OpenID Connect Concepts, Flows

What is OpenID Connect
Concepts
OpenID Tokens (Structure)
OIDC Claims OpenID Connect AuthN flows
3- legged authorization grant flow
Implicit Grant Flow
OpenID UserInfo endpoint
OIDC discovery endpoint
REST and JSON Tokens (JSON Web Tokens(JWT) ) Security

OpenID Connect

This article covers the core concepts of OIDC. You dont need to know what these technologies are to understand this article. Follow the sub headings in the article to connect the pieces to see how OIDC artifacts can be used in your business to offer a service to a client. This article starts with concepts, then covers the OIDC artifacts, the structure of JWT tokens used to communicate userinfo to the client ,the user attributes passed as claims and the security around the tokens.

Two flows one is the 3-legged standard authorization flow, and the 2-legged implicit flow.

To better understand how these protocols are implemented on different products, included in this article is the comparison table that gives the reader a birds-eye view of implementation specifics in OpenAM & Oracle Access Manager.

The implementation steps of OIDC using OpenAM sums up the concepts with a walkthrough. The next article will demo those OIDC steps in OpenAM

What is OpenID Connect

Concepts

OIDC is a framework built on top of OAuth 2.0 or is an extension of OAuth. The ID token is used in OIDC to verify the user identity The user information can be accessed from a user token endpoint provided by OIDC implementations. .

OpenID Tokens (Structure)

OIDC token is an extension of tokens generated by OAuth 2.0 scenarios The access tokens and refresh tokens are created in OAuth2.0 interactions.

The ID token created in the OIDC flow, verifies the user information and contains the following claims which can be accessed using an endpoint: subject, issuer, audience, and timestamps.

The names used to access the token attributes are Iss, sub, aud, exp, iat, auth_time, Nonce, acr, amr sid. The iss, sub, aud, exp,iat auth_time and nonce are mandatory fields of the ID token. The other fields are optional. We will see an example of how these values can be retrieved.

The nonce value if present in the initial authentication request should also be in the ID token generated by the authorization servers and the nonce value should not be modified. The client has to verify the nonce value and confirm it has not changed between request and response interactions with an ID token.

OIDC Claims

There are different claims used by OIDC flow, and they are retrieved using the userinfo endpoint. The various claims for the OIDC flow are email, email-verified, name, given_name, family_name, perferred_username, phone, phone_number_verified, gender & locale.

These claims verify the identiy of a logged in user.

OpenID Connect AuthN flows

OIDC flows: Authorization Grant Flow

3 legged authorization grant flow:

1. Clients should register with the authorization server first before making the authorization code flow.
2. In the OIDC authz flow, the Client scope is OpenID, and the response type for this flow is set to grant code.
3. If the scope doesn’t have ‘OPENID’, then it is considered OAuth2.0 flow.
4. The ID_token and Access_token are obtained in exchange for auth code, returned from the server. In the non OIDC flow only Access_token is returned.
5. In this 3 legged flow, the auth server validates the credentials & gets the consent, before giving the authZ code, so that the clients can use to get the access token & Id _token.

In the 3-legged flow, the sequence of execution is below.

1. The user/browser requests access to the resource.
2. The client (RP) makes a OAuth call with the scope as openid, to the authz server.
3. The authz server validates client id & secret and present the credential screen to the RO/user to submit creds.
4. AuthZ validates and then send the consent screen. The user provides consent to the authZ server, then redirects to the client with the code.
5. The RP make a request with the code and other parameter and requests for access token and ID token (openid flow).
6. The authz server validates the code.
7. RP sends a request for the access token, id token and refresh token.
8. Relying party validates the token with authZ sever and request user claims form the userinfo endpoint.

9. The authZ server validate the ID_tok and return user claims.

10. The service provider submits the access tok for resource access.

11. The Resource server validates access token with authZ server and returns the resource, if the token is valid.

Implicit Grant Flow

In this flow, the code is not used to get an access token, whereas the conset and the code is assumed given. The authZ server validated the RO creds and then redirects to the client using the redirect_URI. The client then makes a request to the authZ server token endpoint with the response token _id_token, client id , client secret and the scope as OPENID. If the scope openid is not present, then this is flow is considered normal OAuth authorization flow.

The authZ server, after validating the creds, replies back with id token. The client uses that id_token to get the claims related to the user for the /userinfo endpoint. The authZ server checks to see if the token is valid and then replies with the claims to the client. The claims are send in JWT format with the verified signature.

More on JWT security and signature later in this post.

OpenID UserInfo endpoint

The access token generated has all the scope attached to it. The access token is sent to the user info endpoint to get the claims associated with the user. The scope associated with an access token will define what are the privileges the user has access to or the privileges the user has. The different scopes allowed with OpenIDConnect are the ones below:

Profile -> this scope is associated with the claim, the user endpoint response with the user profile information.
Email — With the email scope, both email and email_verified are sent as responses.
Address — This endpoint sends an address as the response to this claim.
Phone — Both phone and phone_verified are sent as the response to this claim from the user endpoint.
Offline_access: This scope is used when the refresh token is required.

Retrieving values from AM requires mapping the OIDC claims attribute to the AM LDAP store.

You have to create an identity directory service profile store and map the attributes in the LDAP attributes. The attributes claims returned by the user info endpoint cannot be modified. The values to the corresponding attributes in LDAP can be modified.

The example of claim attribute to LDAP mapping is below:

Profile|
Name- > name
Family_name -> lastname
Given_name -> firstname
Preferred_username — The username in LdAP store
Gender -> “ “
Locale -> preferredlanguage
Updated_at -> current time
email Email -> mail
Email_verified -> ‘N’
Phone -> phone
Phone_verified -> ‘Y’
address formatted -> postal address
Formatted address -> postaladdress
Country-> country
State -> region
Postalcode -> postal_code
Sample response of the user profile is
— — — — — — — — — — — —
“profile”: {
“name”: “ mdave”,
“family_name”: “ dave”,
“given_name”: “mat”
“preferred_username”:“m.dave”,
“gender”: “”,“locale”:”en/CA”
“updated_at”:“1409709292742”
}

The user information endpoint curl is :

curl -X GET http://<hostname>:443//am/oauth2/userinfo -H ‘authorization:Bearer <AccessToken>’“profile”: { “name”: “test user1”, “family_name”: “user1”, “preferred_username”: “tuser1”, “locale”: “EN”, “updated_at”: “1614529555621”},”email”: { “email”: “test@gmail.com”, “email_verified”: “Y”}

OIDC discovery endpoint

The OIDC discovery endpoint enables the discovery of OIDC providers, once the handle is obtained for the OIDC provider, then the configuration can be retrieved. The response will be all the claims and any public key information that is being used.

The OpenID connect endpoint discovery is

/oauth2/.well-known/openid-configuration
curl https://am.example.com:8443/am/oauth2/.well-known/openid-configuration
{“request_parameter_supported”:true,
“claims_parameter_supported”:false,
“introspection_endpoint”:”https://am.example.com:443/am/oauth2/introspect",“check_session_iframe”:”https://am.example.com:443/am/oauth2/connect/checkSession",
“scopes_supported”:[
“address”,
“phone”,
“openid”,
“profile”,
“email”
],
…..
}
The other end point to user is the OIDC configuration end point to retrieve the server details which serves the OIDC configuration.

REST and JSON Tokens (JSON Web Tokens(JWT) ) Security

The following are the key identifiers of JWT tokens / REST APIs

1. Rest is lightweight, Mobile friendly.
2. The ID Token is represented by JWT format. JWT uses JSON web signature & JWT keys.
3. JWT is the standard to share claims in a digitally secure way.
4. JWT and OIDC provide a framework for modern single sign-on. OIDC fits the plugin model, it is easy to develop, lightweight, mobile-friendly, secure (JWT), used for federated protocols.
5. The different actors of OIDC are the End-user, Authorization server and Federated (Relying party).
6. To establish SSO with OIDC, using the OIDC APIs, the Relying parties can make calls to authZ server and verify the token (both ID and Access tokens)
7. Along with ID token (short-lived) — you can also get Refresh token (to renew the tokens). Let’s look at a few OIDC endpoints

Let look at a few OIDC endpoints

/authorize — Endpoint client uses to authorize a user, along with getting consent.
/token — Endpoint to request an access token. The client has to provide the code, client id, client secret and scope
/userinfo — Endpoint to get user identity data.
/revoke — Token invalidation endpoint
/keys — Validate the token endpoint and obtain public certificates.

JSON Web Token (JWT token structure)

JWT has the following structure.

JWT header.payload.signature
Header — Contains the algorithm to verify digital sig.
Payload — has the user data
Signature — For integrity to trust the contents.
Example JWT token with a header, payload and signature.

{“typ”: “JWT”, ““alg”: “S256”}.
{ “sub”: “84gsdfgdfgdfgfd09”,
“name”: “Mat Tomcat”,
“iss”: “https://am.example.com",
“aud”: “00iwerewiiwerew65”,
“iat”: 1667276540,
“exp”: 1557282141,
“preferred_username”: “mat@deviam.com”,
“given_name”: “Mtomcat”,
“family_name”: “Tomcat”}.

Below are the description of the JWT token claims.

Iss — Issuer — Authorization URL
Iat : The token issue time.
Sub — The end-user ID
Aud — The service provider (RP) Identifier.
Name — User Identity displayname
Preferred_username — Username used by the applicaiton (App specific)
Exp — Expiration timestamp in (unix time format)

The claims of the ID token can be mapped to the entry of an users identity card issued by an approving authority.

The signature of the JWT token is the combination of the

SHA (Algorithm + privatekey + header+”.”+ payload)

And is signed by the authorization server. The validation of the signature is done using the public key.

SHA (Algorithm + publickey + header+”.”+ payload, valid(signature)) = true
The principle of OAuth is the Authorization server providing access to resources in a secure transaction based on security tokens. Once access to the resource is established, then all the resources within that scope can be accessed using the same token.
To verify the identity of the user the application can use the OIDC user info endpoint. To access the identity token the id_token is used. The OAuth and OIDC discovery document endpoint provide the metadata about the Authorization Server for auto-discovery.
http://url/.well-know/openid-configuation. This endpoint returns the endpoints for token, authoriz, userinfo, clients and public certificates. The other information returned by the meta discovery document is response_types supported and the grant_types supported.

The metadata provides information to the relying party application as to what scopes and tokens are supported by the authorization servers.

OAuth Tokens are short-lived, used to access resource APIs, can be used by both Trusted and untrusted apps & use JWT token format. JWS. Token can be used to get minimal data and full profile with all the required data.

The following steps are executed in the ID token verification.

1. JWS signature verification.
2. Verify issuer to match URI of authorization server
3. Aud is the OIDC application -Verify
4. Exp date has not passed.
5. The nonce value in the request matches one send to authZ server in the earlier interaction.
6. State value matches the one sent previously to the authZ server.

Configuring OpenID Connect 1.0 (AM 6. OIDC1 guide)

You can customize OIDC and inject specific attributes as the response to an OIDC request. Follow the steps on the OpenAM console

Log in to AM as amadmin (Admin)
Click Realms > Top Level Realm > Configure OAuth Provider > Configure OpenID Connect.
Accept the default values and then click Create on the Configure OpenID Connect page,.
Choose Realms > Top Level Realm > Services, click OAuth2 Provider, and verify that the value for OIDC Claims Script is the default script, OIDC Claims Script.
Register the oidcDemoTest client.
Log in to AM as amadmin.
Choose Realms > Realm Name > Applications > OAuth 2.0.
On the Clients tab, select Add Client. Enter an ID for the client, such as oidcDemoTest, provide a secret, and then click Create.
On the OAuth 2.0 client page:
a. On the Core tab, in Scope(s), enter both profile and openid
The profile scope will return details about the subject such as given name and timezone.
The openid scope indicates this is an OpenID Connect client.
b. On the Advanced tab, in Redirection URIs, enter an example URI such as http://www.sample.com/info.jsp
c. In Display name, enter the name of the client as it will be displayed on the consent page, for example OIDC Claims Script Client. Save work and Test after logout.
For example: http://am.amexample.com:8080/openam/oauth2/realms/root/authorizeclient_id=oidcDemoTest&redirect_uri=http://www.sample.com/info.jsp&response_type=code&scope=openid profile

This article covered the OIDC concepts, 3-legged and the 2-legged flows. It discussed how JWT is used to transfer claims in a web interaction and explained the security used in JWT.

Other topics covered are the discovery endpoints for checking the OIDC metadata and how it can be implemented in OpenAM.