OpenID Connect APIs


We're Moving ... Again

Yes, the Identity Cloud documentation is once more on the move. And this time we're headed to two different locations:

As for the Education Center, well, the Center itself will disappear on July 23rd. We apologize for any inconvenience, but we look forward to becoming a full-fledged member of the Akamai family.
 

The OpenID Connect APIs include the following endpoints:

  • ​/{customer_id}/login/authorize. Requests an authorization code from the authorization endpoint.
  • ​/{customer_id}/login/token. Exchanges an authorization code or a refresh token for a set of Hosted Login tokens.
  • /{customer_id}/oidc/userinfo. Retrieves user profile information from the userinfo endpoint.
  • /{customer_id}/login/.well-known/openid-configuration. Retrieves configuration information from the discovery document.
  • /{customer_id}/login/jwk. Returns the JSON web keys associated with the customer ID.
     

/{customer_id}/login/authorize

Requests an authorization code from the authorization endpoint. 

This endpoint includes the following methods:

  • GET

GET

Description

The /{customer_id}/login/authorize endpoint is used to request an authorization code from the authorization endpoint. If this call succeeds, the client will be sent an authorization code; that code can then be presented to the token endpoint and exchanged for an access token, refresh token, and identity token.

In order to receive a code:

  1. An authorization request to the authorization endpoint; this request must be made using an OIDC client associated with the endpoint. 
  2. If the request is valid, the authorization endpoint uses the OIDC client’s login policy to redirect the user to the appropriate login page where he or she attempts to log on. 
  3. If authentication is successful, an authorization code is returned, and the user is redirected to the location specified by the request’s redirect_uri parameter.

The /{customer_id}/login/authorize endpoint can be used with either of the following authorization flows:

  • Authorization Code. With this flow, the client secret of the OIDC client must be included as part of the token exchange request. For security reasons, it’s recommended that client secrets not be stored on mobile devices. Consequently, this flow type should not be used to make authorization requests from mobile devices.
  • Authorization Code + PKCE. With this flow, the client secret does not need to be included as part of the token exchange request. Instead, a code verifier, code challenge, and code challenge method are used to help ensure the validity of each request and each transaction. Because the client secret is not required, this flow is recommended for authorization requests from mobile clients.

Request Parameters

The query parameters for the /{customer_id}/login/authorize endpoint include the following:

Parameter

Required

Description

client_id

Yes

Unique identifier of the OIDC Client making the request. For example:

22c9604-7b27-464f-bff5-83ba229323af

response_type 

Yes

Specifies the authentication and authorization flow type. For Hosted Login, the response_type must be set to code, which means that, after a successful authentication, the user is sent an authorization code. That code must then be exchanged for an access token before the user can access resources.

scope

Yes

Indicates the scopes you are requesting access to. For example:

openid profile email

Scopes are collections of claims, and claims (for the most part) map to individual user profile attributes. For example, the email scope consists of two claims: emailAddress and emailVerified. With OpenID Connect, the openid scope must always be requested. This tells the authorization server that you want to authenticate by using OIDC.

redirect_url

Yes

The URI (e.g., the web page) that clients are redirected to after being authenticated. For example: 

https://documentation.akamai.com

As you make your way through the authentication process, you’ll see that the redirect URI appears in several different API requests and API responses. The redirect URI must be the same in every request/response or the API call will fail.

state

Yes

Value of the anti-forgery state token. For example: 

99846266547289293014765635352342

The anti-forgery state token (also referred to as the nonce) is a randomly-generated value included in an authorization request and then returned along with the authorization code. The client can check the value returned from the authorization server with the value of the state parameter from the original request. If the values match, that helps verify that the authorization code is legitimate. If they don’t that suggests that something has gone wrong with the authentication process. In that case, authentication should be canceled and then restarted.

prompt

No

Specifies the system behavior when a user needs to be reauthenticated (for example, because the max_age limit has been exceeded). Hosted Login supports two prompt values:

  • none. When a user needs to be reauthenticated, the authorization server first checks to see if the user currently has a valid Hosted Login session. If true, the user is then “silently” reauthenticated (that is, no authentication dialog box is displayed, and the user never knows he or she was reauthenticated). If false, an error is returned, and the user must reauthenticate in order for their Hosted Login session to continue.
     
  • login. The user is always asked to reauthenticate, regardless of whether he or not he or she currently has a valid session.

max_age

No

Specifies the maximum amount of time (in seconds) that a logon session can last before the user is required to reauthenticate.

id_token_hint

No

Specifies that a token previously issued by the authorization server should be passed along with the authentication request. If the end user associated with the token is already logged on, then no new authentication is required and the user remains logged on. If the end user is not logged on, then he or she will be required to sign in.

If you decide to use the id_token_hint parameter you should also include the prompt=none parameter in your request.

ui_locales

No

Specifies the end user’s preferred language (or languages) for the login and registration user interfaces. Language preferences should be passed as a set of space-delimited RFC5646 language codes; for example:

"en-US en-GB fr-CA"

In the preceding example, Hosted Login will first attempt to render the UI in US English. If that fails, the UI will be rendered in British English and then, if necessary, Canadian French.

If this parameter is not present, the default language and local will be used. Note that no error will be returned if you specify an invalid language code, or if your application does not support a specified language.

code_challenge

Yes (with PKCE)

Encrypted value generated by the client. This value will need to be verified before the client will be allowed to exchange an authorization code for a set of tokens.

For example:

code_challenge= RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg
3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYxRkM4Nj
Q0QzdBNw

code_challenge_method

Yes (with PKCE)

Hashing algorithm used to generate code challenge:

For example:

code_challenge_method=S256

Authentication

No authentication is required to call the /{customer_id}/login/authorize endpoint.

Sample Request 1: Authorization Code Flow (curl)

The following command uses the Authorization Code flow to request an authorization code from the https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize endpoint:


curl -X GET \
 'https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize?client_id=21d832df-e92e-4e32-80df-8726d47992fa&redirect_uri=https://documentation.akamai.com/debug&scope=openid&response_type=code&state=dgwt5dbcxja'
 

Sample Request 2: Authorization Code + PKCE Flow (curl)

The following command uses the Authorization Code + PKCE flow to request an authorization code from the endpoint https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize. To use PKCE, the code_challenge and code_challenge_method parameters were added to the previous authorization request.


curl \
 'https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize?client_id=21d832df-e92e-4e32-80df-8726d47992fa&redirect_uri=https://documentation.akamai.com/debug&scope=openid&response_type=code&state=dgwt5dbcxja&code_challenge=RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg 3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYxRkM4Nj Q0QzdBNw&code_challenge_method=S256' 
   

Responses

200 OK

If your call to this endpoint succeeds, you'll get back a response similar to the following. In this sample response, the authorization code has been highlighted in red:

https://v1.api.us.janrain.com/00000000-0000-3000-8000-000000000000/login/code?state=security_token%3bd5262737237ef4a %url%https://hosted-login.akamai.com/callback&code=4/JR27W91a-ofgCe9ur2m6bTghy77

Note that you will get the same response back regardless of whether you are using the Authorization Code flow or the Authorization Code + PKCE flow. When using the Authorization Code + PKCE flow, no information about the code challenge or code challenge method are included in the response.

Errors

The following table includes information about some of the errors that you could encounter when calling this endpoint.

Error 

Description

invalid_client

The supplied OIDC client ID is not associated with the authorization endpoint. When OIDC clients are created, they must be associated with – and, as a result, can only be used with – a specific authorization endpoint.

invalid_redirect_uri

The value for the request’s redirect_uri parameter does not match any of the redirect URIs specified in the OIDC client. Each OIDC client has a set of authorized redirect URIs: one of those authorized URIs must be used as the value of the redirect_uri parameter.

invalid_request

Typically indicates that a required parameter is missing from the request. When that occurs, the error description will usually tell you which parameter is missing:

scope_is_missing

unsupported_response_type

Occurs if the parameter value supplied for the response_type parameter is anything other than code.


/{customer_id}/login/token

Exchanges an authorization code or a refresh token for a set of Hosted Login tokens.

This endpoint includes the following methods:

  • POST

POST

Description

Exchanges an authorization code or a refresh token for an access token, refresh token, and identity token.

Request Parameters

The x-www-url-encoded parameters for the /{customer_id}/login/tokens endpoint include the following:

Parameter

Type

Required

Description

grant_type

string

Yes

Specifies the type of authorization grant being requested. Allowed values are:

  • authorization_code. Indicates that you want to exchange an authorization code for a set of tokens.
     
  • refresh_token. Indicates that you want to exchange a refresh token for a new set of tokens.

code

string

No

The authorization code being exchanged. Use this parameter if the grant_type is set to authorization_code.

refresh_token

string

No

The refresh token being exchanged. Use this parameter if the grant_type is set to refresh_token.

code_verifier

string

No

Required if you are using PKCE (Proof Key for Code Exchange) and your original authorization request includes the code_challenge parameter. The code_verifier must be the same verifier used to generate the initial code challenge.

redirect_uri

url

Yes

URL of the page the user will be redirected to following the token exchange.

Authentication

This endpoint requires Basic authentication unless you are using PKCE (Proof Key for Code Exchange). With PKCE flows, no authentication is required.

When configuring authentication, use your Hosted Login OIDC client ID as the username and the OIDC client secret as the password.

Sample Request (curl)

The following command exchanges the authorization code K2MzvxY8nIRhNQYe for a set of tokens:

curl -X POST \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token \
  -H 'Authorization: Bearer RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=K2MzvxY8nIRhNQYe&redirect_uri=https%3A%2F%2Fdocumentation.akamai.com&code_verifier=AdleUo9ZVcn0J7HkXOdzeqN6pWrW36K3JgVRwMW8BBQazEPV3kFnHyWIZi2jt9gA'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back a response that includes an access token, a refresh token, and an identity token:


{
   "access_token": "5na7KhMcUqnpoVDCRBX5na7Lwgh7L6qOaAlb1r2r_VKcemGgbh634rv261zbghfg6t",
   "refresh_token": "iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH_Xk7EzdpGq5GPQcsxCWM2SxdlwU",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "email openid profile",
   "id_token": "kyJhbGciOiJSUzI1NiIsImtpZCI6ImE5NjRhNjE3YTc0YjZjZWNlMDM4NTdkYWExZThlMTQ0ZDExMTMyYTkiLCJ0eXAiOiJKV1QifQ.eyJhdF9oYXNoIjoiV1Y0STlVbjFWSi96Q25iRHVoWndIUSIsImF1ZCI6WyJhMjJjOTYwNC03YjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3MjEzLCJleHAiOjE1NTMwMzA4MzksImdsb2JhbF9zdWIiOiJjYXB0dXJlLXYxOi8v YjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3bm5qZXl6eXJydDJubTVkcmY1bmtuOC91c2VyLzc5OGQ2NTQwLWExYTYtNDFiNS1iZjcxLTg1YjY5NDFkY2E4MCIsImlhdCI6MTU1MzAyNzIzOSwiaXNzIjoiaHR0cHM6Ly9hcGkubXVsdGkuZGV2Lm9yLmphbnJhaW4uY29tLzAwMDAwMDAwLTAwMDAtMzAw YjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3NDFiNS1iZjcxLTg1YjY5NDFkY2E4MCJ9.TRaDP-i2_a0Z2s6MYh3LQEyTU5UkR1el6w_waPFeV2hZgv10pDHu6xVrAZUZwErU0_mSDbe9bJo5I_yuecgXZ_4Q1WNV0Z4zhTJ-T9ycpN-eSwgPQcDGddh8J1ybI0Rg6yM54OOcf6o_shqrQMGiiFirm9Grt-P YjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI319-S83qGyLStH5db06iVjFahdNex0w39uQSHlTf7Ay0Acb0JOtMOk7JUC406wT5WT5Jz1q-GV2q_ChvxdUCCnd2Vp8lNba3AyznkehABHeISkNYtJ6BKigQ"
}

Error Codes

The following table includes information about some of the error codes that you could encounter when calling this endpoint.

Error Code

Description

400

Error Message: Invalid_grant.

Typically occurs if you pass an invalid authorization code or if the authorization code has expired. Authorization codes are valid only for a few minutes.

If you encounter an error when calling this endpoint your error message will look similar to this:

{
   "error": "invalid_grant",
   "error_description": "code not found or expired"
}

 


/{customer_id}/oidc/userinfo


Returns user profile information from the userinfo endpoint.

This endpoint includes the following methods:

  • GET

GET

Description

Returns user profile information for from the userinfo endpoint. To use this endpoint, you must include an access token in your authorization header; in turn, that means you can only get back the OIDC claims (user attributes) assigned to the the token. In addition, you can only get back claims for the user that the token was issued to. For example, if the token was issued to Karim Nafir and the token was assigned the email scope, then you can only get back the emailAddress and emailVerified claims for Karim Nafir. That’s because emailAddress and emailVerified are the only two claims in the email scope.

URI Parameters

No additional parameters are required to call the /{customer_id}/oidc/userinfo endpoint.

Authentication

This endpoint requires Bearer authentication. To use this authentication, include the word Bearer in your Authorization header, followed by the value of the access token being used to retrieve the user data. For example:

Authorization: Bearer 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli

Sample Request (curl)

The following command returns user information for the user and scopes associated with the access token 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli:

curl \
   https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/profiles/oidc/userinfo \
   -H 'Authorization: Bearer 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli' \
   -H 'Content-Type: application/x-www-form-urlencoded'  

Responses

200 OK

If your call to this endpoint succeeds, you'll get back the requested user profile information:

{
    "emailAddress": "karim.nafir@mail.com",
    "emailVerified": true
}

Error Codes

The following table includes information about some of the error codes that you could encounter when calling this endpoint.

Error Code

Description

400

Error Message: Invalid_request

Indicates that the subject and data authority do not match.

401

Error Message: Invalid_token

Typically occurs if you pass an invalid authorization code or if the authorization code has expired. Authorization codes are valid only for a few minutes.

If you encounter an error when calling this endpoint your error message will look similar to this:

{
   "error": "invalid_request",
   "error_description": "subject and data authority host do not match"
}

 


/{customer_id}/login/.well-known/openid-configuration


Returns the information found in the discovery document.

This endpoint includes the following methods:

  • GET

GET

Description

Returns the discovery document, a set of OIDC values that can be retrieved by a client; using these values enables OIDC clients to configure themselves. For example, you shouldn’t have to hard-code the token URL in a client. Instead, the client can simply connect to the well-known endpoint and retrieve the token URL itself.

The discovery document is more formally referred to as the “well-known endpoint;” that’s why the string well-known appears in the endpoint URL.

URI Parameters

No parameters are required in order to call the /{customer_id}/login/.well-known/openid-configuration endpoint.

Authentication

This endpoint does not require authentication. 

Sample Request (curl)

The following command returns for discovery document for the organization with the Hosted Login customer ID 00000000-0000-0000-0000-000000000000:


curl \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/.well-known/openid-configuration

Responses

200 OK

If your call to this endpoint succeeds, you'll get back the configuration values found on the discovery document:


{
    "issuer": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login",
   "authorization_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize",
   "token_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token",
   "introspection_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token/introspect",
   "revocation_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token/revoke",
   "userinfo_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/profiles/oidc/userinfo",
    "jwks_uri": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk",
    "response_types_supported": [
        "code"
    ],
   "subject_types_supported": [
        "public"
    ],
   "id_token_signing_alg_values_supported": [
        "RS256"
    ],
   "grant_types_supported": [
       "authorization_code",
       "refresh_token"
    ],
   "token_endpoint_auth_methods_supported": [
       "client_secret_basic",
       "client_secret_post"
    ],
   "scopes_supported": [
        "openid",
        "profile",
        "email",
        "address",
        "phone"
    ],
   "claims_supported": [
        "sub",
        "iss",
       "auth_time",
        "acr",
        "name",
       "given_name",
        "address",
       "family_name",
       "middle_name",
       "preferred_username",
        "gender",
       "birthdate",
       "updated_at",
       "phone_number",
       "phone_number_verified",
        "email",
       "email_verified"
    ],
   "code_challenge_methods_supported": [
        "S256"
    
}

 


/{customer_id}/login/jwk


Returns information about the JSON web keys associated with the specified customer.

This endpoint includes the following methods:

  • GET

GET

Description

Returns information about the JSON web keys (JWK) associated with a customer. JSON web keys are public cryptographic keys used to verify the signatures on Hosted Login identity tokens.

URI Parameters

No parameters are required in order to call the /{customer_id}/login/jwk endpoint.

Authentication

This endpoint does not require authentication. 

Sample Request (curl)

The following command returns the JSON web keys associated with the customer ID 00000000-0000-0000-0000-000000000000:


curl -https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk 

Responses

200 OK

If your call to this endpoint succeeds, you'll get back a collection of JSON Web Keys similar to this:


{
    "keys": [
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "51300370a8e1ac0a14a59cdd9c881d3f24c01f78",
            "alg": "RS256",
            "n": "w9OLNr_6sIuqr8OO3nPzorbv8tkmXC-m0k0O3W6gdk1QipvJ2pZkRSzD_iIWnEvYV11RuOBSAb7e_nU7mwNnxX6mORyJIEwnHKucBwaHQhuo56uVUjNTsRI6OuLB6REwxLM0ePPQPJNaXncWzt83oYdHU10VPmp5x0Sj-GjTvMpm2Y4I14KnFUXMEvIC-e5lf2P7q6KMXNw3PchEvmO5fVCgXf5-FgzDzEyn0qXrerdui4lGUtzcREPFksPNLNMlqp0XL5Kz1QLLkKDtR3dVjEtViEYJ6extcI-xFEV785hO4Ok36N99ht41EZk8ibrflNnYkJIEXAw_LKkmtxyZKw",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "f63eecd7318b6a6bcfae82f9607689756c6dd83e",
            "alg": "RS256",
            "n": "2kTH-jB0XDAb4yJy9rRMKNTNk4FEz7n3mbzj7nvupGvozyrpgHNFzSNW-Faxfo8v3cMdekd0-3S1ioNquAn9bbKZ8j2D4wK7rYtJgwOE8vnHkLUPAQuv_ymUgdgRAz7iQhsUN-vs8QLIDTddzEGnKWZASndLb-CYN_3eSWCDL7J8kQGkm9EI91OY1tKUUdIxlHpr90zAR36CFWWIJY1hpgFFnC1Po2r4nBtkBZD-SG_tmWB7fmWmF9v9MNnpmY00h3PsvUfzb6dSzLNt3H2ocSys7F5syaulRGLiKFiTalPPri_wAj-CPVfqiZuEys8PNTVd6T969PM4dIFdIsR0gw",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "a964a617a74b6cece03857daa1e8e144d11132a9",
            "alg": "RS256",
            "n": "7-LW8dGJKFsxU6ztkRA_qdhzvuHkoeWlRGL6ejqW9z_PxtDnQbLIpiy0vFm_DYAyNyFXt1EbuVMzESd4XRCKue4Lw2tGS_iiVQhlq7RkwAYG-hOkiiIHCcLVVCxtPm8gdmW-Cp4sdDozG0Yc99os-nyBtm2YzZ3ECAMsQsQVIjR03_JD3l1u79F4EzWcs2aBMOQ0NFDHqoQyk16Gf6Ww5QMXBtFhI508kYDMg71-0cxpssOrkztBBkxH1WPDpeliEAO91Sy1HDgXkuKdEuPkB3JxUqGXiw_UAez0a4XXBMFNkc5pV8byrKWokKmzNSgSfObqaRx13wOk5xjyVpyfHQ",
            "e": "AQAB"
        }
    ]
}