Managing Custom Claims

You can use the Oracle Identity Cloud Service REST API to add custom claims to an access token, an identity token, or both the tokens. Custom claims are rules that you can add to a token for the Oracle Identity Cloud Service tenant.

Note:

The custom claims feature is available with Oracle Identity Cloud Service Standard subscription and is disabled by default. You must contact Oracle Support Services to enable the feature for your Oracle Identity Cloud Service instance.
The cURL command examples use the URL structure:
https://tenant-base-url/admin/v1/CustomClaims/{id}

The following use case shows you how to:

  • Create a custom claim

  • Modify the custom claim

  • View the custom claim

  • Delete the custom claim

To manage the custom claim:

  1. Specify the headers on the cURL command line:
    -H Authorization: Bearer <Access Token>
    -H Cache-Control: no-cache
    -H Accept:application/json

    To obtain an access token, see Working with OAuth 2 to Access the REST API.

  2. Create the custom claim name MyATCustomClaim and value MyATValue for the access token by running the following command:
    curl -i -X POST https://tenant-base-url/admin/v1/CustomClaims

    Example

    curl -i -X POST https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims

    The following is an example of a JSON request body to create the custom claim:

    {
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
      ],
      "name": "MyATCustomClaim",
      "value": "MyATValue",
      "expression": false,
      "mode": "always",
      "tokenType": "AT",
      "allScopes": true
    }
    Attribute Description

    name

    The custom claim name.

    value

    The custom claim value.

    expression

    Specify if the custom claim value is a user expression. You can determine the user expression by using the Users endpoints.

    Value: true or false

    Example User Expression

    • $user.name.formatted expression with value admin opc.
    • $user.emails.0.type expression with value recovery.
    • $user.emails.1.type expression with value work.
    • $user.urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User.myCustomAttribute expression with value customValue.
    Based on user expressions, a claim returns either a single value attribute or all the attributes associated with the expression. For example, the following expressions return a single value within an array:
    • $user.emails.0.value
    • $(user.emails[0].value)
    While the following expressions return an array:
    • $user.emails.*.value
    • $(user.emails[*].value)

    allScopes

    Specify if you want to associate the custom claim with a set of scopes or all the scopes.

    Value: true or false

    mode

    Specify how you want to attach the custom claim to a token.
    • always: The custom claim will be attached to the token.
    • request: The custom claim will be attached to the token only if it is requested or overridden.
    • never: The custom claim will not be attached to the token.

    tokenType

    Specify the token type.
    • AT: To add custom claim for an access token.
    • IT: To add custom claim for an identity token.
    • BOTH: To add custom claim for the access and identity token.

    scopes

    Optional. The Custom Claim will be embedded to tokens if any scope in the scopes array is requested in the token request. You can either specify allScopes equals to true with no associated scopes array or has allScopes equals to false with associated scopes array.

    The following shows an example of the response body:

    {
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
      ],
      "name": "MyATCustomClaim",
      "value": "MyATValue",
      "expression": false,
      "mode": "always",
      "tokenType": "AT",
      "allScopes": true,
      "id": "ddc7f88bea2a46258c593bddccaf2b86",
      "meta": {
        "created": "2019-05-17T04:33:43.640Z",
        "lastModified": "2019-05-17T04:33:43.640Z",
        "resourceType": "CustomClaim",
        "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/ddc7f88bea2a46258c593bddccaf2b86"
      },
      "idcsCreatedBy": {
        "value": "bac027a9500c4db9a09f5cfbcbda5076",
        "type": "App",
        "display": "exampleDomainAdmin",
        "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
      },
      "idcsLastModifiedBy": {
        "value": "bac027a9500c4db9a09f5cfbcbda5076",
        "type": "App",
        "display": "exampleDomainAdmin",
        "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
      }
    }
  3. Replace all the attributes for the custom claim id ddc7f88bea2a46258c593bddccaf2b86 by running the following command:
    curl -i -X PUT https://tenant-base-url/admin/v1/CustomClaims/{id}

    Example

    curl -i -X PUT https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/246e8af829954faf8070602d51c45426

    The following shows an example of the request body.

    {
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
      ],
      "name": "MyATClaim1",
      "value": "MyATValue1",
      "expression": false,
      "mode": "request",
      "tokenType": "AT",
      "allScopes": true
    }

    The following shows an example of the response indicating the request succeeded.

    {
      "idcsLastModifiedBy": {
        "type": "App",
        "value": "bac027a9500c4db9a09f5cfbcbda5076",
        "display": "exampleDomainAdmin",
        "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
      },
      "idcsCreatedBy": {
        "type": "App",
        "display": "exampleDomainAdmin",
        "value": "bac027a9500c4db9a09f5cfbcbda5076",
        "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
      },
      "mode": "request",
      "id": "ddc7f88bea2a46258c593bddccaf2b86",
      "value": "MyATValue1",
      "expression": false,
      "meta": {
        "created": "2019-05-17T04:33:43.640Z",
        "lastModified": "2019-05-17T04:41:13.177Z",
        "resourceType": "CustomClaim",
        "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/ddc7f88bea2a46258c593bddccaf2b86"
      },
      "allScopes": true,
      "name": "MyATCustomClaim1",
      "tokenType": "AT",
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
      ]
    }
  4. Set the allScopes to false for the id ddc7f88bea2a46258c593bddccaf2b86 by running the following command:
    curl -i -X PATCH https://tenant-base-url/admin/v1/CustomClaims/{id}

    Example

    curl -i -X PATCH https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/246e8af829954faf8070602d51c45426

    The following shows an example of the request body.

    {
      "Operations": [
        {
          "op": "replace",
          "path": "allScopes",
          "value": false
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
      ]
    }

    The following shows an example of the response indicating the request succeeded.

    {
      "idcsLastModifiedBy": {
        "type": "User",
        "value": "210d294a075a4c86bbf6f958bceacf0c",
        "display": "admin opc",
        "$ref": "https://mytenant.identity.internal.oracle.com/admin/v1/Users/ddc7f88bea2a46258c593bddccaf2b86"
      },
      "idcsCreatedBy": {
        "type": "User",
        "display": "admin opc",
        "value": "ddc7f88bea2a46258c593bddccaf2b86",
        "$ref": "https://mytenant.identity.internal.oracle.com/admin/v1/Users/210d294a075a4c86bbf6f958bceacf0c"
      },
      "mode": "always",
      "id": "98e94996776845719cf3b737e565199a",
      "value": "MyATValue",
      "expression": false,
      "meta": {
        "created": "2019-05-31T05:43:32.518Z",
        "lastModified": "2019-05-31T05:58:10.362Z",
        "resourceType": "CustomClaim",
        "location": "https://mytenant.identity.internal.oracle.com/admin/v1/CustomClaims/98e94996776845719cf3b737e565199a"
      },
      "allScopes": false,
      "name": "MyATCustomClaim",
      "tokenType": "AT",
      "scopes": [
        "phone"
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
      ]
    }
  5. View all the custom claims in the tenant by running the following command:
    curl -i -X GET https://tenant-base-url/admin/v1/CustomClaims

    Example

    curl -i -X GET https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims
    The following shows an example of the response body.
    {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ],
      "totalResults": 5,
      "Resources": [
        {
          "idcsLastModifiedBy": {
            "type": "App",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "display": "exampleDomainAdmin",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "idcsCreatedBy": {
            "type": "App",
            "display": "exampleDomainAdmin",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "mode": "always",
          "id": "edf077cbae59435dab3f9de5ba1fd619",
          "value": "AlwaysAllScopesATValue",
          "expression": false,
          "meta": {
            "created": "2019-05-17T04:16:15.121Z",
            "lastModified": "2019-05-17T04:16:15.121Z",
            "resourceType": "CustomClaim",
            "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/edf077cbae59435dab3f9de5ba1fd619"
          },
          "allScopes": true,
          "name": "AlwaysAllScopesATClaim10",
          "tokenType": "AT",
          "schemas": [
            "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
          ]
        },
        {
          "idcsLastModifiedBy": {
            "type": "App",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "display": "exampleDomainAdmin",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "idcsCreatedBy": {
            "type": "App",
            "display": "exampleDomainAdmin",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "mode": "request",
          "id": "ddc7f88bea2a46258c593bddccaf2b86",
          "value": "MyATValue1",
          "expression": false,
          "meta": {
            "created": "2019-05-17T04:33:43.640Z",
            "lastModified": "2019-05-17T04:41:13.177Z",
            "resourceType": "CustomClaim",
            "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/ddc7f88bea2a46258c593bddccaf2b86"
          },
          "allScopes": true,
          "name": "MyATCustomClaim1",
          "tokenType": "AT",
          "schemas": [
            "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
          ]
        },
        {
          "idcsLastModifiedBy": {
            "type": "App",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "display": "exampleDomainAdmin",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "idcsCreatedBy": {
            "type": "App",
            "display": "exampleDomainAdmin",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "mode": "always",
          "id": "150d1eae9f0f4301a22312bd680aa4df",
          "value": "MyATValue",
          "expression": false,
          "meta": {
            "created": "2019-05-17T04:43:43.091Z",
            "lastModified": "2019-05-17T04:43:43.091Z",
            "resourceType": "CustomClaim",
            "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/150d1eae9f0f4301a22312bd680aa4df"
          },
          "allScopes": true,
          "name": "MyATCustomClaim",
          "tokenType": "AT",
          "schemas": [
            "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
          ]
        },
        {
          "idcsLastModifiedBy": {
            "type": "App",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "display": "exampleDomainAdmin",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "idcsCreatedBy": {
            "type": "App",
            "display": "exampleDomainAdmin",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "mode": "never",
          "id": "2680b220be904698b43575e3d654a88c",
          "value": "MyATValue2",
          "expression": false,
          "meta": {
            "created": "2019-05-17T04:44:40.777Z",
            "lastModified": "2019-05-17T04:44:40.777Z",
            "resourceType": "CustomClaim",
            "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/2680b220be904698b43575e3d654a88c"
          },
          "allScopes": true,
          "name": "MyATCustomClaim2",
          "tokenType": "AT",
          "schemas": [
            "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
          ]
        },
        {
          "idcsLastModifiedBy": {
            "type": "App",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "display": "exampleDomainAdmin",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "idcsCreatedBy": {
            "type": "App",
            "display": "exampleDomainAdmin",
            "value": "bac027a9500c4db9a09f5cfbcbda5076",
            "$ref": "https://mytenant.identity.oraclecloud.com/admin/v1/Apps/bac027a9500c4db9a09f5cfbcbda5076"
          },
          "mode": "never",
          "id": "2c92cb2c39ce40bfba09e002f6a1358e",
          "value": "MyATValue3",
          "expression": false,
          "meta": {
            "created": "2019-05-17T04:45:42.926Z",
            "lastModified": "2019-05-17T04:45:42.926Z",
            "resourceType": "CustomClaim",
            "location": "https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/2c92cb2c39ce40bfba09e002f6a1358e"
          },
          "allScopes": false,
          "name": "MyATCustomClaim3",
          "tokenType": "BOTH",
          "schemas": [
            "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
          ]
        }
      ],
      "startIndex": 1,
      "itemsPerPage": 50
    }
  6. View the custom claims in a tenant by providing the query parameter.
    curl -i -X GET https://tenant-base-url/admin/v1/CustomClaims?attributes=(schema attributes)

    Example

    curl -i -X GET https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims?attributes=request

    The following shows an example of the response body after providing the query parameter ?attributes=request:

    {
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        ],
        "totalResults": 4,
        "Resources": [
            {
                "name": "AlwaysAllScopesATClaim10",
                "id": "edf077cbae59435dab3f9de5ba1fd619",
                "value": "AlwaysAllScopesATValue"
            },
            {
                "name": "MyATCustomClaim1",
                "id": "ddc7f88bea2a46258c593bddccaf2b86",
                "value": "MyATValue1"
            },
            {
                "name": "MyATCustomClaim",
                "id": "150d1eae9f0f4301a22312bd680aa4df",
                "value": "MyATValue"
            },
            {
                "name": "MyATCustomClaim2",
                "id": "2680b220be904698b43575e3d654a88c",
                "value": "MyATValue2"
            }
        ],
        "startIndex": 1,
        "itemsPerPage": 50
    }
  7. Optionally, delete the custom claim from the tenant by running the following command:
    curl -i -X DELETE https://tenant-base-url/admin/v1/CustomClaims/{id}

    Example

    curl -i -X DELETE https://mytenant.identity.oraclecloud.com/admin/v1/CustomClaims/246e8af829954faf8070602d51c45426