Supported response types

Suggest Edits

OAuth response types (and the response_type parameter) provide a way for you to specify the items you want to get back following a successful authentication. Hosted Login supports the following response types (also referred to as flows):

code. Returns an authorization code following a successful authentication. This code can then be exchanged at the token endpoint for an access token, a refresh token, and an identity token.
token. The authorization endpoint returns an access token following a successful authentication.
id_token. The authorization endpoint returns an identity token following a successful authentication.

Some of these response types can be combined with other types. For example, consider this syntax:

response_type=code id_token

The preceding request returns an authorization code and an identity token. Both of those items are issued by the authorization endpoint: the client never visits the token endpoint. However, if you want an access token and a refresh token, you'll need to visit the token endpoint and exchange the authorization code for a standard set of Hosted Login tokens.

The response_type parameter is also used to trigger the three grant types ) most-commonly used for user authorization: the authorization_code flow, the implicit flow, and the hybrid flow. If an authorization request includes only the code response type (i.e., response_type=code) then you’re requesting the authorization_code flow. If you see a flow that includes the code response type plus anything else (token or id_token), then you’re dealing with a hybrid flow. For example:

response_type=code id_token

And if you see a response type that doesn’t include the code type then you’re dealing with an implicit flow:

response_type=id_token

The similarities (and differences) among these three grant types are summarized in the following table:

Feature	Authorization Code	Implicit	Hybrid
An authorization code is required in order to obtain tokens	✓	✗	You can get an access token or an identity token directly from the authorize endpoint, but a refresh token requires you to exchange the authorization code at the token endpoint
All tokens are returned from the authorize endpoint	✗	✓	✓ (unless you want a refresh token)
All tokens are returned from the token endpoint	✓	✗	✗
Tokens are transferred by using the HTTP user-Agent	✗	✓	✓
Refresh tokens are returned	✓	✗	Only if you exchange the authorization code at the token endpoint
Requires multiple calls	✓	✗	✗ (unless you want a refresh token)
Clients can be authenticated	✓	✓	✓

Manage response types

Although Hosted Login supports three different response types (code, token, and id_token), only code and id_token are supported by default. If you want to use the token response type you’ll need to update the login policy associated with your OIDC login client. If you make an authorization request that uses an invalid response type you’ll get an “invalid response_type” error:

For example, suppose you want to be able to use any of the supported response types in any authorization request. In that case, you’ll need to use the /loginPolicies endpoint and the PUT method. For example:

curl -L -X PUT \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/allowedResponseTypes' \
  -H 'Authorization: Bearer cBviooa_cmjNcax6MULDgDepVDN6xLueoWlPfw2x2vMdaNUyWCSqcXAmRjV5tw4H' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    "code",
    "id_token",
    "token"
]'

As you can see, all three response types are listed (as a JSON array) in the request body of your API call. In Postman that request body parameter would look like this:

Because you’re using the PUT method, it’s important that you include all the desired response types in your API call. (That’s because the PUT method replaces the existing set of allowed response types with whatever happens to be in the request body of your API call.) For example, suppose your login policy already supports the code and id_token types, and you’d like to add token to the list. To do that, you make the following API call, a call that includes only the token type:

curl -L -X PUT \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/allowedResponseTypes' \
  -H 'Authorization: Bearer cBviooa_cmjNcax6MULDgDepVDN6xLueoWlPfw2x2vMdaNUyWCSqcXAmRjV5tw4H' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    "token"
]'

If your API call succeeds, you'll see the response types supported by the login policy:

[
    "token"
]

Because token was the only response type included in the API call, token is now your only supported type: all the response types previously in the login policy have been removed. (Fortunately, these “lost” types can easily be replaced.) When working with response types, make sure the request body of your API call includes all of your existing response types as well as the new types being added:

[
    "code",
    "id_token",
    "token"
]

Incidentally, although the allowed response types are kept in the login policy, those response types don’t show up if you use the /loginPolicies/{loginPolicyId} endpoint to return the property values of a login policy:

{
    "id": "1e1ab726-f4b5-4bad-ba45-877027af4097",
    "identityStoreDetails": {
        "type": "janrainCapture",
        "connectionDetails": {
            "domain": "us-dev.janraincapture.com",
            "applicationId": "ces7u7uwwudrxtz933jvbehzne",
            "entityType": "user",
            "clientId": "6s7q89env535ek49hkz6hjsh3jgs93ud",
            "clientSecret": "7b7eqyuswtnpaa6zxdvuafum56r4cbsw"
        }
    },
    "loginURL": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/login",
    "title": "Dev Login Policy",
    "_links": {
        "self": {
            "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097"
        }
    }
}

Instead, you must use the /loginPolicies/{loginPolicyId}/allowedResponseTypes endpoint and the GET method to return information about the response types allowed by a login policy, For example:

curl -L -X GET \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/allowedResponseTypes' \
  -H 'Authorization: Bearer cBviooa_cmjNcax6MULDgDepVDN6xLueoWlPfw2x2vMdaNUyWCSqcXAmRjV5tw4H'

The preceding API call returns information similar to the following:

[
    "id_token",
    "token",
    "code"
]

Supported response types

The following sections provide a more detailed look at the response types supported by Hosted Login.

response_type=code

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Token endpoint	Token endpoint	Token endpoint

Grant Type: Authorization code

Supported response modes

query	fragment	form_post
✓	✓	✓

This is the recommended flow to be used when authorizing a user. When the response_type is set to code, the user logs on to Hosted Login; if authentication succeeds, the authorization endpoint issues an authorization code to the client. The client must then go to the token endpoint and exchange that code for an access token, a refresh token, and an identity token. This offers an extra layer of security; that’s because, in addition to the authorization code, the client must provide one of the following:

The client ID and client secret of the confidential OIDC login client (if using the basic Authorization Code flow).
The code verifier, if using Proof Key for Code Exchange (PKCE). This is the recommended approach when using the Authorization code grant.

An authorization request that uses code as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code
    &state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

Following a successful authentication, the user is redirected to the specified URL and is issued an authorization code. If the response mode is set to fragment (the default response mode), the authorization code will be visible in the redirect URI:

http://localhost/?code=Abh7F4HhxZ-Wy2Dk&state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

response_type=token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
n/a	Authorization endpoint	n/a	n/a

Grant Type: Implicit

Supported response modes

query	fragment	form_post
✗	✓	✓

In this flow, the client contacts the authorization endpoint and, following a successful authentication, is issued an access token. No authorization code is issued, and the client never contacts the token endpoint. Because there is no authorization code, this flow is an example of the implicit grant.

The implicit grant was originally developed for use with user agent applications: JavaScript applications running within a web browser. However, because of security risks (for example, anything passed from the server to the client – such as an access token – is visible to the browser) the implicit grant has largely been superseded by the Authorization code + PKCE grant type. Despite that, Hosted Login does allow you to use the implicit grant; this helps the Identity Cloud provide full support for the OAuth standards.

Keep in mind that, with this flow, the client is only issued an access token; the client doesn’t get an identity token or a refresh token.

An authorization request that uses token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=token
    &state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

Following a successful authentication, the user is redirected to the specified URL and is issued an access token. If the response mode is set to fragment (the default response mode), the access token will be visible in the redirect URI:

http://localhost/
    #access_token=q_g8T48bPOEd9KB9mgkDz2w2O0wM8aCGC4fiQm7RTajFnKfdzPphgoEVFUBzlZsd
    &expires_in=3600
    &scope=openid+%252A%253Alogin%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fcallback+%252A%253Alogin%252Ftoken+%252A%253Aprofiles%252Foidc%252Fuserinfo+.%253Aprofiles%252Foidc%252Fuserinfo+%252B%253Aprofiles%252Foidc%252Fuserinfo&state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &token_type=Bearer

response_type=id_token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
n/a	n/a	Authorization endpoint	n/a

Grant Type: Implicit

Supported response modes

query	fragment	form_post
✗	✓	✓

In this flow, the client contacts the authorization endpoint and, following a successful authentication, that endpoint issues the client an identity token. No authorization code is issued, and the client never contacts the token endpoint. Because there is no authorization code, this flow is one version of the implicit grant.

The implicit grant was originally developed for use with user agent applications: JavaScript applications running within a web browser. However, because of security risks (for example, anything passed from the server to the client – such as an access token – is visible to the browser) the implicit grant has largely been superseded by PKCE. Despite that, Hosted Login does allow you to use the implicit grant; this helps the Identity Cloud provide full support for the OAuth standards.

Keep in mind that, with this flow, the client is only issued an identity token; the client doesn’t get an access token or a refresh token.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

After you have been issued your identity token, the nonce should appear in your token. If it doesn’t, or if the value in the token differs from the value in the authorization request, you’re likely dealing with an invalid ID token.

An authorization request that uses id_token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost&scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=id_token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &nonce=mst3k

Following a successful authentication, the user is redirected to the specified URL and is issued an identity token. If the request mode is set to fragment (the default request mode), the identity token will be visible in the redirect URI:

http://localhost/
    #id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3NvdXJjZXMiOnsiaWRfdG9rZW5faGludCI6eyJKV1QiOiJleU ...

Note that, in order to save space, we’ve dramatically truncated the number of characters found in an identity token.

response_type=id_token token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
n/a	Authorization endpoint	Authorization endpoint	n/a

Grant Type: Implicit

Supported response modes

query	fragment	form_post
✗	✓	✓

Note that it makes no difference how you order the elements in the parameter value: response_type=id_token token works exactly the same as response_type= token id_token. However, duplicating a response type (for example, response_type= id_token id_token token) results in an “unsupported response type” error.

In this variation on the implicit grant, a successful authentication results in the authorization endpoint issuing the client an access token and an identity token (but not an access token). As is always the case with an implicit grant, the authorization endpoint is responsible for issuing tokens, and the client does not have to visit the token endpoint.

As with other implicit grant flows, the following disclaimer applies: the implicit grant was originally developed for use with user agent applications: JavaScript applications running within a web browser. However, because of security risks (for example, anything passed from the server to the client – such as an access token – is visible to the browser) the implicit grant has largely been superseded by PKCE. Despite that, Hosted Login does allow you to use the implicit grant; this helps the Identity Cloud provide full support for the OAuth standards.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses id_token token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost&scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=id_token token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &nonce=4hef47hfjdsdnfja

Following a successful authentication, the user is redirected to the specified URL and is issued an identity token and an access token. If the response mode is set to fragment (the default response mode), both tokens will be visible in the redirect URI:

http://localhost/
    #access_token=_p9lSXW6EXHZu37cGh7_SGdQGUzNxMMXgioqbySUbeCXIzf6Eq-i_ZEjM4VOoYoY
    &expires_in=3600
    &id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3NvdXJjZXMiOnsiaWRfdG9rZW5faGludCI6eyJKV1QiOiJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWk ...

Note that, in order to save space, we’ve dramatically truncated the number of characters found in an identity token.

response_type=code id_token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Token endpoint	Initially from the authorization endpoint. If the authorization code is exchanged, a second identity token is issued from the token endpoint.	Token endpoint

Grant Type: Hybrid

Supported response modes

query	fragment	form_post
✗	✓	✓

Note that it makes no difference how you order the elements in the parameter value: response_type=id_token code works exactly the same as response_type=code id_token. However, duplicating a response type (for example, response_type= code code id_token) results in an “unsupported response type” error.

In this flow, the client contacts the authorization endpoint; following a successful authentication, the authorization endpoint issues the client an authorization code and an identity token. It’s then up to the client to go to the token endpoint and exchange the authorization code for an access token, a refresh token, and an updated identity token.

It’s important to note that the identity token is returned in the “front channel;” that means that the token is accessible to the browser (user agent). Because of that, you should make sure that no personally-identifiable information is included in your identity tokens. (This is not a problem when it comes to the access tokens: that’s because the access token is obtained by exchanging the authorization code at the token endpoint and is then sent via the more-secure back channel.)

This flow (a variation of the hybrid grant) is typically used by organizations that want “early access” to the identity token: getting the identity token first allows you to do some sort of pre-processing/personalization before the user gets their access token and is fully-logged on.

The response_type=code id_token flow is also recommend by the OpenID Foundation group working on the Financial-grant API (FAPI) as a way to thwart “Identity provider (IdP) mix-up attacks,” an attack in which a client is tricked into sending its authorization request (and, eventually, its authorization code) to a “rogue” IdP that shares a client ID with a valid IdP. To avoid this issue, the hybrid grant enables the client to extract the value of the identity token’s iss claim. The client can then ensure that the authorization code is sent to the token endpoint associated with the issuer identifier specified in the iss claim.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses code id_token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost 
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code id_token
    &state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
&nonce=mst3k

Following a successful authentication, the user is redirected to the specified URL and is issued an authorization code and an identity token. If the response mode is set to fragment (the default response mode), the authorization code and the identity token will be visible in the redirect URI:

http://localhost/
    #code=M6-UuXv_12se-y4Q
    &id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3NvdXJjZXMiOnsiaWRfdG9rZW5faGludCI6eyJKV1QiOiJleUowZVhBaU9pSktW ...

Note that, in order to save space, we’ve dramatically truncated the number of characters found in an identity token.

response_type=code token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Initially from the authorization endpoint. If the authorization code is exchanged, a second access token is issued from the token endpoint.	Token endpoint	Token endpoint

Grant Type: Hybrid

Supported response modes

query	fragment	form_post
✗	✓	✓

Note that it makes no difference how you order the elements in the parameter value: response_type= token code works exactly the same as response_type=code token. However, duplicating a response type (for example, response_type= code code token) results in an “unsupported response type” error.

In this flow (a variation of the hybrid grant type), the user logs in and, if successfully authenticated, the authorization endpoint issues an access token and an authorization code. If appropriate, the user can use the access token and ignore the authorization code. Alternatively, the client can visit the token endpoint and exchange the authorization code for the typical token set: an access token, a refresh token, and an identity token. At that point, the user will actually have four tokens:

An access token issued by the authorization endpoint.
An access token issued by the token endpoint.
An refresh token issued by the token endpoint.
An identity token issued by the token endpoint.

Note that having two access tokens doesn’t cause any problems: the user can employ either token. As noted previously, the user doesn’t have to exchange the authorization code: the value of making that exchange is that they get an identity token plus an access token that’s associated with a refresh token. That means that, if and when the access token issued by the token endpoint expires, the client can use the refresh token to request a new token. By comparison, if you use the access token issued by the authorization endpoint and that token expires, you’ll have to go back through the authentication process in order to get a new token. That’s because there’s no refresh token associated with the authorization endpoint’s access token.

An authorization request that uses code token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost&scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

Following a successful authentication, the user is redirected to the specified URL and is issued an authorization code and an access. If the response mode is set to fragment (the default response mode), both the authorization code and the access token will be visible in the redirect URI:

http://localhost/
    #access_token=haXcwJR1xarUHq54eyHuno5XU3Ub2nj34pXqMyjXR1ngLyjTTFkc3JOHgWYzqGme
    &code=1Qbhq04fEvaIaUtC
    &expires_in=3600
    &scope=openid+%252A%253Alogin%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fcallback+%252A%253Alogin%252Ftoken+%252A%253Aprofiles%252Foidc%252Fuserinfo+.%253Aprofiles%252Foidc%252Fuserinfo+%252B%253Aprofiles%252Foidc%252Fuserinfo&state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
&token_type=Bearer

response_type=code id_token token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Initially from the authorization endpoint. If the authorization code is exchanged, a second access token is issued from the token endpoint.	Initially from the authorization endpoint. If the authorization code is exchanged, a second identity token is issued from the token endpoint.	Token endpoint

Grant Type: Hybrid

Supported response modes

query	fragment	form_post
✗	✓	✓

Note that it makes no difference how you order the elements in the parameter value: response_type=id_token token code works exactly the same as response_type=code id_token token. However, duplicating a response type (for example, response_type= code code id_token token) results in an “unsupported response type” error.

With this flow (another version of the hybrid grant), a user logs on to Hosted Login; if authentication succeeds, the authorization endpoint issues the user an authorization code, an access token, and an identity token. The two tokens can be used as-is; the only thing to keep in mind is that the authorization endpoint doesn’t issue a refresh token. That means that, when the access token expires, the user will have to go through the authentication process again in order to get a replacement token.

Unless, of course, the authorization code is exchanged at the token endpoint for an access token, a refresh token, and an identity token. At that point the user will have five tokens:

An access token issued by the authorization endpoint.
An identity token issued by the authorization endpoint.
An access token issued by the token endpoint.
An refresh token issued by the token endpoint.
An identity token issued by the token endpoint.

Obviously there’s some duplication here: the user has two access tokens and two identity tokens. But that’s OK: having multiple tokens won’t cause any problems. And while the user can employ either token, the best practice is to use the access token issued by the token endpoint; that’s because this token is associated with a refresh token.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses code id_token token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code id_token token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &nonce=4hef47hfjdsdnfja

Following a successful authentication, the user is redirected to the specified URL and is issued an authorization code, an access token, and an identity token. If the response mode is set to fragment (the default response mode), the authorization code and both tokens will be visible in the redirect URI:

http://localhost/
    #access_token=vDscbAiYHyKLSGn67U3eNQtCLH8tPPtV6RA5pn4pzl9hYCDZlUKz1Jc3ayF3jGJC
    &code=b6THxXp7lhZb7yvB
    &expires_in=3600
    &id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3tcu5YiqbycKE8QjVWEmeng ... &token_type=Bearer

code. Returns an authorization code following a successful authentication. This code can then be exchanged at the token endpoint for an access token, a refresh token, and an identity token.
token. The authorization endpoint returns an access token following a successful authentication.
id_token. The authorization endpoint returns an identity token following a successful authentication.

Some of these response types can be combined with other types. For example, consider this syntax:

response_type=code id_token

The response_type parameter is also used to trigger the three flows most-commonly used for user authorization: the authorization_code flow, the implicit flow, and the hybrid flow. If an authorization request includes only the code response type (i.e., response_type=code) then you’re requesting the authorization_code flow. If you see a flow that includes the code response type plus anything else (token or id_token), then you’re dealing with a hybrid flow. For example:

response_type=code id_token

And if you see a response type that doesn’t include the code type then you’re dealing with an implicit flow:

response_type=id_token

The similarities (and differences) among these three grant types are summarized in the following table:

Feature	Authorization Code	Implicit	Hybrid
An authorization code is required in order to obtain tokens	✓	✗	You can get an access token or an identity token directly from the authorize endpoint, but a refresh token requires you to exchange the authorization code at the token endpoint
All tokens are returned from the authorize endpoint	✗	✓	✓ (unless you want a refresh token)
All tokens are returned from the token endpoint	✓	✗	✗
Tokens are transferred by using the HTTP user-Agent	✗	✓	✓
Refresh tokens are returned	✓	✗	Only if you exchange the authorization code at the token endpoint
Requires multiple calls	✓	✗	✗ (unless you want a refresh token)
Clients can be authenticated	✓	✓	✓

Manage response types

curl -L -X PUT \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/allowedResponseTypes' \
  -H 'Authorization: Bearer cBviooa_cmjNcax6MULDgDepVDN6xLueoWlPfw2x2vMdaNUyWCSqcXAmRjV5tw4H' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    "code",
    "id_token",
    "token"
]'

As you can see, all three response types are listed (as a JSON array) in the request body of your API call. In Postman that request body would look like this:

curl -L -X PUT \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/allowedResponseTypes' \
  -H 'Authorization: Bearer cBviooa_cmjNcax6MULDgDepVDN6xLueoWlPfw2x2vMdaNUyWCSqcXAmRjV5tw4H' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    "token"
]'

If your API call succeeds, you'll see the response types supported by the login policy:

[
    "token"
]

[
    "code",
    "id_token",
    "token"
]

{
    "id": "1e1ab726-f4b5-4bad-ba45-877027af4097",
    "identityStoreDetails": {
        "type": "janrainCapture",
        "connectionDetails": {
            "domain": "us-dev.janraincapture.com",
            "applicationId": "ces7u7uwwudrxtz933jvbehzne",
            "entityType": "user",
            "clientId": "6s7q89env535ek49hkz6hjsh3jgs93ud",
            "clientSecret": "7b7eqyuswtnpaa6zxdvuafum56r4cbsw"
        }
    },
    "loginURL": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/login",
    "title": "Dev Login Policy",
    "_links": {
        "self": {
            "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097"
        }
    }
}

Instead, you must use the /loginPolicies/{loginPolicyId}/allowedResponseTypes endpoint and the GET method to return information about the response types allowed by a login policy, For example:

curl -L -X GET \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/allowedResponseTypes' \
  -H 'Authorization: Bearer cBviooa_cmjNcax6MULDgDepVDN6xLueoWlPfw2x2vMdaNUyWCSqcXAmRjV5tw4H'

The preceding API call returns information similar to the following:

[
    "id_token",
    "token",
    "code"
]

Supported response types

The following sections provide a more detailed look at the response types supported by Hosted Login.

response_type=code

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Token endpoint	Token endpoint	Token endpoint

Grant Type: Authorization code

Supported response modes

query	fragment	form_post
✓	✓	✓

The client ID and client secret of the confidential OIDC login client (if using the basic Authorization Code flow).
The code verifier, if using Proof Key for Code Exchange. This is the recommended approach when using the Authorization code grant.

An authorization request that uses code as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code
    &state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

Following a successful authentication, the user is redirected to the specified URL and is issued an authorization code. If the response modes is set to fragment (the default response mode), the authorization code will be visible in the redirect URI:

http://localhost/?code=Abh7F4HhxZ-Wy2Dk&state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

response_type=token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
n/a	Authorization endpoint	n/a	n/a

Grant Type: Implicit

Supported response modes

query	fragment	form_post
✗	✓	✓

The implicit grant was originally developed for use with user agent applications: JavaScript applications running within a web browser. However, because of security risks (for example, anything passed from the server to the client – such as an access token – is visible to the browser) the implicit grant has largely been superseded by PKCE (Proof Key for Code Exchange). Despite that, Hosted Login does allow you to use the implicit grant; this helps the Identity Cloud provide full support for the OAuth standards.

Keep in mind that, with this flow, the client is only issued an access token; the client doesn’t get an identity token or a refresh token.

An authorization request that uses token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=token
    &state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

http://localhost/
    #access_token=q_g8T48bPOEd9KB9mgkDz2w2O0wM8aCGC4fiQm7RTajFnKfdzPphgoEVFUBzlZsd
    &expires_in=3600
    &scope=openid+%252A%253Alogin%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fcallback+%252A%253Alogin%252Ftoken+%252A%253Aprofiles%252Foidc%252Fuserinfo+.%253Aprofiles%252Foidc%252Fuserinfo+%252B%253Aprofiles%252Foidc%252Fuserinfo&state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &token_type=Bearer

response_type=id_token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
n/a	n/a	Authorization endpoint	n/a

Grant Type: Implicit

Supported response modes

query	fragment	form_post
✗	✓	✓

The implicit grant was originally developed for use with user agent applications: JavaScript applications running within a web browser. However, because of security risks (for example, anything passed from the server to the client – such as an access token – is visible to the browser) the implicit grant has largely been superseded by PKCE (Proof Key for Code Exchange). Despite that, Hosted Login does allow you to use the implicit grant; this helps the Identity Cloud provide full support for the OAuth standards.

Keep in mind that, with this flow, the client is only issued an identity token; the client doesn’t get an access token or a refresh token.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses id_token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost&scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=id_token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &nonce=mst3k

http://localhost/
    #id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3NvdXJjZXMiOnsiaWRfdG9rZW5faGludCI6eyJKV1QiOiJleU ...

Note that, in order to save space, we’ve dramatically truncated the number of characters found in an identity token.

response_type=id_token token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
n/a	Authorization endpoint	Authorization endpoint	n/a

Grant Type: Implicit

Supported response modes

query	fragment	form_post
✗	✓	✓

As with other implicit grant flows, the following disclaimer applies: the implicit grant was originally developed for use with user agent applications: JavaScript applications running within a web browser. However, because of security risks (for example, anything passed from the server to the client – such as an access token – is visible to the browser) the implicit grant has largely been superseded by PKCE (Proof Key for Code Exchange). Despite that, Hosted Login does allow you to use the implicit grant; this helps the Identity Cloud provide full support for the OAuth standards.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses id_token token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost&scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=id_token token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &nonce=4hef47hfjdsdnfja

http://localhost/
    #access_token=_p9lSXW6EXHZu37cGh7_SGdQGUzNxMMXgioqbySUbeCXIzf6Eq-i_ZEjM4VOoYoY
    &expires_in=3600
    &id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3NvdXJjZXMiOnsiaWRfdG9rZW5faGludCI6eyJKV1QiOiJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWk ...

Note that, in order to save space, we’ve dramatically truncated the number of characters found in an identity token.

response_type=code id_token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Token endpoint	Initially from the authorization endpoint. If the authorization code is exchanged, a second identity token is issued from the token endpoint.	Token endpoint

Grant Type: Hybrid

Supported response modes

query	fragment	form_post
✗	✓	✓

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses code id_token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost 
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code id_token
    &state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
&nonce=mst3k

http://localhost/
    #code=M6-UuXv_12se-y4Q
    &id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3NvdXJjZXMiOnsiaWRfdG9rZW5faGludCI6eyJKV1QiOiJleUowZVhBaU9pSktW ...

Note that, in order to save space, we’ve dramatically truncated the number of characters found in an identity token.

response_type=code token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Initially from the authorization endpoint. If the authorization code is exchanged, a second access token is issued from the token endpoint.	Token endpoint	Token endpoint

Grant Type: Hybrid

Supported response modes

query	fragment	form_post
✗	✓	✓

An access token issued by the authorization endpoint.
An access token issued by the token endpoint.
An refresh token issued by the token endpoint.
An identity token issued by the token endpoint.

An authorization request that uses code token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost&scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng

http://localhost/
    #access_token=haXcwJR1xarUHq54eyHuno5XU3Ub2nj34pXqMyjXR1ngLyjTTFkc3JOHgWYzqGme
    &code=1Qbhq04fEvaIaUtC
    &expires_in=3600
    &scope=openid+%252A%253Alogin%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fauthorize+.%253Alogin%252Fprovider%252F%252A%252Fcallback+%252A%253Alogin%252Ftoken+%252A%253Aprofiles%252Foidc%252Fuserinfo+.%253Aprofiles%252Foidc%252Fuserinfo+%252B%253Aprofiles%252Foidc%252Fuserinfo&state=LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
&token_type=Bearer

response_type=code id_token token

Codes/tokens are issued from the following locations:

Authorization Code	Access Token	Identity Token	Refresh Token
Authorization endpoint	Initially from the authorization endpoint. If the authorization code is exchanged, a second access token is issued from the token endpoint.	Initially from the authorization endpoint. If the authorization code is exchanged, a second identity token is issued from the token endpoint.	Token endpoint

Grant Type: Hybrid

Supported response modes

query	fragment	form_post
✗	✓	✓

Unless, of course, the authorization code is exchanged at the token endpoint for an access token, a refresh token, and an identity token. At that point the user will have five tokens:

An access token issued by the authorization endpoint.
An identity token issued by the authorization endpoint.
An access token issued by the token endpoint.
An refresh token issued by the token endpoint.
An identity token issued by the token endpoint.

📘
When requesting an identity token, you must include the nonce parameter in your authorization request. If you don’t, your request will fail with a “Nonce is required when response_type is _id_token” error. The nonce is simply a random string added to the authorization request:
nonce=ewy4hw3e4hn328ncdjfgndf

An authorization request that uses code id_token token as the request_type will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=http://localhost
    &scope=openid
    &code_challenge=ufBhlb8CfzV874maXPFHIguVkjBYssKgi8L5Ec
    &code_challenge_method=S256
    &response_type=code id_token token
    &state= LA6fKYw_1_7x_xrSpJQlStcu5YiqbycKE8QjVWEmeng
    &nonce=4hef47hfjdsdnfja

http://localhost/
    #access_token=vDscbAiYHyKLSGn67U3eNQtCLH8tPPtV6RA5pn4pzl9hYCDZlUKz1Jc3ayF3jGJC
    &code=b6THxXp7lhZb7yvB
    &expires_in=3600
    &id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1QifQ.eyJfY2xhaW1fbmFtZXMiOnsiZ2xvYmFsX3N1YiI6ImlkX3Rva2VuX2hpbnQifSwiX2NsYWltX3tcu5YiqbycKE8QjVWEmeng ... &token_type=Bearer

Updated over 2 years ago