/{customer_id}/config/loginPolicies//{login_policy_id} | Akamai Identity Cloud Education Center

Login policies help manage the user login experience by doing such things as: specifying the exact path to the Capture domain and the user profile entity type, and defining the login URL for the associated directory. All OpenID Connect clients (public and confidential) must be associated with one (but only one) login policy.

Login policies can also be used to specify custom claims: custom claims provide a way to return user profile attributes that are not returned by any of your predefined scopes. For example, suppose you have a custom attribute – newsletterSubscriber– that is not returned by any of your Hosted Login scopes. You cannot add this attribute to any of your existing scopes, nor can you create a new scope. However, in your login policy you can define a custom claim that will return the newsletterSubscriber attribute:

"customClaims": {
       "id_token": 
           {"subscriber": "newsletterSubscriber"}
     }

In the preceding example, a unique claim name (subscriber) is mapped to the newsletterSubscriber attribute. In addition, the value id_token indicates that the custom claim should be returned as part of the identity token. For example:

{
  "iss": "accounts.akamai-documentation.com",
  "sub": "8855454e-8146-11e8-adc0-fa7ae01bbebc",
  "aud": "c2a5b7bc-e329-b4e4-dd6b-eb1ae01c22aa",
  "iat": 1530897246,
  "exp": 1530900246,
  "jti": "ID.rWH0iZkhFNxAoDxR5LhLAOqNj2bQvmMaeQiqhH5BcAU",
  "subscriber": true
}

Alternatively, you can replace id_token with userinfo. When you do that, the custom claim is not returned as part of the identity token; instead, it’s returned when you make a call to the userinfo endpoint.

For more information, see the article OpenID Connect Scopes and Claims.

Authentication

This endpoint requires token-based authentication. To obtain an access token, you must use a configuration client (using the client ID as the username and the client secret as the password) to access the /{customer_id}}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. For example, if you get back the access token Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB then your Authorization header would look like this when using Curl:

-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.

Methods

This endpoint supports the following methods:

GET
PUT
DELETE

GET

Description

Returns information about the specified login policy. All OpenID Connect clients used for logins and registrations must be associated with a login policy.

Path Parameters

The path parameters that must be included in the request are listed in the following table:

Name	Type	Required	Description
{customer_id}	string	Yes	Unique identifier of the customer associated with the login policy.
{token_policy_id}	string	Yes	Unique identifier of the login policy to be returned.

Sample Request (Curl)

The following command returns information about the login policy with the policy ID d4308c4d-f5d5-403f-bbb4-403dbdb3efe6:

curl -X GET \
 https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/loginPolicies/d4308c4d-f5d5-403f-bbb4-403dbdb3efe6 \ 
-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information about the specified login policy:

{
    "id": "d4308c4d-f5d5-403f-bbb4-403dbdb3efe6",
    "identityStoreDetails": {
        "type": "janrainCapture",
        "connectionDetails": {
            "domain": "dev-app.janraincapture.com",
            "applicationId": "kfcmdfudasmx9wkay7463vpdsy",
            "entityType": "user",
            "clientId": "96by2t9dav337mvzbybqdfcjmrsd7bn4",
            "clientSecret": "jiu62gun9wkkmi7fgnqx4ppe1476amh99"
        }
    },
    "loginURL": "http://localhost/login",
    "title": "Documentation Login Policy",
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/loginPolicies/d4308c4d-f5d5-403f-bbb4-403dbdb3efe6"
        }
    }
}

PUT

Description

Modifies the specified login policy.

Path Parameters

The path parameters that must be included in the request are listed in the following table:

Name	Type	Required	Description
{customer_id}	string	Yes	Unique identifier of the customer associated with the login policy.
{login_policy_id}	string	Yes	Unique identifier of the login policy to be modified.

Request Parameters

Request parameters for this endpoint must be formatted as a JSON object and included in the body parameter of your API call. For example:

{
    "id": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "identityStoreDetails": {
        "type": "janrainCapture",
        "connectionDetails": {
            "domain": "dev-app.janraincapture.com",
            "applicationId": "kfcmdfudasmx9wkay7463vpdsy",
            "entityType": "user",
            "clientId": "96by2t9dav337mvzbybqdfcjmrsd7bn4",
            "clientSecret": "jiu62gun9wkkmi7fgnqx4ppe1476amh99"
        }
    },
    "loginURL": "http://localhost/login",
    "title": "Documentation Login Policy",
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/loginPolicies/b8097975-93c7-46db-8cfe-19609e67eadb"
        }
    }

The key values used in the body parameter include the following:

Key	Description
type	Must be set to janrainCapture: `"type": "janrainCapture"` This value is required but cannot be changed.
domain (connectionDetails)	URL of your Identity Cloud Capture domain. Your Akamai representative will supply you with domain names available for your use. For example: `"domain":"dev-app.janraincapture.com"` This value is required but cannot be changed.
applicationId (connectionDetails)	Unique identifier of the Identity Cloud application associated with the login policy. For example: `"applicationId": "kfcmdfudasmx9wkay7463vpdsy"` This value is required but cannot be changed.
clientId (connectionDetails)	Unique identifier of the owner client associated with the Identity Cloud application. For example: `"clientId": "96by2t9dav337mvzbybqdfcjmrsd7bn4"` This value is required but cannot be changed.
clientSecret (connectionDetails)	Client secret of the owner client associated with the login policy. For example: `"clientSecret": " jiu62gun9wkkmi7fgnqx4ppe1476amh99"` This value is required but cannot be changed.
entityType (connectionDetails)	Name of the entity type where the user profiles associated with this client are stored. For example: `"entityType": "user"` This value is required but cannot be changed.
loginURL	URL of the web page used for Hosted Login logins and registrations. For example: `"loginURL": "http://akamai-documentation.com/login"`
title	Friendly name for the new login policy. Note that login policy names do not have to be unique. For example: `"title": "Akamai Documentation Login Policy"`
customClaims	Provides a way to return user profile attributes that are not returned by any of the allowed scopes. For example: `"customClaims": { "id_token": {"subscriber": "newsletterSubscriber"} }` See the discussion at the beginning of this article for more information.

It’s important to note that you must include all the key values in your body request, even if those values are not being changed. For example, suppose you leave out the key value title. In that case, your API call will fail with a 400 Bad Request error and the following error message:

{
  "errors": "('title',) field required"
}

The one exception to the preceding rule is the customClaims value: this value is not required, and your API call will not fail if customClaims is omitted. However, suppose your login policy currently contains a custom claim. If so, then the customClaims value will need to appear in the API call. If it does not, then the existing custom claim will be removed from the login policy (because that claim was not included in the PUT call).

Sample Request (Curl)

The following command updates the login policy with the ID b8097975-93c7-46db-8cfe-19609e67eadb:

curl -X PUT \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/loginPolicies/b8097975-93c7-46db-8cfe-19609e67eadb \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "identityStoreDetails": {
        "type": "janrainCapture",
        "connectionDetails": {
            "domain": "dev-app.janraincapture.com",
            "applicationId": "kfcmdfudasmx9wkay7463vpdsy",
            "entityType": "user",
            "clientId": "96by2t9dav337mvzbybqdfcjmrsd7bn4",
            "clientSecret": "REDACTED"
        }
    },
    "loginURL": "http://localhost/login",
    "title": "Additional Scopes Allowed Policy"
}'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back detailed information for the updated login policy:

{
    "id": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "identityStoreDetails": {
        "type": "janrainCapture",
        "connectionDetails": {
            "domain": "dev-app.janraincapture.com",
            "applicationId": "kfcmdfudasmx9wkay7463vpdsy",
            "entityType": "user",
            "clientId": "96by2t9dav337mvzbybqdfcjmrsd7bn4",
            "clientSecret": "REDACTED"
        }
    },
    "loginURL": "http://localhost/login",
    "title": "Additional Scopes Allowed Policy"
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/loginPolicies/b8097975-93c7-46db-8cfe-19609e67eadb"
        }
    }
}

Response Codes

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

Response Code	Description
400	Bad request. Typically indicates a syntax error; for example, you might have left off a parameter or misspelled a parameter name. Often-times the error description will help you pinpoint the problem; for example: `{ "errors": { "title": [ "Missing data for required field." ] } }`

DELETE

Description

Deletes the specified login policy.

Note that you cannot delete any login policy currently assigned to an OIDC client; that’s because OIDC clients (or at least the clients used for logins and registrations) must be assigned a login policy. If you want to remove a login policy that is currently assigned to an OIDC client you must first modify the OIDC client and associate it with a different login policy. Only then can the login policy be removed. This task is made easier by the fact that, if you attempt to delete a login policy assigned to one or more OIDC clients, the resulting error message will contain the IDs of each client the policy is assigned to:

{
   "errors": "[\"/customers/01000000-0000-3000-9000-000000000000/clients/af4f70a3-0364-4505-94c4-8d26df86e161\",
\"/customers/01000000-0000-3000-9000-000000000000/clients/9e7f2429-496d-4437-b516-048472613cf9\",\
"/customers/01000000-0000-3000-9000-000000000000/clients/7b65f467-83fc-462e-94e7-79708e79ee18\"]\n"
}

Path Parameters

The path parameters that must be included in the request are listed in the following table:

Name	Type	Required	Description
{customer_id}	string	Yes	Unique identifier of the customer associated with the login policy.
{login_policy_id}	string	Yes	Unique identifier of the login policy to be deleted.

Sample Request (Curl)

The following command deletes the login policy with the policy ID d4308c4d-f5d5-403f-bbb4-403dbdb3efe6:

curl -X DELETE \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/loginPolicies/d4308c4d-f5d5-403f-bbb4-403dbdb3efe6 \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

Responses

204 No Content

If your call to this endpoint succeeds, you will not get back a return value. Instead, you will get back the HTTP response code 204 No Content.

Response Codes

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

Response Code	Description
409	Conflict. Typically means that you are trying to delete a login policy that is currently assigned to one or more OIDC clients. The login policy must be unassigned from all its associated OIDC clients before it can be deleted.