Standard and Custom OAuth 2.0 and OpenId Connect Endpoints

Authway supports the following standard and custom OAuth 2.0 and OpenId Connect endpoints:

Endpoint Description
Discovery Exposes metadata about the OAuth 2.0 and OpenId Connect endpoints, capabilities and extensions.
JWK set Get the published JSON Web Key (JWK) set to verify the signature of an issued token or to encrypt request objects that is passed to the server.
Authorization Authenticate the end-user by sending their browser to the authorization endpoint.
Pushed Authorization Request (PAR) Pass the request parameters in a backchannel directly to the server before sending the user’s browser to the authorization endpoint.
Token Pass an OAuth 2.0 grant, such as code, refresh token or client credentials, to get an Id token and/or access token.
Token introspection Validate and get the real access token for a reference token.
Token revocation Revoke a refresh or access token.
UserInfo Fetch user information that is not in the token.
Check Session iframe Check the identity provider for changes of the end-user authentication.
Logout (end-session) Sign-out the end-user by sending their browser to the logout endpoint.
Scope introspection Custom endpoint that allows a client or API resource to fetch extra scopes for a user through a backchannel.

Subsections of Standard and Custom OAuth 2.0 and OpenId Connect Endpoints

Discovery Endpoints

Overview

The Discovery Endpoint (also called the OpenID Provider Configuration Document) is defined in the OpenID Connect Discovery specification.

It provides a JSON document at a well-known location that describes the Identity Provider’s (IdP’s) capabilities and endpoints. Clients (RPs) can use this to automatically configure themselves instead of requiring manual configuration of URLs and supported features.

Endpoint

GET https://[BASE_URL]/.well-known/openid-configuration

Response

The response is a JSON object containing metadata about the IdP. Example:

{
   "issuer": "https://[BASE_URL]",
   "authorization_endpoint": "https://[BASE_URL]/connect/authorize",
   "token_endpoint": "https://[BASE_URL]/connect/token",
   "userinfo_endpoint": "https://[BASE_URL]/connect/userinfo",
   "end_session_endpoint": "https://[BASE_URL]/connect/endsession",
   "jwks_uri": "https://[BASE_URL]/.well-known/openid-configuration/jwks",
   "check_session_iframe": "https://[BASE_URL]/connect/checksession",
   "introspection_endpoint": "https://[BASE_URL]/connect/introspect",
   "revocation_endpoint": "https://[BASE_URL]/connect/revocation",
   "scopes_supported": ["openid", "profile", "email"],
   "response_types_supported": ["code", "id_token", "token id_token"],
   "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
   "subject_types_supported": ["public", "pairwise"],
   "id_token_signing_alg_values_supported": ["RS256"],
   "claims_supported": ["sub", "name", "email", "email_verified"]
}

Usage

  1. Client retrieves configuration at startup:

    HTTP GET https://[BASE_URL]/.well-known/openid-configuration

  2. Client dynamically discovers the necessary endpoints and metadata:

  • Authorization Endpoint
  • Token Endpoint
  • UserInfo Endpoint
  • End Session Endpoint
  • Check Session IFrame
  • Supported scopes, response types, and signing algorithms
  1. Client uses the JWKS URI (jwks_uri) to fetch public keys for verifying ID Tokens.

Security Considerations

  • Validate that the issuer field matches the expected IdP issuer.
  • Cache discovery results for efficiency, but refresh periodically to catch configuration changes.

JWK Set

Overview

The JSON Web Key Set (JWKS) URI provides the public keys used by the Identity Provider (IdP) to sign tokens (e.g., ID Tokens, Access Tokens if JWTs).

Clients (RPs) retrieve the JWKS document to validate signatures on tokens, ensuring authenticity and integrity.

Endpoint

The endpoint is advertised in the jwks_uri in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/.well-known/openid-configuration/jwks

Response

The response is a JSON object containing an array of public keys. Example:

{
   "keys": [
     {
       "kty": "RSA",
       "kid": "1b94c",
       "use": "sig",
       "alg": "RS256",
       "n": "vrjOf...",
       "e": "AQAB"
     },
     {
       "kty": "EC",
       "kid": "5df2a",
       "use": "sig",
       "alg": "ES256",
       "crv": "P-256",
       "x": "f83OJ3...",
       "y": "x_FEzRu..."
     }
   ]
}

Usage

  1. Retrieve JWKS:
GET https://[BASE_URL]/.well-known/openid-configuration/jwks

  1. Select Key by kid:
    Tokens (e.g., JWTs) include a kid (Key ID) in their header. The RP uses this value to find the correct key from the JWKS.

  2. Verify Signature:
    The RP uses the key to validate the token’s signature and ensure it was issued by the IdP.

Security Considerations

  • Validate that keys come from a trusted jwks_uri discovered via .well-known/openid-configuration.
  • Cache keys, but refresh periodically, since IdPs rotate signing keys.

Authorization Endpoint

Overview

The Authorization Endpoint is the starting point for OAuth 2.0 and OpenID Connect flows. It handles user authentication and authorization, and issues an authorization code, implicit tokens, or an ID Token, depending on the flow.

Clients redirect the user’s browser to this endpoint with the appropriate query parameters. After the user authenticates (and consents if required), the IdP redirects the browser back to the client with the authorization response.

Endpoint

The endpoint is advertised in the authorization_endpoint in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/authorize

Parameters

Parameter Required Description
response_type Yes Defines which flow to use (code, id_token, token, or a combination).
client_id Yes The client identifier registered with the IdP.
redirect_uri Yes Where the user should be redirected after authentication. Must be pre-registered.
scope Yes Space-delimited list of scopes. Must include openid for OpenID Connect requests.
state Recommended Opaque value used to maintain request state and prevent CSRF. Returned unchanged in response.
nonce Required for id_token String used to associate client session with ID Token to prevent replay attacks.

All parameters are documented here.

Usage

  1. Redirect User:
    The RP builds an authorization request and redirects the user’s browser to the IdP:
https://idp.example.com/authorize?
   response_type=code&
   client_id=my-client-id&
   redirect_uri=https%3A%2F%2Frp.example.com%2Fcallback&
   scope=openid%20profile%20email&
   state=xyzABC123&
   nonce=abc987

  1. User Authenticates:
    The IdP authenticates the user.

  2. Redirect Back:
    The IdP redirects the user’s browser back to the RP with an authorization response. Example (Authorization Code Flow):

https://rp.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyzABC123

Security Considerations

  • Always validate state to protect against CSRF.
  • Always use nonce when requesting id_token.
  • Use response_type=code with PKCE for public clients (e.g., SPAs, mobile apps).

Pushed Authorization Request (PAR) Endpoint

Overview

The Pushed Authorization Request (PAR) Endpoint allows clients to securely push authorization request parameters directly to the Identity Provider (IdP) via a backchannel POST request.

Instead of sending all authorization parameters in the front-channel (via the browser), the client sends them to the IdP in advance. The IdP returns a short-lived request_uri reference. The client then uses this request_uri in the front-channel redirect to the Authorization Endpoint.

This improves security (no long query strings, prevents tampering) and reliability (handles large requests). The use of PAR is encouraged by the FAPI working group within the OpenID Foundation. For example, the FAPI2.0 Security Profile requires the use of PAR. This security profile is used by many of the groups working on open banking (primarily in Europe), in health care, and in other industries with high security requirements.

Endpoint

The endpoint is advertised in the pushed_authorization_request_endpoint in the metadata exposed by the discovery endpoint and typically is:

POST https://[BASE_URL]/connect/par

Parameters (form-encoded)

All parameters normally passed to the Authorization Endpoint (response_type, client_id, redirect_uri, scope, state, nonce, etc.) must be included in the PAR request.

Parameter Required Description
response_type Yes Defines the flow (code, id_token, etc.).
client_id Yes The client identifier registered with the IdP.
redirect_uri Yes Must match a registered redirect URI.
scope Yes Scopes requested (openid required for OIDC).
state Recommended Opaque value for request correlation/CSRF protection.
nonce Required for id_token requests Protects against replay attacks.

Full documentation of all authorization parameters can be found here.

Authentication

  • Confidential clients authenticate (e.g., HTTP Basic Auth or private_key_jwt).
  • Public clients may use PKCE (Proof Key for Code Exchange).

Response

A successful response returns JSON with a request_uri and its lifetime (expires_in):

{
   "request_uri": "urn:ietf:params:oauth:request_uri:1a2b3c4d",
   "expires_in": 90 
}

Usage Flow

  1. Push Authorization Request:
POST /par 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic base64(client_id:client_secret)  

response_type=code& client_id=my-client-id& 
    redirect_uri=https%3A%2F%2Frp.example.com%2Fcallback& 
    scope=openid%20profile& 
    state=xyz123& 
    nonce=abc987

  1. Receive request_uri:
    The IdP returns a short-lived request_uri.

  2. Redirect User to Authorization Endpoint:
    Instead of passing full parameters, the RP redirects the user with only:

https://[BASE_URL]/connect/authorize?client_id=my-client-id&request_uri=urn:ietf:params:oauth:request_uri:1a2b3c4d

  1. IdP Resolves Request:
    The IdP looks up the pushed request parameters, authenticates the user, and continues the flow as normal.

Security Considerations

  • Prevents exposure of sensitive parameters in browser history, logs, or query strings.
  • Ensures integrity of the authorization request (cannot be modified in transit).
  • Short-lived request_uri values mitigate replay attacks.
  • Clients should never log or store request_uri values beyond their lifetime.

Token Endpoint

Overview

The Token Endpoint is used by clients to exchange an authorization code, refresh tokens, or client credentials for OAuth 2.0 tokens (Access Token, Refresh Token, and optionally an ID Token).

It is typically called by back-end components (not the browser) using HTTPS POST requests.

Endpoint

The endpoint is advertised in the authorization_endpoint in the metadata exposed by the discovery endpoint and typically is:

POST https://[BASE_URL]/connect/token

Parameters (form-encoded)

Parameter Required Description
grant_type Yes The grant type (authorization_code, refresh_token, client_credentials, etc.).
code Required for authorization_code The authorization code received from the Authorization Endpoint.
redirect_uri Required for authorization_code Must match the original redirect_uri used in the request.
client_id Required (if not using client authentication header) The client identifier.
client_secret Required (for confidential clients) The client’s secret.
code_verifier Required for PKCE The original code verifier for PKCE-enabled flows.
refresh_token Required for refresh_token grant The refresh token issued earlier.

Response

Successful responses are JSON objects containing issued tokens, for example:

{
   "access_token": "SlAV32hkKG",
   "token_type": "Bearer",
   "expires_in": 3600,
   "refresh_token": "8xLOxBtZp8",
   "id_token": "eyJhbGciOiJSUzI1..." 
}

Usage (Authorization Code Flow with PKCE)

  1. Obtain Authorization Code:
    From the Authorization Endpoint.

  2. Send Token Request:

HTTP POST /token
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic base64(client_id:client_secret)
 grant_type=authorization_code&
 code=SplxlOBeZQQYbYS6WxSbIA&
 redirect_uri=https%3A%2F%2Frp.example.com%2Fcallback&
 code_verifier=abcdef123456
  1. Receive Tokens:
    The IdP responds with an Access Token, ID Token (if OIDC), and optionally a Refresh Token.

Security Considerations

  • Never expose client_secret in public clients (use PKCE instead).
  • Validate all tokens received (signature, expiration, audience, nonce).

Token Introspection Endpoint

Overview

The Introspection Endpoint is defined in RFC 7662. It allows APIs (or clients) to query the IdP about the active state of an OAuth 2.0 token (Access Token or Refresh Token). Refresh tokens can only be introspected by the client that requested them.

This endpoint is useful for APIs that need to validate whether a token is still valid, and to obtain metadata about the token (e.g., scope, expiration, subject).

Endpoint

The endpoint is advertised in the introspection_endpoint in the metadata exposed by the discovery endpoint and typically is:

POST https://[BASE_URL]/connect/introspect

Parameters (form-encoded)

Parameter Required Description
token Yes The token to be introspected.
token_type_hint Optional A hint about the type of token (access_token or refresh_token).

Authentication

The introspection endpoint requires authentication. Since the request to the introspection endpoint is typically done by an API, which is not an OAuth client, the ApiResource is used to configure credentials. For a client the configured credentials of the client is used.

Response

Successful responses are JSON objects. If the token is active:

{
   "active": true,
   "scope": "openid profile email",
   "client_id": "my-client-id",
   "username": "alice",
   "token_type": "access_token",
   "exp": 1699999999,
   "iat": 1699990000,
   "sub": "6b3d5b7b-867b-4e34-98df-f1c8a9af37b9",
   "aud": "api.example.com",
   "iss": "https://[BASE_URL]" 
}

Unknown or expired tokens will be marked as inactive::

{
   "active": false 
}

Usage Example

HTTP POST /introspect 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic base64(api_resource:api_resource_secret)  

token=[token]&token_type_hint=access_token

Return JWT Instead of JSON

Authway supports RFC 9701 to return a JWT response from the introspection endpoint.

To return a JWT response, set the Accept header in the HTTP request to application/token-introspection+jwt:

HTTP POST /connect/introspect
Accept: application/token-introspection+jwtAuthorization: 
Authorization: Basic base64(api_resource:api_resource_secret)  

token=[token]

A successful response will return a status code of 200 and has a Content-Type: application/token-introspection+jwt header, indicating that the response body contains a raw JWT instead. The base64 decoded JWT will have a typ claim in the header with the value token-introspection+jwt. The token’s payload contains a token_introspection JSON object similar to the default response type:

{
  "alg": "RS256",
  "kid": "BE9D78519A8BBCB28A65FADEECF49CBC",
  "typ": "token-introspection+jwt"
}.{
  "iss": "https://localhost:5001",
  "iat": 1729599599,
  "aud": "api1",
  "token_introspection": {
    "iss": "https://localhost:5001",
    "nbf": 1729599599,
    "iat": 1729599599,
    "exp": 1729603199,
    "aud": [ "api1" ],
    "client_id": "client",
    "jti": "44FD2DE9E9F8E9F4DDD141CD7C244BE9",
    "active": true,
    "scope": "api1"
}}.[Signature]

Token Revocation Endpoint

Overview

The Revocation Endpoint is defined in RFC 7009. It allows clients to notify the IdP that a previously issued Refresh Token or Access Token is no longer needed.

Revocation helps ensure tokens cannot be misused if they are leaked or when a session ends.

Endpoint

The endpoint is advertised in the revocation_endpoint in the metadata exposed by the discovery endpoint and typically is:

POST https://[BASE_URL]/connect/revocation

Parameters (form-encoded)

Parameter Required Description
token Yes The token to revoke (Access or Refresh Token).
token_type_hint Optional A hint about the type of token (access_token or refresh_token).

Authentication

  • The client must authenticate (e.g., Basic Auth with client_id and client_secret).

Response

  • A successful revocation request returns HTTP 200 OK with an empty body.
  • Even if the token is invalid or already revoked, the IdP returns 200 OK (to prevent token probing).

Usage Example

POST /connect/revocation
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic base64(client_id:client_secret)  

token=8xLOxBtZp8&token_type_hint=refresh_token

Security Considerations

  • RPs should clear local session data after revoking tokens.

UserInfo Endpoint

Overview

The UserInfo Endpoint is defined in the OpenID Connect Core specification. It returns claims about the authenticated end-user, given a valid Access Token obtained via OpenID Connect.

It allows clients to retrieve claims (e.g., sub, name, email).

Endpoint

The endpoint is advertised in the userinfo_endpoint in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/userinfo

Authentication

  • Requires an Access Token issued for the openid scope.
  • The token is sent in the Authorization header:

Authorization: Bearer SlAV32hkKG

Response

A successful response is a JSON object containing user claims. Example:

{
   "sub": "6b3d5b7b-867b-4e34-98df-f1c8a9af37b9",
   "name": "Alice Adams",
   "given_name": "Alice",
   "family_name": "Adams",
   "preferred_username": "[email protected]",
   "email": "[email protected]",
   "email_verified": true 
}

Usage Example

GET /connect/userinfo
Authorization: Bearer SlAV32hkKG

Security Considerations

  • Clients should request only the scopes they need (profile, email, phone, address) to avoid unnecessary data exposure.

Check Session iframe

Overview

The Check Session IFrame endpoint allows relying parties (RPs) to detect changes in the user’s authentication state at the Identity Provider (IdP). It is defined by the OpenID Connect Session Management specification. RPs embed this endpoint in a hidden <iframe> within their application. The RP can then periodically send postMessage requests to the iframe to check whether the user’s session at the IdP is still valid.

Another option to silently check that a user is stilled signed in is by making an authentication request with prompt=none parameter. This will return a new ID token without user interaction, unless the user is no longer authenticated.

Endpoint

The endpoint is advertised in the check_session_iframe in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/checksession

Parameters

This endpoint does not accept query parameters directly. Instead, communication happens through HTML5 postMessage between the RP’s hidden iframe and the IdP’s check session iframe.

Usage

  1. Obtain session_state:
  • When the RP receives an authorization response from the IdP, it will include a session_state value.
  • The RP stores this value for use in session checking.
  1. Embed the iframe:
    <iframe id="op-iframe"
            src="https://[BASE_URL]/connect/checksession"
            style="display:none;">
    </iframe>
  1. Send Messages:
  • The RP periodically (e.g., every few seconds) sends a message via postMessage to the iframe in the form:
client_id session_state
  • Example in JavaScript:
var iframe = document.getElementById("op-iframe").contentWindow; 
var clientId = "my-client-id"; 
var sessionState = "abc123xyz"; // from IdP authorization response 
setInterval(function() {
     iframe.postMessage(clientId + " " + sessionState,
                        "https://[BASE_URL]"); 
}, 5000);
  1. Receive Responses:

  • The IdP responds back to the RP window with one of the following values:

    • "unchanged" – The session is still valid.
    • "changed" – The session has changed (e.g., user logged out at IdP).
    • "error" – Invalid message format or unrecognized client.

  • Example listener:

window.addEventListener("message", function(e) {
     if (e.origin !== "https://[BASE_URL]") return;
     if (e.data === "changed") {
         // Trigger RP logout or silent reauthentication
     }
}, false);

Security Considerations

  • Always validate the origin of the postMessage to ensure it matches the IdP domain.
  • The iframe should never be visible to end users.
  • Applications should define a clear flow for handling "changed" responses (e.g., logout the user, refresh tokens, or re-initiate login).

Logout (End Session) Endpoint

Overview

The End Session Endpoint allows relying parties (RPs) to sign the user out of the Identity Provider (IdP) and, optionally, to perform Single Logout (SLO) across multiple clients.

The RP can redirect the user’s browser to this endpoint to terminate the IdP session. The IdP will then clear its authentication state and optionally redirect the user back to a specified post-logout URL.

Endpoint

The endpoint is advertised in the end_session_endpoint in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/endsession

Parameters

Parameter Required Description
id_token_hint Recommended The ID Token previously issued by the IdP. Helps the IdP identify the RP and user session to sign out.
post_logout_redirect_uri Optional URL to which the IdP should redirect the user after logout. Must be pre-registered with the IdP.
state Optional Opaque value used by the RP to maintain state between the logout request and response. Returned to the RP in the redirect.

Usage

  1. Obtain id_token_hint:
    When the RP authenticates the user via the Authorization Endpoint, it receives an ID Token. This token is typically passed as the id_token_hint when initiating logout.

  2. Redirect the User to Logout Endpoint:
    Example redirect:

https://idp.example.com/logout?id_token_hint=eyJhbGciOi...&
   post_logout_redirect_uri=https%3A%2F%2Frp.example.com%2Flogout%2Fcallback&
   state=abc123
  1. IdP Terminates Session:
  • The IdP clears its authentication session.
  • If post_logout_redirect_uri is provided and valid, the IdP redirects the user’s browser to that URI.
  • The state parameter (if provided) is appended to the redirect.
  1. RP Handles Post-Logout Redirect:
  • The RP should validate the state value if it was sent.
  • Example redirect URL received by the RP:
https://rp.example.com/logout/callback?state=abc123

Security Considerations

  • post_logout_redirect_uri must be registered with the IdP to prevent open redirect attacks.
  • Passing id_token_hint helps ensure logout applies to the correct user and RP session.
  • The RP should clean up its own local session in addition to triggering IdP logout.

Custom Scope Introspection Endpoint

Overview

The scope introspection is a custom endpoint that Authway supports.

Tokens (both ID token and access token) can become large when they contain many claims and there are good reasons for keeping them small. For access tokens one solution is to use reference token.

Another challenge with tokens is that their content often is static after the creation. This can become a problem especially for long-lived tokens. For user permissions this is often not desirableand the change must take effect before the lifetime of the token has expired.

Authway therefor exposes the scope introspection endpoint that allows an API (or client) to fetch both updated and new claims from the IdP.

Endpoint

The endpoint is advertised in the scope_introspection_endpoint in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/scope/introspect

Parameters (form-encoded)

Parameter Required Description
sub Yes The unique identity of the user sub.
scope Optional Space-delimited list of scopes. If not passed Authway will return claims for the perms scope. Only identity scopes are allowed and not API scopes.
tid Optional The unique identity of the tenant.

Authentication

  • The API (or client) must authenticate (e.g., Basic Auth or in the body, with Api resource and api_resource_secret or client_id and client_secret).

Response

A successful response is a JSON object containing user claims. Example:

{
   "sub": "6b3d5b7b-867b-4e34-98df-f1c8a9af37b9",
   "name": "Alice Adams",
   "given_name": "Alice",
   "family_name": "Adams",
   "preferred_username": "[email protected]",
   "email": "[email protected]",
   "email_verified": true 
}

Usage Example

GET /connect/scope/introspect
Authorization: Basic base64(api_resource:api_resource_secret)

sub=6b3d5b7b-867b-4e34-98df-f1c8a9af37b9&scope=profile perms

Security Considerations

  • APIs and Clients should request only the scopes they need (profile, email, phone, perms) to avoid unnecessary data exposure.
  • Only clients will have configuration for allowed scopes, which effectivly means that an API resource can request any scopes.