Authorization endpoint

The Authorization Endpoint performs Authentication of the End-User. This is done by sending the User Agent to the Identify OAuth 2.0 authorization server's Authorization Endpoint for Authentication and Authorization, using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect.

Request URL:

https://identify.safewhere.com/runtime/oauth2/authorize.idp

prompt parameter

The prompt parameter specifies whether the Identify Server prompts the End-User for reauthentication and consent. The defined values are:

  • none: The possible workflows are:
    • If End-user is not already authenticated in yet, the login_required error would be responded.
    • If End-user is already authenticated but its corresponding client is not configured with appropriate consents, the interaction_required error would be responded.
    • If End-user is already authenticated with appropriate consents, but id_token_hint is missing, the login will be proceeded successfully.
    • If End-user is already authenticated with appropriate consents, but id_token_hint is invalid, the login_required error would be responded.
  • login: The Identify server prompts the End-User for reauthentication even if he has already authenticated.
  • consent: The Identify server prompts the End-User for consent before returning information to the Client. If it cannot obtain consent, it returns a consent_required error.

request and request_uri parameter

You can visit here to see how it works.

WHR parameter

The whr parameter specifies what Identity Provider the OAuth 2.0/OIDC application would like to use. You can visit here to know how it works.

Note: You need to add the Whr paramater Home Realm Discovery rule on the Choose the HRD rules and the order that you want them to run dropdown list found on the Home Ream Discovery tab of the OAuth 2.0/OIDC application.

Step-up support

In basic API authorization scenarios, an authorization server selects the appropriate authentication method for a request based on factors such as the requested scopes, the resource being accessed, the client's identity, and other predefined characteristics.

However, this method can be insufficient in certain situations. For example, a resource server might need different levels of authentication strength depending on whether a specific threshold is exceeded. This threshold is dynamically assessed by the resource server using internal logic that is not visible to the authorization server.

To address these challenges, Identify introduced the step-up feature, which works with OIDC applications using the acr_values and max_age parameters in the authorization request.

acr_values
OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference.

The Authentication Context Class (acr_values) used during authentication is included as the acr claim in the access token and ID token, as specified in Section 2.

Identify OAuth 2.0 supports the max_age parameter in the authorization request as specified in RFC 9470:

max_age
The "max_age" parameter specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by Identify. If the elapsed time is greater than this the max_age value, the client MUST attempt to actively re-authenticate the End-User. 

When the max_age parameter is used, the returned access token and ID token MUST include an auth_time claim. The Auth_time in the access token and the ID token is a JSON numeric value representing the number of seconds since 1970-01-01T00:00:00Z (UTC) until the date and time the token was issued.

{
    "sub": "admin",
     ...
    "arc": "urn:dk:gov:saml:attribute:AssuranceLevel:3",
    "auth_time": 1702280033,
    ...
    "azp": "webmvc_codeflow_id",
    "iat": 1730391105,
    "nbf": 1730391105,
    "exp": 1766391105,
    "iss": "https://identify01.identify.safewhere.com/runtime/oauth2"
}

Resource parameter

In requests to the authorization server, a client MAY indicate the protected resource it is requesting access to by including the following parameter in the request.

resource
OPTIONAL. Indicates the target service or resource to which access is being requested. Its value MUST be an absolute URI. The URI MUST NOT include a fragment component. It SHOULD NOT include a query component. Its value must be one of the configured Security token audiences. Multiple resource parameters MAY be used to indicate that the requested token is intended for multiple resources.

If the request includes a resource parameter, the resulting JWT access token's aud claim SHOULD have the same value as the resource parameter in the request.

Enhance authentication request security

Revoke all issued tokens upon reuse of an authorization code

As clarified in the specification, an authorization code must not be used more than once. If an authorization code is reused, all associated tokens (both the access token and the related refresh token) will be revoked.

In addition, the Identify's userinfo endpoint will reject the request if it is submitted with a revoked access_token.