Query, validate, and cancel tokens

Both REST and SOAP STS instances support 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 both REST and SOAP STS instances' configuration 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 OpenID Connect 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 for both REST and SOAP STS instances using REST API calls.

When using the sts-tokengen endpoint, be sure to 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 OpenID Connect tokens for the demo user for the username-transformer STS instance:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen?_queryFilter=\/sts_id+eq+\'username-transformer\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "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 the demo user. The results show that AM has issued two OpenID Connect tokens:

$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen?_queryFilter=\/token_principal+eq+\'demo\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "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://openam.example.com:8443/openam/sts-tokengen/B663D248CE4C3B63A7422000B03B8F5E0F8E443B
{
    "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "_rev":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "result":"token with id B663D248CE4C3B63A7422000B03B8F5E0F8E443B successfully removed."
}

Validate and cancel tokens by invoking a REST STS instance

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

To validate a token, use the validate action. The following example validates an OpenID Connect token previously issued by the username-transformer REST 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://openam.example.com:8443/openam/rest-sts/username-transformer?_action=validate
{
    "token_valid":true
}

To cancel a token, use the cancel action. The following example cancels an OpenID Connect token previously issued by the username-transformer REST 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://openam.example.com:8443/openam/rest-sts/username-transformer?_action=cancel
{
    "result":"OPENIDCONNECT token cancelled successfully."
}

Validate and cancel tokens by invoking a SOAP STS instance

The source code for the validateToken and cancelToken methods in the org.forgerock.openam.sts.soap.SoapSTSConsumer class provides information needed to construct WS-Trust 1.4-compliant calls for validating and cancelling tokens.

Locate the org.forgerock.openam.sts.soap.SoapSTSConsumer class under openam-sts/openam-soap-sts/openam-soap-sts-client in the AM source code.

PingAM 7.5.0