Manage Push Claims

Push claims enable you to centralize and standardize the user profile information added to an identity token (or made available from the userinfo endpoint) following a successful authentication. Typically, user profile information is requested by including the scope parameter (and, optionally, the claims parameter) in an authorization request. That means it’s up to the client to request the information, and to know what information it’s even allowed to request. 

With push claims, the responsibility for retrieving user profile information is placed on the server rather than the client: clients no longer have to request information by using the scopes parameter or the claims parameter (in fact, if those parameters are included in an authorization request they are ignored). Instead of using the scopes or claims parameter, each authorization request is automatically assigned the custom claims defined in the login policy. After a user has been authenticated, the server checks the login policy and automatically pushes the custom claims to the identity token/userinfo endpoint, regardless of whether or not that information was included in the authorization request. 

Push claims are managed by using the /pushClaims endpoint, which lets you view your current push claims status and enable or disable push claims for a login policy. Note that the actual claims (that is, the custom claims found in a login policy) are managed by using the /{customerId}/config/loginPolicies/{loginPolicyId} endpoint: the /pushClaims endpoint is not used for adding custom claims to or removing custom claims from a login policy.

This endpoint supports the following methods:



GET

Description

Returns a value (true or false) indicating whether push claims have been enabled for the specified login policy. By default, push claims are disabled in login policies. 

URI Parameters

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

Parameter

Type

Required

Description

{customerId}

string

Yes

Unique identifier of the organization associated with the login policy.

{loginPolicyId}

string

Yes

Unique identifier for the login policy.


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must employ a configuration client (using the client ID as the username and the client secret as the password) to access the /{customerId}/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 will 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.


Sample Request (curl)

The following command returns the push claim status for login policy 1e1ab726-f4b5-4bad-ba45-877027af4097:

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


Responses

200 OK

If your call to this endpoint succeeds, you’ll get back a Boolean value indicating whether push claims have been enabled in the login policy:

false


Error Response Codes

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

Response Code

Description

403

Forbidden. Typically occurs when you make a call using an invalid configuration token. This is usually because the token has expired (configuration tokens have a maximum lifetime of 1 hour). However, it’s also possible that the token wasn’t issued a scope capable of accessing push claim information. See the article API Security for Configuration for more information.

404

Not found. The specified login policy could not be found. This often occurs because you referenced an invalid policy ID or customer ID when making your API call.



PUT

Back to top


Description

Enables or disables push claims in the specified login policy. To enable push claims, set the body parameter of your API call to true:

true

To disable push claims, set the body parameter to false:

false

Note that, when configuring the body parameter, you can use either plain-text or JSON formatting. (In this documentation, we use plain-text formatting.) Note, too that push claims are disabled by default in all login policies.


URI Parameters

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

Parameter

Type

Required

Description

{customerId}

string

Yes

Unique identifier of the organization associated with the login policy.

{loginPolicyId}

string

Yes

Unique identifier for the login policy.


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must employ a configuration client (using the client ID as the username and the client secret as the password) to access the /{customerId}/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 will 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.


Sample Request (curl)

The following command enables push claims for login policy 1e1ab726-f4b5-4bad-ba45-877027af4097:

curl -L -X PUT 
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/loginPolicies/1e1ab726-f4b5-4bad-ba45-877027af4097/pushClaims' \
  -H 'Authorization: Bearer dgqJbjCmon__P9OXLz5ulJtpS-jupleB-MBejblVMZHS8Nc-EeMSl91_b76WhtdA' \
  -H 'Content-Type: application/json' \
  --data-raw 'true'


Responses

If your call to this endpoint succeeds, you’ll get back a Boolean value indicating the updated push claims status for the specified login policy:

true


Error Response Codes

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

Response Code

Description

403

Forbidden. Typically occurs when you make a call using an invalid configuration token. This is usually because the token has expired (configuration tokens have a maximum lifetime of 1 hour). However, it’s also possible that the token wasn’t issued a scope capable of accessing push claim information. See the article API Security for Configuration for more information.

404

Not found. The specified login policy could not be found. This generally occurs because you referenced an invalid policy ID or customer ID when making your API call.