AM 7.3.1

Legacy OAuth 2.0 endpoints

AM exposes the following legacy endpoints:

OAuth 2.0 administration endpoints
Endpoint Description

/frrest/oauth2/token (Legacy)

Retrieve metadata about a token, revoke access and refresh tokens (AM-specific endpoint, legacy)

/oauth2/tokeninfo (Legacy)

Validate tokens and retrieve token metadata, such as scopes, to determine how to respond to requests for protected resources (AM-specific endpoint, legacy)

/frrest/oauth2/token (Legacy)

This AM-specific OAuth 2.0 token administration endpoint lets you read, list, and delete (revoke) OAuth 2.0 tokens. OAuth 2.0 clients can also manage their own tokens.

The /frrest/oauth2/token endpoint is labelled as legacy and does not support client-side OAuth 2.0 tokens.

Use the following endpoints instead:

To list the contents of a specific token, send an HTTP GET request to /frrest/oauth2/token/token-id as follows:

$ curl \
--request POST \
--data "grant_type=password" \
--data "username=demo" \
--data "password=Ch4ng31t" \
--data "scope=cn" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
{
    "scope": "cn",
    "expires_in": 60,
    "token_type": "Bearer",
    "access_token": "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
}
$ curl \
--request GET \
--header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs…​EwNDU2NjE0*" \
https://openam.example.com:8443/openam/frrest/oauth2/token/f5fb4833-ba3d-41c8-bba4-833b49c3fe2c
{
    "expireTime": [
        "1418818601396"
    ],
    "tokenName": [
        "access_token"
    ],
    "scope": [
        "cn"
    ],
    "grant_type": [
        "password"
    ],
    "clientID": [
        "myClientID"
    ],
    "parent": [],
    "id": [
        "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
    ],
    "tokenType": [
        "Bearer"
    ],
    "redirectURI": [],
    "nonce": [],
    "realm": [
        "/alpha"
    ],
    "userName": [
        "demo"
    ]
}

To list the tokens for the current user, send an HTTP GET request to /frrest/oauth2/token/?_queryId=access_token, including the SSO token of the current user in a header. The following example shows a search for the demo user’s access tokens:

$ curl \
 --request GET \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcw…​" \
 "https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryId=access_token"
{
    "result": [
    {
      "_rev": "1753454107",
      "tokenName": [
        "access_token"
      ],
      "expireTime": "Indefinitely",
      "scope": [
        "openid"
      ],
      "grant_type": [
        "password"
      ],
      "clientID": [
        "myClientID"
      ],
      "tokenType": [
        "Bearer"
      ],
      "redirectURI": [],
      "nonce": [],
      "realm": [
        "/alpha"
      ],
      "userName": [
        "bjensen"
      ],
      "display_name": "",
      "scopes": "openid"
    },
    {
      "_rev": "1753454107",
      "tokenName": [
        "access_token"
      ],
      "expireTime": "Indefinitely",
      "scope": [
        "openid"
      ],
      "grant_type": [
        "password"
      ],
      "clientID": [
        "myClientID"
      ],
      "tokenType": [
        "Bearer"
      ],
      "redirectURI": [],
      "nonce": [],
      "realm": [
        "/alpha"
      ],
      "userName": [
        "bjensen"
      ],
      "display_name": "",
      "scopes": "openid"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

To list the tokens for a specific user, send an HTTP GET request to /frrest/oauth2/token/?_queryId=userName=_username_,realm=/_realm_, where string is the user, such as bjensen, and realm is the subrealm in which the user is located. You do not have to include the realm parameter if the user is in the top-level realm.

Include the SSO token of an administrative user, such as amAdmin, in a header. For example:

$ curl \
  --request GET \
  --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs…​EwNDU2NjE0*" \
  "https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryId=userName=bjensen,realm=alpha"
{
    "result": [
    {
      "_id": "2aaddde8-586b-4cb7-b431-eb86af57aabc",
      "_rev": "-549186065",
      "tokenName": [
        "access_token"
      ],
      "expireTime": "Indefinitely",
      "scope": [
        "openid"
      ],
      "grant_type": [
        "password"
      ],
      "authGrantId": [
        "50e9f80b-d193-4aeb-93e9-e383ea2cabd3"
      ],
      "clientID": [
        "myClientID"
      ],
      "parent": [],
      "refreshToken": [
        "5e1423a2-d2cd-40d5-8f54-5b695836cd44"
      ],
      "id": [
        "2aaddde8-586b-4cb7-b431-eb86af57aabc"
      ],
      "tokenType": [
        "Bearer"
      ],
      "auditTrackingId": [
        "6ac90d13-9cac-444b-bfbc-c7aca16713de-777"
      ],
      "redirectURI": [],
      "nonce": [],
      "realm": [
        "/alpha"
      ],
      "userName": [
        "bjensen"
      ],
      "display_name": "",
      "scopes": "openid"
    },
    {
      "_id": "5e1423a2-d2cd-40d5-8f54-5b695836cd44",
      "_rev": "1171292923",
      "tokenName": [
        "refresh_token"
      ],
      "expireTime": "Oct 18, 2016 10:51 AM",
      "scope": [
        "openid"
      ],
      "grant_type": [
        "password"
      ],
      "authGrantId": [
        "50e9f80b-d193-4aeb-93e9-e383ea2cabd3"
      ],
      "clientID": [
        "myClientID"
      ],
      "authModules": [],
      "id": [
        "5e1423a2-d2cd-40d5-8f54-5b695836cd44"
      ],
      "tokenType": [
        "Bearer"
      ],
      "auditTrackingId": [
        "6ac90d13-9cac-444b-bfbc-c7aca16713de-776"
      ],
      "redirectURI": [],
      "realm": [
        "/alpha"
      ],
      "userName": [
        "bjensen"
      ],
      "acr": [],
      "display_name": "",
      "scopes": "openid"
    },
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

To delete (revoke) a token, perform an HTTP DELETE on /frrest/oauth2/token/token-id, including the SSO token of an administrative user, such as amAdmin, as in the following example:

$ curl \
--request POST \
--data "grant_type=password" \
--data "username=demo" \
--data "password=Ch4ng31t" \
--data "scope=cn" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
{
    "scope": "cn",
    "expires_in": 60,
    "token_type": "Bearer",
    "access_token": "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
}
$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs…​EwNDU2NjE0*" \
 "https://openam.example.com:8443/openam/frrest/oauth2/token/f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
{
    "success": "true"
}

/oauth2/tokeninfo (Legacy)

AM-specific endpoint used to validate tokens and to retrieve information out of them, such as scopes, the grant type used when issuing the token, or the token expiration time.

The /oauth2/tokeninfo endpoint is labelled as legacy.

To validate tokens and retrieve information with a spec-based endpoint, see /oauth2/introspect.

Resource servers—or any party having the token ID—can obtain token information through this endpoint without authenticating.

The token information endpoint supports the following query parameter:

access_token

Specifies the token ID.

Required: Yes.

The following example shows AM issuing an access token, and then returning token information:

$ curl \
--request POST \
--data "grant_type=password" \
--data "username=demo" \
--data "password=Ch4ng31t" \
--data "scope=write" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
{
  "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
  "scope": "write",
  "token_type": "Bearer",
  "expires_in": 3599
}
$ curl \
--request GET \
--header "Authorization: Bearer sbQZuveFumUDV5R1vVBl6QAGNB8" \
"https://openam.example.com:8443/openam/oauth2/tokeninfo"
{
   "access_token":"sbQZuveFumUDV5R1vVBl6QAGNB8",
   "grant_type":"password",
   "auth_level":0,
   "scope":[
      "write"
   ],
   "realm":"/alpha",
   "token_type":"Bearer",
   "expires_in":2491,
   "write":"",
   "client_id":"myClient"
}

Note that AM returns a JSON object with the following properties:

access_token

Specifies the token ID.

grant_type

Specifies the OAuth 2.0 grant flow used to issue the token.

auth_level

Specifies the authentication level of the resource owner that authenticated to authorize the token.

scope

Specifies a JSON structure containing the scopes associated with the token.

realm

Specifies the realm from which the token was obtained.

token_type

Specifies the type of token.

expires_in

Specifies the time, in seconds, that the token is valid for. This value is set at token creation time, and it depends on the configuration of the OAuth2 Provider Service.

During the introspection call, AM calculates the amount of seconds the token is still valid for and returns it in the expires_in object. Therefore, repeated calls to the endpoints return different values for the object.

However, the actual value of the expires_in object in the token does not change. Inspecting the token without using AM will show the value set at token creation time.

AM does not return this object for client-side tokens issued to a client configured in a different realm that the resource owner’s.

client_id

Specifies the client that requested the token.

Copyright © 2010-2024 ForgeRock, all rights reserved.