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 both 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)

The AM-specific OAuth 2.0 token administration endpoint /frrest/oauth2/token lets administrators read, list, and delete (revoke) OAuth 2.0 tokens. OAuth 2.0 clients can also manage their own tokens.

Important

The /frrest/oauth2/token endpoint is labeled as legacy and it does not work with client-based OAuth 2.0 tokens.

Use the following endpoints instead:

/oauth2/introspect. Use this endpoint to retrieve metadata from OAuth 2.0 tokens.
/oauth2/token/revoke. Use this endpoint to delete (revoke) specific OAuth 2.0 tokens.
/users/user/oauth2/applications. Use this endpoint to list clients holding tokens granted by specific resource owners, and for deleting tokens for a combination of a resource owner and client.

To list the contents of a specific token, perform an HTTP GET on /frrest/oauth2/token/token-id 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/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": [
        "/"
    ],
    "userName": [
        "demo"
    ]
}

To list the tokens for the current user, perform an HTTP GET on /frrest/oauth2/token/?_queryId=access_token, including in 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": [
        "/test"
      ],
      "userName": [
        "user.4"
      ],
      "display_name": "",
      "scopes": "openid"
    },
    {
      "_rev": "1753454107",
      "tokenName": [
        "access_token"
      ],
      "expireTime": "Indefinitely",
      "scope": [
        "openid"
      ],
      "grant_type": [
        "password"
      ],
      "clientID": [
        "myClientID"
      ],
      "tokenType": [
        "Bearer"
      ],
      "redirectURI": [],
      "nonce": [],
      "realm": [
        "/test"
      ],
      "userName": [
        "user.4"
      ],
      "display_name": "",
      "scopes": "openid"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

To list a specific user's tokens, perform an HTTP GET on /frrest/oauth2/token/?_queryId=userName=string, where string is the user, such as user.4. 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=user.4"
{
    "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": [
        "/test"
      ],
      "userName": [
        "user.4"
      ],
      "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": [
        "/test"
      ],
      "userName": [
        "user.4"
      ],
      "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/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.

Tip

The /frrest/oauth2/tokeninfo endpoint is labeled 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/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":"/",
   "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 expiration time in seconds.
client_id: Specifies the client that requested the token.