Hosted Login APIs

The Hosted Login APIs include the following endpoints:

          


/{customerId}/login/authorize

Requests an authorization code from the authorization endpoint. 

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

If an authorization request is accepted, the user is presented with the sign-in screen and is asked to log on to the site or app. If authentication succeeds, the user will be fully logged on to the site, will be issued an access token, a refresh token, and an identity token, and then be redirected to the URL specified in the authorization request.

Note. That’s a slightly-abridged version of the authorization and authentication process. For a more-detailed version, see the article Authorization Code + PKCE.

A typical authorization request looks something like this: 

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
   ?client_id=64430515-01ea-4f5d-82e4-c36161af009
   &redirect_uri=https://oidc-playground.akamai.com/redirect_uri
  &scope=openid email phone
   &code_challenge=y63Qmobx6ZCSYCZqPNzQ6Qx1rGK0reaxgbb5WSAQR0o
   &code_challenge_method=S256
   &response_type=code
   &state=tbXZO4Fkxy90JvJx0s2sbt-FsK2yNK0tqYrX4YvPjB4
Note. A few carriage returns and blank spaces were added to the preceding request in order to make it easier to read. A real authorization request looks more like this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?&client_id=64430515-01ea-4f5d-82e4-c36161af0093&redirect_uri=https%3A%2F%2Foidc-playground.akamai.com%2Fredirect_uri&code_challenge= y63Qmobx6ZCSYCZqPNzQ6Qx1rGK0reaxgbb5WSAQR0o&code_challenge_method=S256&response_type=code&scope=openid%20email%20phone&state=tbXZO4Fkxy90JvJx0s2sbt-FsK2yNK0tqYrX4YvPjB4

The parameters used in the preceding authorization request, as well as additional parameters than can also be used in a request, are summarized in the table below:

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 login client used to make the authorization request. For example:

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


response_type 

Yes

Specifies the type of response expected from the authorization server; at this point in time the Identity Cloud only supports the code response type. Note that this parameter is required even though there’s only one supported response type:

response_type=code

The code response indicates that the client expects to get an authorization code back following a successful authentication. In turn, the client exchanges that code for a set of tokens.

scope

Yes

Specifies the OpenID Connect scopes to be accessible from the userinfo endpoint following a successful authentication and login. Note that you must include the scope parameter and, at a minimum, request the openid scope; this tells the authorization server that you want to authenticate by using OpenID Connect.

Other scopes supported by the Identity Cloud are detailed in the article OpenID Connect Scopes and Claims. You can request multiple scopes by separating each scope using a blank space:

scope=openid email profile

You can include any (or all) the supported scopes in your authentication request. However, that doesn’t mean that you’ll get back all of those scopes. Instead, the scopes made accessible from the userinfo endpoint depend on the value of the allowedScopes property found in the token policy applied during a user login. 

For example, suppose the allowedScopes property only specifies the openid and email scopes. In that case you can only get back those two scopes; any other scopes mentioned in your authorization request (such as profile or address) are ignored and are not returned.

redirect_uri

Yes

Specifies the URL of the page the user is redirected to following a successful authentication and login. For example:

redirect_uri=https://identitydocs.akamai.com/redirect

Note that the specified URL must be exactly match one of the URLs listed in the OIDC login client’s redirectURIs property. If the URL isn’t included in the redirectURIs property then the authorization request fails with an Invalid client error and the user will not be authenticated.

code_challenge

Yes (with PKCE)

Hashed and encoded value generated by the client. This value should be verified before the client is allowed to exchange an authorization code for a set of tokens.

For example:

code_challenge= RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg
3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYxRkM4NjQ0QzdBNw

code_challenge_method

Yes (with PKCE)

Hashing algorithm used to generate the value of the code_challenge parameter. For Hosted Login, this will always be S256:

code_challenge_method=S256


state

No (but recommended)

A random string that helps guard against cross-site request forgery (CSRF). For example, suppose your authentication includes the following state parameter and parameter value: 

state=GA-ISU_6CwFn0tQTFiYD_-Gvy39Nb6iTdugdGIzTUng

After a successful authentication, you’ll be redirected to the URL specified by the redirect_uri parameter. If you were redirected by the authorization server then the state parameter and value will be included in the URI:

https://identitydocs.akamai.com/redirect_uri?code=AH6S2WG_XchALC-p&state=GA-ISU_6CwFn0tQTFiYD_-Gvy39Nb6iTdugdGIzTUng

If the state parameter in the redirect URI doesn’t match your original parameter value then you might be the victim of CSFR attack (defined as an attack in which malware tries to trick you into carrying out some sort of action you never intended to carry out). In that case, you should restart the authentication process.

prompt

No

Specifies which screen (if any) is displayed when a user makes an authorization request. Allowed values are:

  • none (the default value). When set, Hosted Login checks to see if the user has a valid session before displaying a screen. If the user does not have a valid session then the sign-in screen is displayed and the user must log in. However, if a valid session is found then the sign-in screen is not displayed and the user is automatically logged in based on the current session.
     
  • login. The sign-in screen is always displayed first, even if a valid session is found. This ensures that users log in each time they access the site.
     
  • create. The traditional registration screen (used for creating new account) is always displayed first. Note, however, that the Sign In link isn’t found on the traditional registration screen. That means that setting the prompt to create represents a dead-end for existing users: they don’t need to create account, but they can’t log on using their existing account.

For example:

prompt=login


max_age

No

Specifies the amount of time, in seconds, that can elapse before a user is required to reauthenticate. For example, suppose the max_age parameter is set to 3600 seconds (one hour). A user logs on, leaves the website, then returns 30 minutes later. Because the max_age limit of 1 hour has not been reached, the user will automatically be authenticated and resume their previous session.

Now, suppose a second user logs on, leaves the website, then comes back 2 hours later. because the max_age value has been exceeded, this user will be forced to reauthenticate.

Note that the max_age parameter applies only to logins. Suppose a third user logs on and stays on the site for 2 hours. That user will not be forced to reauthenticate halfway through their session. As noted, max_age only applies to logins.

ui_locales

No

Specifies the language/locale used when displaying Hosted Login login, registration, and user profile screens. Language preferences are passed as a space-delimited set of RFC 5646 language codes. For example:

ui_locales= fr-FR es-ES

In the preceding example, Hosted Login first tries to render screens by using French (fr-FR); if that fails, Hosted Login tries to render the screens by using Spanish (es-ES). If that fails, then Hosted Login defaults to displaying all screens in English.

Why would an attempt to render screens fail? This is almost always because you specified a language/locale that can’t be found in your flow: you can specify any language or locale that you want, but to actually display screens using that language/locale requires you to have the locale (and the accompanying translations) in your flow. See this article for more information.


login_hint

string

Provides a way to prepopulate the email address field on the Hosted Login sign-in screen. In your authorization request, include the login_hint parameter followed by the email address of the user who needs to be authenticated. For example:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
    &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
    &redirect_uri=https%3A%2F%2Fwacky-harmonious-bike.dev.or.janrain.com%2Fredirect_uri
    &code_challenge=MJm7VEGLvMtD4Mi1SGUc2QPRPVKqyaoEbBTxYKC4UJk
    &code_challenge_method=S25
    &response_type=code
    &scope=openid
    &state=5TK5-3LXryr8EIxn6kV4mgqEa3KqRA4-HwHJbyzlgU0
    &login_hint=gmstemp@hotmail.com

When you submit your authorization request, the email address will be included on the sign-in screen:

Note that Hosted Login cannot determine the email address to be included in the authorization request. Instead, you will need to use an alternate approach to determine the email address (for example, getting the email address when the user logs on to the computer) and then take the steps needed to add that address to the authorization request.

claims

No

Specifies the claims (i.e., user profile attributes) to be included in the identity token or to be made accessible from the userinfo endpoint (or both). These claims can either be standard OpenID Connect claims (see OpenID Connect Scopes and Claims for more information) or custom claims created by your organization and defined in your login policies.

For example, this syntax makes the birthdate claim accessible from the userinfo endpoint:

&claims={"userinfo":{"birthdate":null}}

Meanwhile, this syntax adds a custom claim named organization to the identity token:

&claims={"id_token":{"organization":null}}

And this syntax makes the organization claim accessible from the userinfo endpoint and adds that same claim to the identity token:

&claims={"userinfo":{"organization":null}, "id_token":{"organization":null}} 


display

No

Specifies where (and how) the sign-in screen is displayed. Allowed values are:

  • page (the default value)., When you submit your authorization request, you’ll be redirected to a separate page that contains the sign-in screen (and nothing but the sign-in screen). After you’ve successfully logged on you'll be redirected to the page specified in the redirectURIs property of your OIDC client.
     
  • popup. When you submit your authorization request you are not redirected to a standalone login page. Instead, the login page appears in a pop-up window, no redirection required. After you’ve successfully logged on then you’ll be redirected to the page specified in the redirectURIs property of your OIDC client.

For example:

display=page


nonce

No, but recommended


Helps ensure that the identity token you receive is the same identity token that you requested (in other words, you got back a token sent in direct response to your authentication request).

To use the nonce parameter, simply enter a random string in the Nonce field and then make your authentication request, When you decode the returned identity token, you should see a nonce property. The value in the identity token should be the same as the value included in your authentication request.

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 endpoint https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize:


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.


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.


     

     


/{customerId}/auth-ui/profile

Back to top


Access a user's user profile.

Description

The /{customerId}/auth-ui/profile endpoint opens the Manage Profile screen for the user associated with the active session. For example, if August Joseph Springer logs on to a site and “owns” the active session, then calling the /{customerId}/auth-ui/profile endpoint brings up his Manage Profile screen:

As you probably noticed, this means that no authentication is needed to call the /{customerId}/auth-ui/profile endpoint: instead, access to the endpoint relies on a cookie that points to the active Hosted Login session. If there is no such cookie, and thus no active session, then your call to this endpoint fails with the following error:

However what is needed to call this endpoint is the ID of the OIDC client that the user employed when logging in. The client_id parameter is one of three parameters available for use with the /{customerId}/auth-ui/profile endpoint:

Parameter

Required

Description

client_id

Yes

Unique identifier of the OIDC client that the user employed when logging on. If this parameter isn’t included in the authorization request you’ll get a Bad request error:

If the parameter is included, but you specify an invalid client ID, you’ll get a Something went wrong error:

redirect_uri

No

When present, specifies the URL that users should be redirected to if they click Logoff in their user profile. Note that the specified URL must be included in the OIDC client’s redirect_uri property. If it’s not, the user profile will not be opened and the Something went wrong error messageis displayed.

If there's no active Hosted Login session then the No authenticated ession found OAuth error is returned to the app.

And, of course, no user profile is displayed.

state

No

An arbitrary value that can be used to track a redirect after the user has clicked Logoff in their user profile. For example, suppose state is set to 87651431 and the redirect_uri is set to https://identitydocs.akamai.com/redirect. When a user clicks Logoff and is redirected, the URI they’re redirected to should look like this:

https://identitydocs.akamai.com/redirect?state=87651431

Including the state in the URI provides assurance that Hosted Login was responsible for the redirect.


Sample Request

For example, this command opens the Manage Profile page for the current user and, after the user clicks Logoff, redirects the user to https://oidc-playground.akamai.com/redirect_uri:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile
 ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
 &redirect_uri=https://oidc-playground.akamai.com/redirect_uri

You can also directly access the individual sections of your user profile by using these URLs:

  • Personal Data: https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile/data?client_id=64430515-01ea-4f5d-82e4-c36161af0093
     
  • Account Security: https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile/security?client_id=64430515-01ea-4f5d-82e4-c36161af0093
     
  • Privacy Settings: https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile/privacy?client_id=64430515-01ea-4f5d-82e4-c36161af0093




     

     


/{customerId}/auth-ui/logout

Back to top


Logs a user out of a Hosted Login session.

Description

The /{customerId}/auth-ui/logout endpoint logs a user out of a Hosted Login session. This brings the user session to a close, but does not expire or otherwise invalidate the user’s access and refresh tokens. To invalidate the tokens, you need to call the /{customerId}/token/revoke endpoint.

For example, this command logs a user out of his or her current session and then, following a successful logout, redirects the user to the URL https://identitydocs.akamai.com/logout:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/logout
 ?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://identitydocs.akamai.com/logout

The parameters available for use with the /{customerId}/auth-ui/logout endpoint are described in the following table:

Parameter

Required

Description

client_id

Yes

Unique identifier of a valid OIDC client; it’s recommended that you reference the same OIDC client that the user employed when logging on. If you omit this parameter you’ll see the following error message:

If the parameter is included, but you specify an invalid client ID, you’ll get a Something went wrong error:

redirect_uri

No

When present, the user is redirected to the specified URL after he or she is logged out. Note that this URL must be included in the OIDC client’s redirectURIs property. If the URL is not listed then a Something went wrong error message is displayed.

If logout is successful but the redirect_uri is not included in the call then the Logout Success screen is displayed:

state

No

An arbitrary value that can be used to track a redirect after the user has is logged off by using this endpoint. For example, suppose state is set to 87651431 and the redirect_uri is set to https://identitydocs.akamai.com/redirect. When a user is logged off and redirected, the URI they’re redirected to should look like this:

https://identitydocs.akamai.com/redirect?state=87651431

Including the state in the URI provides assurance that Hosted Login was responsible for the redirect.

No authentication is required to call the /{customerId}/auth-ui/logout endpoint. Instead, the endpoint automatically logs out the user associated with the active session.

Calling the /{customerId}/auth-ui/logout endpoint is equivalent to a user clicking the Logout button in his or her user profile.