Skip to main content

Endpoint reference

All paths are relative to the site root.

EndpointMethodPath
DiscoveryGET/wenisch-tech/keystone-oidc/.well-known/openid-configuration
AuthorizationGET / POST/wenisch-tech/keystone-oidc/oauth/authorize
TokenPOST/wenisch-tech/keystone-oidc/oauth/token
UserInfoGET/wenisch-tech/keystone-oidc/oauth/userinfo
JWKSGET/wenisch-tech/keystone-oidc/oauth/jwks

For clients that derive Keycloak-style paths, /protocol/openid-connect/auth, /token, /userinfo and /certs are routed to the same handlers. They aren't advertised in discovery; new clients should use the discovery document.

Discovery​

{
"issuer": "https://example.com/wenisch-tech/keystone-oidc",
"authorization_endpoint": "https://example.com/wenisch-tech/keystone-oidc/oauth/authorize",
"token_endpoint": "https://example.com/wenisch-tech/keystone-oidc/oauth/token",
"userinfo_endpoint": "https://example.com/wenisch-tech/keystone-oidc/oauth/userinfo",
"jwks_uri": "https://example.com/wenisch-tech/keystone-oidc/oauth/jwks",
"scopes_supported": ["openid", "profile", "email", "roles"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"id_token_signing_alg_values_supported": ["RS256"],
"token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
"code_challenge_methods_supported": ["S256", "plain"]
}

Authorize​

ParameterRequiredDescription
response_typeyesMust be code
client_idyesThe client's ID
redirect_uriyesExact match of a registered URI
scopeyesSpace-separated, must include openid
staterecommendedEchoed back, protects against CSRF
noncerecommendedIncluded in the ID token
code_challengepublic: yesBase64url challenge, 43-128 characters
code_challenge_methodpublic: S256S256 or plain (confidential clients only)

Token​

Client authentication. Confidential clients must send one of:

  • Authorization: Basic base64(urlencode(client_id):urlencode(client_secret))
  • client_id and client_secret in the POST body

Public clients send only client_id.

Authorization code grant (grant_type=authorization_code):

ParameterRequiredDescription
codeyesCode from the authorize endpoint
redirect_uriyesSame value as in the authorize request
client_idyesNot needed when sent through Basic auth
code_verifierPKCERequired when a code_challenge was used, and always for public clients

Refresh token grant (grant_type=refresh_token): send refresh_token and client_id. Confidential clients authenticate as above.

Response:

{
"access_token": "<JWT>",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "<JWT>",
"refresh_token": "<opaque string>",
"scope": "openid profile email"
}

Errors:

ErrorStatusCause
invalid_client401Unknown client, or a confidential client without valid credentials
invalid_request400For example a client_id mismatch between header and body
invalid_grant400Bad, expired or reused code; redirect URI mismatch; missing or wrong code_verifier
unsupported_grant_type400Only authorization_code and refresh_token are supported

UserInfo​

Send Authorization: Bearer <access_token>. The response contains the claims for the granted scopes. See Scopes and claims.

JWKS​

Returns the public RSA key in JWKS format for verifying RS256 tokens.