PingAM 8.0.0

Query, validate, and cancel tokens

The Security Token Service (STS) instance supports token persistence, which is the ability to store tokens issued for the STS instance in the Core Token Service (CTS). You enable token persistence for STS instances under Realms > Realm Name > STS > STS Instance Name > General Configuration > Persist Issued Tokens in Core Token Store. Tokens are saved in the CTS for the duration of the token lifetime, which is a configuration property for STS-issued SAML v2.0 and OIDC tokens. Tokens with expired durations are periodically removed from the CTS.

With token persistence enabled for an STS instance, AM provides the ability to query, validate, and cancel tokens issued for the instance:

  • Querying tokens means listing tokens issued for an STS instance or for a user.

  • Validating a token means verifying that the token is still present in the CTS.

  • Cancelling a token means removing the token from the CTS.

Invoke the sts-tokengen endpoint

The sts-tokengen endpoint provides administrators with the ability to query and cancel tokens issued using REST API calls.

When using the sts-tokengen endpoint, make sure you provide the token ID for an AM administrator, such as amAdmin, as the value of a header whose name is the name of the SSO token cookie, by default iPlanetDirectoryPro.

Query tokens

List tokens issued for an STS instance by using the queryFilter action in an HTTP GET call to the sts-tokengen endpoint with the /sts-id argument.

The following example lists all the tokens issued for the username-transformer STS instance. The results show that AM has issued two OIDC tokens for bjensen for the username-transformer STS instance:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://am.example.com:8443/am/sts-tokengen?_queryFilter=\/sts_id+eq+\'username-transformer\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376098
        }
    ],
    "resultCount":2,
    "pagedResultsCookie":null,
    "totalPagedResultsPolicy":"NONE",
    "totalPagedResults":-1,
    "remainingPagedResults":-1
}

List tokens issued for a particular user with the queryFilter action in an HTTP GET call to the sts-tokengen endpoint with the /token-principal argument.

The following example lists all the tokens issued for bjensen. The results show that AM has issued two OIDC tokens:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://am.example.com:8443/am/sts-tokengen?_queryFilter=\/token_principal+eq+\'bjensen\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376098
        }
    ],
    "resultCount":2,
    "pagedResultsCookie":null,
    "totalPagedResultsPolicy":"NONE",
    "totalPagedResults":-1,
    "remainingPagedResults":-1
}

Cancel tokens

Cancel tokens by making an HTTP DELETE call to the sts-tokengen/token-id endpoint:

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://am.example.com:8443/am/sts-tokengen/B663D248CE4C3B63A7422000B03B8F5E0F8E443B
{
    "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "_rev":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "result":"token with id B663D248CE4C3B63A7422000B03B8F5E0F8E443B successfully removed."
}

Validate and cancel tokens by invoking an STS instance

STS users can validate and cancel tokens by making an HTTP POST call to an STS instance’s endpoint.

To validate a token, use the validate action. The following example validates an OIDC token previously issued by the username-transformer STS instance:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Content-Type: application/json" \
--data '{
    "validated_token_state": {
        "token_type": "OPENIDCONNECT",
        "oidc_id_token": "eyAidHlwIjogIkpXVCIsIC…​"
    }
}' \
https://am.example.com:8443/am/rest-sts/username-transformer?_action=validate
{
    "token_valid":true
}

To cancel a token, use the cancel action. The following example cancels an OIDC token previously issued by the username-transformer STS instance:

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Content-Type: application/json" \
--data '{
    "cancelled_token_state": {
        "token_type": "OPENIDCONNECT",
        "oidc_id_token": "eyAidHlwIjogIkpXVCIsIC…​"
    }
}' \
 https://am.example.com:8443/am/rest-sts/username-transformer?_action=cancel
{
    "result":"OPENIDCONNECT token cancelled successfully."
}