Contents

Popular

OpenID connect feature has been integrated into the OAuth flow which is discussed in previous sections.

This feature enables clients to verify the identity of the end-user based on the authentication performed by an Authorization Server as well as to obtain basic profile information about the end-user in a security token represented as JWT which is referred to as ID token in this context. This is the primary extension that OpenID Connect makes to OAuth.

If a client needs the ID token, either the response_type parameter in the request to Authorization endpoint must include "id_token" or the scope must include "openid". This is how a client can rely on Authorization server for the end-user Authentication.

All possible scenarios of obtaining code/token/id_token for different combinations of response_type parameter values that are supported with/without the "openid" in scope within the requests to Authorization and Token endpoints are tabulated as follows:

(tick) - the entity is issued

(error) - the entity is not issued

(minus) - invalid request

Response TypeOpenID in ScopeEndpointCodeAccess TokenID Token
code


Included

Authorization(tick)

(error)

(error)

Token

(error)

(tick)(tick)
Not IncludedAuthorization(tick)

(error)

(error)

Token

(error)

(tick)

(error)

token




Included
Authorization

(error)

(tick)

(error)

Token(minus)(minus)(minus)
Not Included

Authorization

(error)

(tick)

(error)

Token(minus)(minus)(minus)
id_token


Included

Authorization

(error)

(error)

(tick)
Token(minus)(minus)(minus)
Not IncludedAuthorization

(error)

(error)

(tick)

Token(minus)(minus)(minus)
code, id_tokenIncludedAuthorization(tick)

(error)

(tick)
Token

(error)

(tick)(tick)
Not IncludedAuthorization(tick)

(error)

(tick)
Token

(error)

(tick)(tick)
token, id_tokenIncludedAuthorization

(error)

(tick)(tick)
Token(minus)(minus)(minus)
Not IncludedAuthorization

(error)

(tick)(tick)
Token(minus)(minus)(minus)
code, tokenIncludedAuthorization(tick)(tick)

(error)

Token

(error)

(tick)(tick)
Not IncludedAuthorization(tick)(tick)

(error)

Token

(error)

(tick)

(error)

code, token, id_tokenIncludedAuthorization(tick)(tick)(tick)
Token

(error)

(tick)(tick)
Not IncludedAuthorization(tick)(tick)(tick)
Token

(error)

(tick)(tick)

For generating id_token, following might have to be added to the policy configuration:

  1. Basic user information - The end-user information obtained from the resource server should be included as variables in the section of policy configuration attributes, which will then be used by the policy to wrap into additional claims of the id_token.
  2. Private/secret key - The key with which the id_token should be signed while generation. If the algorithm chosen is symmetric, "openid_secret_key" must be fed into context variables. If the algorithm chosen is asymmetric, Private JSON Web Keys and kid value have to be fed into context variables as "JsonWebKeys" and "kid" respectively. The corresponding Public JSON Web Key has to be shared with the client to support the validation of the issued id_token.
  3. Salt - A value that is kept private, not known to the client, which is used in the calculation of the sub claim of id_token.
  4. Issuer - Identifier of the issuer i.e the authorization server playing the role of an OpenID provider. This will be fed into iss Claim value in ID Tokens issued by the Issuer. This value shall also be provided in the OpenID discovery URL.

According to the scenarios mentioned in the table, id_token is generated (based on the request parameters/scope) either at Authorization endpoint or Token endpoint by the respective policies along with code and/or token. The following Claims are present within the ID Token issued:

  • iss
    REQUIRED. Issuer Identifier for the Issuer of the response.
  • sub
    REQUIRED. Subject Identifier. A locally unique identifier for the end-user. This is the value obtained by HS256 hashing of the client's "sector_identifier_uri" or redirect_uri after concatenating it with a salt and the end-user id provided in the policy configuration.
  • aud
    REQUIRED. Audience Identifier. The client_id of the client that the ID Token is intended for.
  • exp
    REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing.
  • iat
    REQUIRED. Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

Additional claims include c_hash and/or at_hash, basic user information.

//openid discovery information url//

Pre-negotiated parameters for the issue of OpenID :

  1. Algorithm (to be negotiated while client registration): Currently supported algorithms are HS256, RS256, and ES256.
    1. For symmetric algorithms, the secret key has to be fed into context variables with the name "openid_secret_key" prior to the policies.
    2. For asymmetric algorithms, the id_token will be signed using a private key and its corresponding public key will be available in openid discovery information url or ///be a part of client subscription form information///
  2. Client Authentication method: This section defines a set of Client Authentication methods that can be used by Clients to authenticate to the Authorization Server when using the Token Endpoint.
    The client authentication methods that are currently supported:
    1. client_secret_basic - Clients that have received a client_secret value from the Authorization Server authenticate with the Authorization Server by sending it as one of the request parameters to the token endpoint.
    2. private_key_jwt - Clients that have chosen this method register a public key with the Authorization Server and sign a JWT with its corresponding private key and delivers that JWT during its authentication.

      When invoking the token endpoint using the POST method, the request MUST include the following parameters along with grant_type, code, client_id:
      • client_assertion_type: This must be set to "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".
      • client_assertion: This must contain the encoded assertion JWT.
        The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values:
        • iss
          REQUIRED. (Issuer) This claim must contain the client_id of the OAuth Client.
        • sub
          REQUIRED. (Subject) This claim must contain the client_id of the OAuth Client.
        • aud
          REQUIRED. (Audience) This claim must contain the value that identifies the Authorization Server as an intended audience. It should be the URL of the Authorization Server's Token Endpoint.
        • jti
          REQUIRED. JWT ID. A unique identifier for the token. This ensures to prevent reuse of the JWT.
        • exp
          REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing.
        • iat
          OPTIONAL. Time at which the JWT was issued.
    During Client Registration, the client may register any one of the above-mentioned Authentication methods. If no method is registered, the default method is client_secret_basic.

Example 

1. Include "id_token" in response_type parameter in order to obtain ID token from Authorization End Point.
2. Include "openid" in scopes section of client subscription in order to obtain ID token from Token End Point.

Sample Response from Token End Point  - JSON payload
{"access_token":"f6066dc10ba961f6bee7ead46226754c","refresh_token":"8194f3f1e4e49a82bdfe3b745ac936fb","sub":"4yP6WA9QWvG5IAI9/hJ2dg==","logonCount":"default","scope":"Read,openid","id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ewogICJzdWIiIDogIjR5UDZXQTlRV3ZHNUlBSTkvaEoyZGc9PSIsCiAgImlzcyIgOiAiRklPUkFOTyIsCiAgImF1ZCIgOiAiRkl5eC1Ta1NIRHNhVUxkZWRtS0RYb2MtIiwKICAiaWF0IiA6IDE1NzA3OTcwNjcwMzIsCiAgImV4cCIgOiAxNTcwNzk3MDY3MDMyLAogICJzaG93IiA6ICJkZWZhdWx0IiwKICAiYWRkaXRpb25hbENsYWltIiA6IHsKICAgICJhdF9oYXNoIiA6ICIrbm1rLzQ5WEIrVjlLblNlU0J1Smh3PT0iLAogICAgImJhc2ljIHVzZXIgaW5mbyIgOiAie1wibG9nb25Db3VudFwiOlwiZGVmYXVsdFwiLFwiZGVzY3JpcHRpb25cIjpcImRlZmF1bHRcIixcInVzZXJJRFwiOlwiZGVmYXVsdFwiLFwic3ViXCI6XCI0eVA2V0E5UVd2RzVJQUk5L2hKMmRnPT1cIn0iCiAgfQp9.-0zplvMEt_ZiVQkH_GniLu6y7vWbS2dHwI8q3Jt3SS8","description":"default","expires_in":300,"userID":"default"}

Adaptavist ThemeBuilder EngineAtlassian Confluence