1. Administering Oracle Access Management
  2. Managing the Oracle Access Management OAuth Service and OpenIDConnect
  3. Understanding OpenIDConnect
  4. OpenIDConnect Authentication Flows in Oracle Access Manager

40.4 OpenIDConnect Authentication Flows in Oracle Access Manager

OpenIDConnect server performs authentication to login as user or to verify the login status of the user and securely sends the result to the Client.

The authentication flows determine how the ID Token and Access Token are returned to the Client. Before processing a request, the client applications need to have an existing registration with the OAuth and OpenIDConnect servers. See Clients and Creating a Client .

Oracle Access Manager supports OpenIDConnect with the following 3-legged authentication flows:

  • Authorization Code Grant Flow

  • Implicit Grant Flow

The important parameters used in the curl command for OpenIDConnect Authentication Flows are:

Table 40-4 Parameters used in the curl command for OpenIDConnect Authentication Flows

Field Description Type Required/Optional

client_id

Id of the client making the request.

string

Required

scope

OpenIDConnect requests MUST contain the "openid" scope value. If not present but other scopes are present, it is treated as a normal OAuth request flow where the scope parameter is not mandatory.

string

Required

redirect_uri

Redirect URI registered with the client, to which the response will be sent.

string

Required

response_type

Indicating the type of request (Valid values - code, token, id_token, token id_token)

string

Required

state

Not mandatory but recommended to maintain state between the request and callback.

string

Recommended

nonce

The value used to associate a Client session with an ID Token, and to mitigate replay attacks.

String

Required for implicit flows

See OpenIDConnect Core 1.0 .

This section describes the following topics:

40.4.1 Understanding Authorization Code Grant Authentication Flow

When using the Authorization Code Grant Flow, the response_type parameter is set to code and all tokens are returned from the Token Endpoint. In this authentication flow, the authZcode is returned to the client. With the authZcode, the client makes a request to the token endpoint and receives the access and identity tokens.

The Authorization Code Grant Authentication Flow, at a high level, is described as follows:

  1. Client prepares an authentication request containing the desired request parameters such as scope and response_type and sends it to the OAM authorization server.

  2. OAM authorization server authenticates the user and obtains user’s consent to access protected resources.

  3. The OAM server sends the Authorization Code (authZcode) to the Client.

  4. Client sends the authZcode to the Token Endpoint and exchanges it for an ID Token and an Access Token directly. The response body contains both the tokens.

    Note:

    Note: For non-OpenIDConnect flows, only the Access Token is returned.

  5. Client validates the ID token and retrieves the User's Subject Identifier.

Note:

Identity token is returned only for the OpenIDConnect flow i.e., when the request contains "openid" keyword in the scope parameter. When the keyword is missing in the scope, it is considered as a normal OAuth - Authorization Code Flow that returns only the access token.

Mandatory parameters in a request include the following:

  • client_id: Id of the client making the request

  • scope: OpenIDConnect requests must contain the keyword openid in the scope parameter. When openid scope is not present and other scopes are defined, then the authentication flow is treated as a pure OAuth request flow.

    • Consider a scenario where the scopes requested are not registered with the client. In a 3-legged flow, when a client requests for valid scopes that were not registered with the client, authZcode is created if the user gives the consent. For example, a Resource Server has three scopes: scopeA, scopeB, and scopeC where only scopeA is registered with the client. During an Authorization code or Implicit grant authentication flow, the client requests for scopeB and scopeC. The consent page is displayed to the user as the scopes requested are valid but not registered with the client. Upon obtaining user’s consent, the code is created for or the token is generated in Implicit flows.

    • Consider a scenario where no scope is passed in the request: When no scope is passed in the request, the default scope registered with the client is used to generate the AuthZcode and Access token eventually. Thus is a pure OAuth flow where the scope parameter is not mandatory.

  • redirect_uri: Redirect URI registered with the client, to which the response will be sent.

  • response_type: Indicating the type of request; valid values include code, token, id_token, and token id_token)

  • state: Not mandatory but recommended to maintain state between the request and callback.

  • response_mode: Optional. Determines how the Authorization Server returns result parameters from the Authorization Endpoint.

For an Authorization Code Grant Authentication flow, the server returns the Access token where the response_type parameter value is code as shown in the following table:

Table 40-5 Authorization Code Grant Authentication flow: Parameters and Access tokens

Parameter value Tokens returned Sample Request (with openid scope) Sample Response

response_type=code

Access Token

Identity Token

http://host2:2222/oauth2/rest/authorize?response_type=code&domain= JANEDOEIDDOMAIN1&client_id=JANEDOEOAUTHIDCLIENT1&scope=RServer0.searchsong openid profile&state=code1234&redirect_uri=http://host2:19528/app1/pages/Sample.jsp

http://host2:19528/app1/pages/Sample.jsp?code=NHN3WEtWazhjdGI0ZXhRcVh5bWttdz09fnYwcitKZ3ZDdFc3aXJoUVJISVR0S3lWRlVrbjFKM0JFSzZLOGlCZW13RkNBRzVUbzN1L3NOZUJLTVVFc3E1KzJnZlhVZGFXRXNJcEhtSkJNTi9BWWJhZ2VWUjZDZFB5SmtIM254VnRKcUdadVlGSjdzUzN4VktGTmFLVFhZYWQxR0NvYzVIa2M4ajJaN1haWUFzZHBKekpzL0pEa3ljcXZkdzEybnlVZlBrRkhSZy8vTE14VXpMQUoxcThhaXRROU5VMURhNHkrRW9WeFE2bFhLWmR0NmFyTUVTLzlsTkZtQ1B6YTNoeGtFWHJNR2FUV05BaWZJZXFkSk9nNzdTeFZpME9zVi92dWFRalRhbHNRWWkwQnBZbFBHRmppNjJhU1R0S1NBaCtZaDBENzRXMFJuQ0R4dW1SQTlKbTVWZjhZRzQ0WGVnSE0yemc2U0JxbzIzQWwxd3lNNnFFS2FpLzZvaXJjSUdwZFl3anhXSDl2b09lZkJaamNHY1ZCTlYxOUcwY3JKUWE5RFVidDF0VG1PRDBWNDdOcEFxZWFMbkFvRFc2QjZGUFFpd0drenEvSERjUVBpYWhoSUxHM1BOTW5CRFIyT2hzY3FJbzRvbWUxN0pONEVTR2ZiZC9sNFlYVUd2QXBPNFpWNVMxdGYrUEQ2cFJFLzZrRmVhYWk0cTV4T09jQnF1VytES2U4N0d2OXNpdlJPV3hUOFREajNSekFqeU5nWWNLc2VkTm51elBOeHlsYjAwQ3pTeWFNVVQ5R0toNWJCR2NYNGwzZkZUNlFJTUlHYVJDd3lKT1dITFhYRElqS3pTK29uZUxsSUdGZDByUUtHSmFrZGVNbGhmQktNT0hrcW8yY0xhNFQveTk4TW0zeXZOemNyc20zWnlIbWZOUHFuTFU4K2ZjPQ==&state=code1234

authzCode (sample snippet for reference)

NA

NA

http://localhost:8080/Sample.jsp?code=NDNlVnBOQ2MxWlZ4MHRmTWdHSm85QT09fnJBakNGU3FOOC9MZHFyK0N3dDNDZG1uVWY4Sm05WXNEdDRRbEI1cEEwQU0rb2IvVEpqS3ZjWDBnZSs0V1hka0NnYnhIRjlnKzNtekJINysvMmlPekRpS09nOUFqbEVsUEFiRmY1VG4rbmFPbDg5OGtXc2hTdHlTRUV5azM4U1k0NExHbWNKd0Fwa3YxZkw0VVZFdXBWS1dFWEtLWUR2T2FrTyt5VzNzdHhDaFp1b0NCOHBBWDFFNXZBZ1B4dEpEN2xmbm9vRzdIR0JpZEpid1ZvamR5NzFUVytKVzZuaEE3WFlPb3NlUS9BK2pqVHo2OUNuWGdxajRMMWFwU1V6M256NG1RS3JoK3E5RGVDRDd6THJ5NWl5U3RlWE14eDh1YU9oUHJwSGpkVzJnPQ==&state=code1234

access_token (sample snippet for reference)

   

"eyJraWQiOiJPSURDRG9tYWluIiwieDV0IjoibndBTXM0cXVVZDV3emdkUTZSOTZaekRrRTYwIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwOi8vZGVuMDF0cHMudXMub3JhY2xlLmNvbToxNzc4Mi9vYXV0aDIiLCJhdWQiOiJPSURDU2VydmVyIiwiZXhwIjoxNTA5NjQwMjcwLCJqdGkiOiIxUEFrcFlabVVtSjVuMlAyV0JfRDZBIiwiaWF0IjoxNTA5NjM2NjcwLCJzdWIiOiJhYXJhdGhpIiwiY2xpZW50IjoiT0lEQ0NsaWVudDIiLCJzY29wZSI6WyJPSURDU2VydmVyLnNjb3BlMSIsIk9JRENTZXJ2ZXIub3BlbmlkIiwiT0lEQ1NlcnZlci5waG9uZSIsIk9JRENTZXJ2ZXIuYWRkcmVzcyJdLCJkb21haW4iOiJPSURDRG9tYWluIn0.ulizk3lEk2aWIc89zD7uf-rIQRz89RNfDGpdy_mrl8dMhSZme69BI-DOS1-Yj7Pj6aTSXzCUUVkDTKdVzJb8e8BcjF9FYiea8mE7zw9ulHtMO-gceSiVHQ4tc3sOYJ7_vek2gUfGj7urS_h3oHQqGazWqQlQOHRxbnYr7xbprj58pFqiJdmVAp1eReYVNlmM7RpXKFRVyUZ43JBGEHONr94tuRC8H-Ss7Y9K_ND59Q0xmOmgoznXjrNz7KN2yWC3rlRuJySmPrzqG0bA0Pp30TAvXGqUpllFn5H9DN0PnZKLeUWZZRB5GaXL-xWRmbzCS6eW1l0sMEqEdABVfdooLA",

"token_type": "Bearer",

"expires_in": 3600,

     

RDRG9tYWluIn0.ulizk3lEk2aWIc89zD7uf-rIQRz89RNfDGpdy_mrl8dMhSZme69BI-DOS1-Yj7Pj6aTSXzCUUVkDTKdVzJb8e8BcjF9FYiea8mE7zw9ulHtMO-gceSiVHQ4tc3sOYJ7_vek2gUfGj7urS_h3oHQqGazWqQlQOHRxbnYr7xbprj58pFqiJdmVAp1eReYVNlmM7RpXKFRVyUZ43JBGEHONr94tuRC8H-Ss7Y9K_ND59Q0xmOmgoznXjrNz7KN2yWC3rlRuJySmPrzqG0bA0Pp30TAvXGqUpllFn5H9DN0PnZKLeUWZZRB5GaXL-xWRmbzCS6eW1l0sMEqEdABVfdooLA",

"token_type": "Bearer",

"expires_in": 3600,

refresh_token (sample snippet for reference)

   

"LGHeL2ToSLNRsYN5rmvlQg==~2G6JvVBnwuNrTN/69fDPvzX2RZSVRptEbUF4mGVkf/bjCeeZFfaPEnyoqVu9hB5Gt4BZPMDeEjYQZx1imRdGNh/NOx/MoRt8oXkyMljf1g4Qo67n5RThoyNVNczkevmNUeBznSTjdW2HNOSzHBnv0WY8IeimNkN3C77K2wAbSJtGWio8uX388jlrvXEa/5XdNe2LszA4c5nW5UgZzcjAi/69y9azViyEdtKP4ndo8CNS8O4cVAym2pryEr2zKPr+NfW7mwJ7gVeyjCaxcKmQ2zHKGpblaPHxak/iCyN0jew31XursBIRCP9PCKRwBc26qGX2Sf7W8Q3bxsUvImhvYw==",

id_token (sample snippet for reference)

 

http://150.136.116.143:7777/oauth2/rest/authorize?client_id=OIDCClient&redirect_uri=<>&scope=openid&state=38j02ra9az&nonce=<>&response_type=id_token&response_mode=form_post

"eyJraWQiOiJPSURDRG9tYWluIiwieDV0IjoibndBTXM0cXVVZDV3emdkUTZSOTZaekRrRTYwIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwOi8vZGVuMDF0cHMudXMub3JhY2xlLmNvbToxNzc4Mi9vYXV0aDIiLCJzdWIiOiJhYXJhdGhpIiwiYXVkIjoiT0lEQ1NlcnZlciIsImV4cCI6MTUwOTY0MDI3MCwiaWF0IjoxNTA5NjM2NjcwLCJhdXRoX3RpbWUiOjAsImp0aSI6IkJKYTRlU3NhemhLa01Wd0pOT1F1NncifQ.NmUWTa0brKTV54ZIYUq8mxamATPO3xVHILALO22CAgdAYZs0ixKDSxMH-z-7-giNyAu8MXUwXmBnfnwpd0ZuphlPVMVtr0YAEh_pzraR_bKSkgIqtHOIpswFVaz69YXyFtvmlOU77m-zEndsUbsxuJ0oZ9BErtIqcnkiaQn5os_RKr4uz3ltZtSxzH-vF1nzbmOpHZYETNrEji8kqg36gZHWxhFtbAE8hh_8UoNYpDCfxnpt1Du9kbFp2jXdeM9HVwQW_KH7Vv6rW8mChPefw9lAv3nfHxuiwcZ2GLC9NOwSJBVDMA94V1u9KfsXvR_bAIyaVE5zC-rpFEyXEG5ckA"

response_mode

  

http://150.136.116.143:7777/oauth2/rest/authorize?client_id=OIDCClient&redirect_uri=<>&scope=openid&state=38j02ra9az&nonce=<>&response_type=id_token&response_mode=form_post

  

40.4.1.1 Getting IDtoken via a Refersh Token Request

In the Authorization Code Grant, we can also get the idtoken in the refresh token request. The offline_access scope can be used with the prompt parameter of consent. Whenever offline_access is requested, the user will be asked for consent.

Authorize request:
http://<HostServer>:<OHSPort>/oauth2/rest/authorize?response_type=code&domain=iddomain&client_id=idclient&scope=openid offline_access&state=code1234&redirect_uri=https://oauthdebugger.com/debug&response_mode=fragment&nonce=123&prompt=consent

Authorize response: You will receive authorization code as response.

Token request:
curl --location 'http://<HostServer>:<ManagedServerPort>/oauth2/rest/token' \
--header 'X-OAUTH-IDENTITY-DOMAIN-NAME: iddomain' \
--header 'Authorization: Basic anVuZTp3ZWxjb21lMQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=AUTHORIZATION_CODE' \
--data-urlencode 'code=<>\
--data-urlencode 'redirect_uri=https://oauthdebugger.com/debug'

Token response: You will receive Access token, idtoken and refresh token as response.

Refresh request:
curl --location 'http://<HostServer>:<ManagedServerPort>/oauth2/rest/token' \
--header 'X-OAUTH-IDENTITY-DOMAIN-NAME: iddomain' \
--header 'Authorization: Basic anVuZTp3ZWxjb21lMQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=REFRESH_TOKEN' \
--data-urlencode 'refresh_token=<>'

Refresh response: You will receive Access token and idtoken as response.

40.4.2 Understanding Implicit Grant Authentication Flow

For an Implicit Grant Authentication Flow, the server returns all the tokens at the same time depending on the response_type parameter as follows:

Table 40-6 Implicit Grant Authentication Flow: Parameters and Access tokens

Parameter value Tokens returned Sample Request Sample Response

response_type=token id_token

Access Token

Identity Token

http://host3:2222/oauth2/rest/authorize?response_type=token id_token&domain=OIDCDomain&client_id=OIDCClient2&scope=OIDCServer.scope2+OIDCServer.openid+OIDCServer.email&redirect_uri=http://localhost:8080/Sample.jsp&nonce=abcde

http://localhost:8080/Sample.jsp#access_token=eyJraWQiOiJPSURDRG9tYWluIiwieDV0IjoibndBTXM0cXVVZDV3emdkUTZSOTZaekRrRTYwIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwOi8vZGVuMDF0cHMudXMub3JhY2xlLmNvbToxNzc4Mi9vYXV0aDIiLCJhdWQiOiJPSURDU2VydmVyIiwiZXhwIjoxNTA5NzE2MjY2LCJqdGkiOiJnTVllVGFrZVB6T3lZdGlHS0N5TTdnIiwiaWF0IjoxNTA5NzEyNjY2LCJzdWIiOiJhYXJhdGhpIiwiY2xpZW50IjoiT0lEQ0NsaWVudDIiLCJzY29wZSI6WyJPSURDU2VydmVyLnNjb3BlMiIsIk9JRENTZXJ2ZXIub3BlbmlkIiwiT0lEQ1NlcnZlci5lbWFpbCJdLCJkb21haW4iOiJPSURDRG9tYWluIn0.TDoX8y9Eg__DxrxWFrg0-sBxMiJaiPeo7jMdIDsKIXfkN60WGRuSI9atFHgcU5cnK_8R1jtZtlyp7kdUqmy-89prnzylWgUdUHXGspQVbsRf08Sgbhmrtz_RczKUygK78SSRTJXlKigRF_T3Wy6B9cmlcR-H1iVctR4eD8xcUCfGm5_bcnewTTOFbSsXDghwT_NIn1Dg-Jn6MgpWEMZMz7O_RFFrWeosztwvYqwatT7PDZZqszJ-qN9_muW4lUH-k4AnMIWS1jYUpjPMIa98gALyOP8WP6dtyB_q4FLZnx_ECmobXLvGo4GnMNLEL7sYj3jgYNySBB2d06jZcQocBQ&token_type=Bearer&id_token=eyJraWQiOiJPSURDRG9tYWluIiwieDV0IjoibndBTXM0cXVVZDV3emdkUTZSOTZaekRrRTYwIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwOi8vZGVuMDF0cHMudXMub3JhY2xlLmNvbToxNzc4Mi9vYXV0aDIiLCJzdWIiOiJhYXJhdGhpIiwiYXVkIjoiT0lEQ1NlcnZlciIsImV4cCI6MTUwOTcxNjI2NiwiaWF0IjoxNTA5NzEyNjY2LCJhdXRoX3RpbWUiOjAsIm5vbmNlIjoiYXZ5dWt0aCIsImp0aSI6IlFWdkFzU2xla3RTVWgtVHFNRXd5Q1EifQ.BMpBwtSbsffW2vz2YDh594UFOWcN52jtt2mVX3hD6OK3y-_qra71g676Igbk9PKSNcDp15yrFkIvuz39wbvVW_DC5DfOjRpWnWd-4KX8RoPpwSJDNFwZVudvgWoJ7bafGaaVO7Y-pnK-dkvb8lOX2ohBt3byaAu3rjykswR_wSw00r3ElExHqi4KSUeXW5LKDUOEf3E9pAC8tEcpQq6oh-QuzVfNxHJmB2zjSpFnzmUtuH74otVxUck38s5qqu5OiiHjw1DYgyatk-QxoJXuBPlEP0RBZ9Fspg1eJCQbhXDJoaA_n4yGsxpfM00Gok-PSTJbc0K29pwN6CdJbqCJGg&state=

response_type=id_token

Identity Token

http://host3:2222/oauth2/rest/authorize?response_type=id_token&domain=OIDCDomain&client_id=OIDCClient2&scope=OIDCServer.scope2&redirect_uri=http://localhost:8080/Sample.jsp&nonce=1234&state=abcd

http://localhost:8080/Sample.jsp#id_token=eyJraWQiOiJPSURDRG9tYWluIiwieDV0IjoibndBTXM0cXVVZDV3emdkUTZSOTZaekRrRTYwIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwOi8vZGVuMDF0cHMudXMub3JhY2xlLmNvbToxNzc4Mi9vYXV0aDIiLCJzdWIiOiJhYXJhdGhpIiwiYXVkIjoiT0lEQ1NlcnZlciIsImV4cCI6MTUwOTcyNTI0MCwiaWF0IjoxNTA5NzIxNjQwLCJhdXRoX3RpbWUiOjAsIm5vbmNlIjoiMTIzNCIsImp0aSI6Ii12RThqMlpHOEhabXZTRnVXcTVPSmcifQ.2qxv4rdrv-YvWNUK31aphrWkQ0iIrxhK690X2FgWW1CSNImUWfYGsNolcHiXxyzwPT6sv6koJ4m0jOIl2HEnIuWTdbE7SbtNJQ8JSVcg2et6hQJXLUXB1ECJQGCtw8FUYsprg-dtki-gCW85eRH9_V1RJMV2XaHC7PNoHEjG4CfqKmjwubfletYRReXks_uJ9YYW8TKnk87srG2Hh-uzK3C_GFLqUWaFrXp6XyM1yS-w4N-WyQ7UszuZTv8zd8SzX1xahjIdY0nakMEA7My7O3PcpVM4RTh-6xVLR_jNqRGxwbg4jc8QfmoWzMwRrYyjxFTzBSyGgd0jB3PWp4zn5w&state=abcd

response_type=token

Access Token

http://host3:2222/oauth2/rest/authorize?response_type=token&domain=OIDCDomain&client_id=OIDCClient2&scope=OIDCServer.scope1&state=code1234&redirect_uri=http://localhost:8080/Sample.jsp

http://localhost:8080/Sample.jsp#access_token=eyJraWQiOiJPSURDRG9tYWluIiwieDV0IjoibndBTXM0cXVVZDV3emdkUTZSOTZaekRrRTYwIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwOi8vZGVuMDF0cHMudXMub3JhY2xlLmNvbToxNzc4Mi9vYXV0aDIiLCJhdWQiOiJPSURDU2VydmVyIiwiZXhwIjoxNTA5NzA5OTE0LCJqdGkiOiI5S3BfLUZhT2pBTmxOOFE5S1J2T2d3IiwiaWF0IjoxNTA5NzA2MzE0LCJzdWIiOiJhYXJhdGhpIiwiY2xpZW50IjoiT0lEQ0NsaWVudDIiLCJzY29wZSI6WyJPSURDU2VydmVyLnNjb3BlMSJdLCJkb21haW4iOiJPSURDRG9tYWluIn0.QcCrRvlBEbK6-rVooKqkSzMP0RofgjeEhr74AbdJGnNQewlTQ9zry_TY56oWrkkyNKqjRYN0qa1_kXHoe562M-02L46A2qJSEEaaejrYhuvItmKbur0XlPpx8stUGCBhiv_vzSX_E5dr2aZ7P9Xz6Eqjm-wMMzZngAKImPmrdMDR3eJLIK2AfX7DFdcS9g4FIDZC3I8eoJ6sNBjBSVY37qGoT87NUh_d3y4Ga0Ga9Y9n5tHoxrqW1kuvtAAxHbB2lQBvBabSgDlGMGS9Fp7o0pi6by176XFUg7iYb1UY5Dx1hr0mlwPOHb3ndBX8Kg6wna_NplvvHrSc7XTH3DpOYw&token_type=Bearer&state=code1234

Note:

When an authorization request is made with an authorization code grant or implict grant type, and if openid scope is not included, the request is handled as a normal OAuth authorization request. An id_token is not issued through the response. Only access_token and refresh_token (in case of authorization code grant flow) are issued
Use the new request parameter repsonse_mode to fetch the authorization grants to redirect_uri in appropriate format:

Table 40-7 Parameter Values for response_mode

Parameter Value Description

form_post

The Authorization Response parameters are encoded in HTML form values that are auto-submitted by the User Agent and sent to the Client as HTTP POST requests.

fragment

The Authorization Response parameters are encoded in the fragment added to the redirect_uri when redirected back to the client.

This mode is default and need not be provided.

query

The Authorization Response parameters are encoded in the query string added to the redirect_uri when redirecting back to the client.

Note:

The response_mode=form_post/query requires the user to acknowledge the consent each time. If custom attribute consentExpiryTimeInMinutes is set to a non-empty value for the oauth identity domain then the default response_mode=fragment will be resumed for subsequent requests. Domain attribute consentExpiryTimeInMinutes is usually set via admin endpoint <server:port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain.

40.4.3 Understanding OpenIDConnect UserInfo Endpoint

The UserInfo endpoint is an OAuth2.0 resource that returns claims or information about the authenticated user.

The access token is generated with all necessary scopes. The client passes this access token to the User endpoint of the server and requests for the claims about the end-user.

OpenIDConnect Clients use scope values to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints.

OpenIDConnect defines the following scope values that are used to request Claims as shown in the table:

Table 40-8 scope values that are used to request Claims

Scope Description Mandatory/optional

profile

If requested, the Access token is generated with this scope. When the access token is sent to the server's UserInfo endpoint, the server responds with specific claims about the authenticated user's profile.

Optional

email

It requests access to the email and email_verified Claims of the user

Optional

address

It requests access to the address Claim of the end user.

Optional

phone

It requests access to the phone_number and phone_number_verified Claims of the end user.

Optional

See Also:

40.4.3.1 Retrieving Userinfo Attributes from OAM

When LDAP is used, the values for all the scope attributes or claims need to be retrieved from OAM. Configure OAM to get the Userinfo Claims.

Create a new IDStore using any one of the following methods:

  • Using IDSProfile

  • OAM IDStore directly

Note:

The attribute or claim in the token are mapped to the physical attribute in the IDStore. The attribute or claims that are returned as part of the userinfo response cannot be modified. However, the values returned as part of these can be modified by editing the attribute in IDStore to Physical attribute mapping.

See Also:

The following table captures the claims under each scope and the corresponding backend LDAP attribute.

Table 40-9 Claims under each scope and the corresponding backend LDAP attribute.

Scope Attributes/Claims IDStore Attriubute IDSProfile's physical attribute Sample Response

Profile

Name

family_name

given_name

given_name

preferred_username

gender

locale

updated_at

name

lastname

firstname

firstname

name

This is returned as ""

preferredlanguage

current time

eg: cn

sn

givenname

givenname

cn

"profile": {

"name": " jane",

"family_name": " doe",

"given_name": "jane"

"preferred_username": "j.doe",

"gender": "",

"locale":"en/US"

"updated_at": "1509709292632"

}

email

email_verified

"N"

   

address

formatted

country

region

postal_code

postaladdress

country

state

postalcode

"address": {

"formatted": "Aaccf Amar$01251 Chestnut Street$Panama City, DE 50369",

"country" :"US",

"region": "DE",

"postal_code": "50369"

}

  

phone

phone_number_verified

"N"

"phone": {

"phone_number_verified": "false"

}

  

Following figure shows mapping between the entity attribute to physical attribute for an IDSProfile:

When the claim:given_name is mapped to the firstname attribute in the IDStore, and the firstname is mapped to the givenname physical attribute in LDAP. This attribute to physical attribute can be changed to give the required value. We can change the Physical Attribute column, when maidenname should be returned instead of givenname.

As shown in the following figure, under IAMSuite, there are two resources seeded out-of-the-box for OAuth. While requesting for UserAttributes, the resource /OAuth/UserAssertion is used to assert the user against the new IDStore. Then, modify the originally created IdentityDomain to set the identityProvider to the new IDStore created through Admin OAuth APIs or curl commands.

Description of aiaag_oidc_iamsuite_appdom.png follows
Description of the illustration aiaag_oidc_iamsuite_appdom.png

If the newly created IDStore is a DefaultStore, no changes required. The resource /OAuth/UserAssertion uses OAuth Assertion Policy that has the LDAPNoPasswordValidationScheme. Ensure that the scheme uses LDAPNoPasswordAuthModule that uses the new IDStore.

Description of aiaag_oidc_idsprofle.png follows
Description of the illustration aiaag_oidc_idsprofle.pngDescription of aiaag_oidc_ldapnopassauth.png follows
Description of the illustration aiaag_oidc_ldapnopassauth.png

If the newly created IDStore is not a DefaultStore, perform the following:

  • Using UserIdentificationPlugin, create a new authentication module, UserInfoAuthModule

  • Set the KEY_IDENTITY_STORE_REF to point to the new IDStore.

  • Create a new AuthnScheme or update LDAPNoPasswordValidationScheme to use this new module.

  • Update the OAuth Assertion Policy to point to this new Authentication scheme.

Table 40-10 Parameters to create new authentication module, UserInfoAuthModule

Endpoint Sample Request Sample Response

http://{{machine}}:{{mgdport}}//oauth2/rest/userinfo

curl -X GET http://host4:14100//oauth2/rest/userinfo -H 'authorization: Bearer <AccessToken>' 

"guid": "6C9CF210194A11E99FB45DDD0C60B95A",
        "sub": "weblogic",
        "family_name": "weblogic",
        "preferred_username": "weblogic",
        "updated_at": "1548740667872",
        "email_verified": false,
        "phone_number_verified": false

40.4.3.2 Retrieving User Info Attributes Using Template-Based Mapping

The following claims are read from IDStore, if the IDStore attribute name matches with the OIDC standard claim names. For more information about the standard claims, see https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims

For few common claims there is default mapping to IDStore Attributes. However, for the claims that do not have a default mapping to IDStore attributes, use template-based mappings. For details, see Defining Custom Claims Using Templates

Table 40-11 OIDC Standard Claims Mapping

Scope Attibutes/Claims Mapping for the IDStore Attributes Sample Response
Profile

name

family_name

given_name

middle_name

nickname

preferred_username

profile

picture

website

gender

birthdate

zoneinfo

locale

updated_at

Following common claims also have default mapping to IDStore Attributes: For example:

name is mapped to name

family_name is mapped to lastname

given_name is mapped to firstname

preferred_username is mapped to name

locale is mapped to preferredlanguage

updated_at is mapped to current time

 
{
    "sub": "userSub",
    "name": "user1",
    "family_name": "userLastName",
    "given_name": "userGivenName",
    "middle_name": "userMiddleName",
    "nickname": "userNickname",
    "preferred_username": "userPreferredUsername",
    "profile": "userProfile",
    "picture": "userPicture",
    "website": "userWebsite",
    "gender": "Female",
    "birthdate": "2000-01-01",
    "zoneinfo": "Unknown",
    "locale": "IN",
    "updated_at": 1628759535,
}
email

email

email_verified

 email is mapped to mail 
{
    "email": "user@example.com",
    "email_verified": false
}
address 
"address": {
    "formatted",
    "street_address",
    "locality",
    "region",
    "postal_code",
    "country"
}

formatted is mapped to postaladdress

country is mapped to country

region is mapped to state

postal_code is mapped to postalcode

 
"address": {
    "formatted": "Aaccf Amar$01251 Chestnut Street$Panama City, DE 50369",
    "street_address": "Panama City",
    "locality": "Panama City",
    "region": "DE",
    "postal_code": "50369",
    "country": "US"
}
phone

phone_number

phone_number_verified

 phone_number is mapped to telephone 
{
    "phone_number": "[+1415555-0100]",
    "phone_number_verified": false
}

Note:

Claim values can be mapped to any physical attribute present in the User Store using Template-based mapping. For more information, see Examples for Template-Based Claims.

40.4.4 Understanding OpenIDConnect Discovery Endpoint

OpenID Provider Issuer discovery is the process of determining the location of the OpenID Provider.

Using the Issuer location discovered, the OpenID Provider's configuration information can be retrieved. The response is a set of Claims about the OpenID Provider's configuration, including all necessary endpoints and public key location information.

40.4.4.1 Configuring OpenIDConnect Discovery Endpoint

The OpenID Provider's configuration details are exposed through /.well-known/openid-configuration.

As shown in the following figure, on the OAM console, under IAMSuite domain, OpenID Discovery endpoint is listed as a resource:

Description of aiaag_oidc_discov_endpoint.png follows
Description of the illustration aiaag_oidc_discov_endpoint.png

Locate mod_wl_ohs.conf file at <ohs_domain_home>/config/fmwconfig/components/OHS/instances/<ohs_instance_name> and add the following: 

<Location /.well-known/openid-configuration> 
SetHandler weblogic-handler
PathTrim /.well-known 
PathPrepend /oauth2/rest
WebLogicHost <OAM_managed_server host>
WebLogicPort <OAM_managed_server port> 
</Location>

Sample request: 

GET /.well-known/openid-configuration HTTP/1.1 
Host: host4:7777

Sample response: 

{
"issuer": "http://host4:7777/oauth2", 
"authorization_endpoint": "http://host4:7777/oauth2/rest/authorize", 
"token_endpoint": "http://host4:7777/oauth2/rest/token", 
"userinfo_endpoint": "http://host4:7777/oauth2/rest/userinfo", 
"introspect_endpoint": "http://host4:7777/oauth2/rest/token/info",
"jwks_uri": "http://host4:7777/oauth2/rest/security", 
"end_session_endpoint": "http://host4:7777/oauth2/rest/userlogout", 
"scopes_supported": [ 
	"openid",
	"profile", 
	"email", 
	"address", 
	"phone" 
],
"response_types_supported": [
	"code",
	"token",
	"id_token",
	"token id_token"
],
"grant_types_supported": [
	"client_credentials",
	"password",
	"refresh_token",
	"authorization_code",
	"implicit",
	"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"subject_types_supported": [
	"public"
],
"id_token_signing_alg_values_supported": [
	"RS256"
],
"userinfo_signing_alg_values_supported": [
	"none"
],
"token_endpoint_auth_methods_supported": [
	"client_secret_basic",
	"client_secret_jwt"
],
"token_endpoint_auth_signing_alg_values_supported": [
	"RS256"
],
"claims_supported": [
	"aud",
	"exp",
	"iat",
	"iss",
	"jti",
	"sub"
],
"ui_locales_supported": [
	"en"
]
}

Configuring claims_supported

OAM supports all OIDC standard claims (refer to https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims), provided they have a value in the configured UserStore or have template-based mappings.

claims_supported in the discovery URL can be configured to display all these standard claims by updating the oam-config.xml. The customized claim_supported list must be added under the following path in oam-config.xml:

DeployedComponent/Server/NGAMServer/Profile/STS/datastore/backend/discoveryproviders/metadatadiscovery/claimsSupported

See Updating OAM Configuration

Following is a sample claim_supported list:
<Setting Name="claimsSupported" Type="htf:map">
 <Setting Name="aud" Type="xsd:string">aud</Setting>
 <Setting Name="exp" Type="xsd:string">exp</Setting>
 <Setting Name="iat" Type="xsd:string">iat</Setting>
 <Setting Name="iss" Type="xsd:string">iss</Setting>
 <Setting Name="jti" Type="xsd:string">jti</Setting>
 <Setting Name="sub" Type="xsd:string">sub</Setting>
 <Setting Name="acr" Type="xsd:string">acr</Setting>
 <Setting Name="name" Type="xsd:string">name</Setting>
 <Setting Name="given_name" Type="xsd:string">given_name</Setting>
 <Setting Name="family_name" Type="xsd:string">family_name</Setting>
 <Setting Name="middle_name" Type="xsd:string">middle_name</Setting>
 <Setting Name="nickname" Type="xsd:string">nickname</Setting>
 <Setting Name="preferred_username" Type="xsd:string">preferred_username</Setting>
 <Setting Name="profile" Type="xsd:string">profile</Setting>
 <Setting Name="picture" Type="xsd:string">picture</Setting>
 <Setting Name="website" Type="xsd:string">website</Setting>
 <Setting Name="email" Type="xsd:string">email</Setting>
 <Setting Name="email_verified" Type="xsd:string">email_verified</Setting>
 <Setting Name="gender" Type="xsd:string">gender</Setting>
 <Setting Name="birthdate" Type="xsd:string">birthdate</Setting>
 <Setting Name="zoneinfo" Type="xsd:string">zoneinfo</Setting>
 <Setting Name="locale" Type="xsd:string">locale</Setting>
 <Setting Name="updated_at" Type="xsd:string">updated_at</Setting>
 <Setting Name="address" Type="xsd:string">address</Setting>
 <Setting Name="phone_number" Type="xsd:string">phone_number</Setting>
 <Setting Name="phone_number_verified" Type="xsd:string">phone_number_verified</Setting>
</Setting>

40.4.4.2 Configuring OIDC Discovery Endpoint

In addition to the OpenID Provider's configuration details, another endpoint, /.well-known/oidc-configuration is exposed. It provides information related to the access server such as authentication and logout endpoints.

Locate mod_wl_ohs.conf file at <ohs_domain_home>/config/fmwconfig/components/OHS/instances/<ohs_instance_name> and add the following: 

<Location /.well-known/oidc-configuration> 
SetHandler weblogic-handler
PathTrim /.well-known 
PathPrepend /oauth2/rest
WebLogicHost <OAM_managed_server host>
WebLogicPort <OAM_managed_server port> 
</Location>

Sample request: 

GET /.well-known/oidc-configuration HTTP/1.1 
Host: host4:7777

Sample response: 

{
"configuration": {
"release-version": "12.2.1.3.0"
},
"access-configuration": {
"http-direct-authentication-endpoint": "http://host4:7777/oam/server/authentication",
"http-logout-endpoint": "http://host4:7777/oam/server/logout",
"http-credential-submit-endpoint": "http://host4:7777/oam/server/auth_cred_submit"
},
"openid-configuration": {

← Same as openid discovery response value→
}
}

Note:

Currently the back-channel logout through the end_session_endpoint is not implemented. The front-channel logout through http-logout-endpoint can be used to logout the user and end the session.

40.4.5 Fetching Identity Domain Certificate

Use the security endpoint, http://<managed server host>:<managed server port>/oauth2/rest/security, to fetch public certificate of given Identity domain. The output from this endpoint is <identitydomain>.p7b file .

Table 40-12 Fetch public certificate of given Identity domain: Parameters

Parameter Type Parameter Name Description Sample

Header

X-OAUTH-IDENTITY-DOMAIN-NAME

Identity Domain Name

MDCDomain19

Header

Authorization

Basic <B64 encoded clientid:password>

Basic TURDQ2xpZW50MTk6d2VsY29tZTE=

Query

identityDomainName

Identity Domain Name

Note: First preference will be given to X-OAUTH-IDENTITY-DOMAIN-NAME.

Second preference is given to identityDomainName.

MDCDomain18

Following is a sample REST call where X-OAUTH-IDENTITY-DOMAIN-NAME has the preference over identityDomainName.

Sample Request:

 curl -X GET 'http://host1:14100/oauth2/rest/security?identityDomainName=MDCDomain18' -H 'authorization: Basic TURDQ2xpZW50MTk6d2VsY29tZTE=' -H 'x-oauth-identity-domain-name: MDCDomain19'

Following is a sample REST call that results in MDCDomain18 public certificate chain in p7b format. i.e. MDCDomain18.p7b file:

Sample Request:

curl -X GET 'http://host1:14100/oauth2/rest/security?identityDomainName=MDCDomain18' -H 'authorization: Basic TURDQ2xpZW50MTk6d2VsY29tZTE='