Skip to main content

Using Application Metadata in Token Claims

This article provides an instruction on how to add application metadata to ID or access tokens in SecureAuth to provide application's data used to perform authorization decisioning and enforcement.

About Using Client Metadata

With SecureAuth, you can inject additional metadata attributes as part of the client application object.

Metadata can be used as

Prerequisites

  • Administrator's privileges in SecureAuth

  • At least one application with its metadata defined in SecureAuth

    Note

    • For the purpose of this instruction, the Demo Portal application is used (built-in by default in the SecureAuth administrator portal).

    • For the instruction on how to add metadata for an application, see Configure app metadata.

Create Custom Token Claims

You can create a new claim for your tokens using client metadata in either one of these ways:

Use the Admin Portal

To enhance your tokens with claims using application metadata, you can either see the short video guide or follow Step-by-step Instruction.

Video Guide

Step-by-step Instruction

  1. Navigate to https://authz.cloudentity.io/ and sign in to your account.

  2. Go to OAuth > Tokens & Claims > Claims.

  3. Select the type of the token that you want to enhance (ID Tokens or Access Tokens) and Add claim.

  4. In the Add claim pop-out window

    • Enter a name of the claim.

    • Select Client from the Source type drop-down menu.

    • From the Source path drop-down menu, select Metadata to specify the path to the data object that you want to inject.

  5. Select Create from the bottom of the Add claim pop-out window.

    Note

    See Verify New Token Claim to check how to test your new setup.

    Result: You have added a new custom claim for your tokens.

Use Admin API

To create your custom token claim, use the Create claim admin API to make a CURL call with option --data-raw posting required data to the server.

Note

Make sure that tenant_id, authorization_server_id, and SecureAuth URL are correct. This API requires the tenant-admin-level access token.

Example CURL Call

curl --location --request POST 'https://your-acp.cloudentity.io/api/admin/skynet/claims' \
--header 'Authorization: Bearer <Admin Access Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"tenant_id": "your-acp-tenant",
"authorization_server_id": "your-acp-workspace",
"name": "application_labels",
"mapping": "metadata",
"source_type": "client",
"source_path": "metadata.application_labels",
"type": "access_token",
"scopes": []
}'

Verify New Token Claim

If you use the SecureAuth administrator portal to add your new custom token claim, you can check if the claim is actually added to your token using the demo application built in the SecureAuth administrator portal and available by default.

Step-by-step Guide

  1. Navigate to https://authz.cloudentity.io/ and sign in to your account.

  2. Open the Demo application.

  3. Log in to the demo application.

    You have logged in to Demo application and you can check the tokens issued by SecureAuth. In particular, you can verify Access token > PAYLOAD for your newly-added claim.

In this section: