Managing tokens with the DataPower Gateway

API Connect can use the DataPower® distributed cache to manage the token lifecycle that includes when to revoke access rights.

Before you begin

To use the DataPower Gateway to manage tokens, the DataPower quota enforcement server must be enabled on the DataPower Gateway to use the distributed cache, see. Quota enforcement.

Note: This option is not supported for API Connect with IBM® Cloud public.

About this task

When distributed cache support is enabled, replay protection is provided across the gateway cluster through the quota enforcement server. This support ensures that the same token cannot be reused across the members of the quota enforcement peer group.

The Allow user to view and revoke permissions and Allow application to revoke its token settings are set independently.

Procedure

Enable support for the DataPower distributed cache.

  1. Click OAuth 2 > Tokens section.
  2. Switch on the Enable revocation slider.
  3. Select Use DataPower Gateway.

Optionally allow user to view and revoke permissions.

  1. Select Allow users to View and revoke permissions.
    This option inserts 2 REST API calls to /oauth2/issued.
    • An HTTP GET operation that retrieves a list of all granted permissions for a specific user.
    • An HTTP DELETE operation that revokes an application for a specific user.
    The setting inserts header-based security definitions of client ID and client secret as shown in example. The API call to revoke a given application for a given user is shown in the second example.
    Note: View and revoke permissions should be limited to administrative applications because it allows applications subscribed to this OAuth provider API the ability to view and revoke permissions for other applications.

    View permissions example

    To list out all the applications granted by user cn=spoon,o=ibmwith username spoon and password spoon using a registered administration application of 5287fe53-8747-438a-8262-681ec75b79c5.
    • Request:
      GET /oauth2/issued
HTTP/1.1
       Host: apic.ibm.com
       x-ibm-client-id: 5287fe53-8747-438a-8262-681ec75b79c5
       x-ibm-client-secret: E2qM6mG2bX2uC1xT2iN1uU6bT5cV4dN7nW5kM5uP8vL3uF3cT7
       Authorization: Basic c3Bvb246c3Bvb24=
    • Response:
      HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
[
    {
        "clientId": "7369ad66-5674-b7d3-4567-de35283421aca",
        "owner": "cn=spoon,o=ibm",
        "clientName": "PetStore Application",
        "scope": "listpet",
        "issuedAt": 1503327054,
        "consentedOn": 1503327054,
        "expiredAt": 1503330654,
        "refreshTokenIssued": false,
        "appId": "d2031f0f27339315333734ab9",
        "org": "PetStoreOrg",
        "orgTitle": "Katie Pet Grooming Inc",
        "orgId": "5887803de4b06e6998c4b2c7",
        "provider": "SuperStore",
        "providerTitle": "Simon SuperStore",
        "providerId": "5887803de4b06e6998c4b2c7",
        "catalog": "publicapi",
        "catalogTitle": "For public",
        "catalogId": "5887803de4b06e6998c4b2d3"
    },
    {
        "clientId": "a8746323-9825-a842-8736-abd8202356ac8",
        "owner": "cn=spoon,o=ibm",
        ...
    }
]

    Revoke permissions example

    To revoke application a8746323-9825-a842-8736-abd8202356ac8 by owner cn=spoon,o=ibm.
    • Request
      DELETE /oauth2/issued?client-id=a8746323-9825-a842-8736-abd8202356ac8
HTTP/1.1
       Host: apic.ibm.com
       x-ibm-client-id: 5287fe53-8747-438a-8262-681ec75b79c5
       x-ibm-client-secret: E2qM6mG2bX2uC1xT2iN1uU6bT5cV4dN7nW5kM5uP8vL3uF3cT7
       Authorization: Basic c3Bvb246c3Bvb24=
    • Response
      HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: private, no-store, no-cache, must-revalidate
Pragma: no-cache

     { "status": "success" }

Optionally allow applications to self manage token lifecycle by revoking their own token.

  1. Select Allow application to revoke its token.
    This option inserts 1 REST API call to /oauth2/revoke, which supports OAuth 2.0 IETF RFC 7009.
    • An HTTP POST operation that an application can send to this API to revoke either an access_token, or refresh_token with token_type_hint as shown in the examples.
    Revoke access_token example
    • Request:
      POST /oauth2/revoke 
HTTP/1.1

    Host: apic.ibm.com

       x-ibm-client-id: 5287fe53-8747-438a-8262-681ec75b79c5
       x-ibm-client-secret: E2qM6mG2bX2uC1xT2iN1uU6bT5cV4dN7nW5kM5uP8vL3uF3cT7
      Content-Type: application/x-www-form-urlencoded

      token_type_hint=access_token&token=AAIHZGVmYXVsdD1-KqwD0Yc3EDn94lSWX14xuR....
    • Response:
      HTTP/1.1 200 OK
      Content-Type: application/json;charset=UTF-8
      Cache-Control: private, no-store, no-cache, must-revalidate
      Pragma: no-cache

     { "status": "success" }
    Revoke a refresh_token example
    • Request:
      POST /oauth2/revoke 
HTTP/1.1

    Host: apic.ibm.com

       x-ibm-client-id: 5287fe53-8747-438a-8262-681ec75b79c5
       x-ibm-client-secret: E2qM6mG2bX2uC1xT2iN1uU6bT5cV4dN7nW5kM5uP8vL3uF3cT7
      Content-Type: application/x-www-form-urlencoded

      token_type_hint=refresh_token&token=........
    • Response:
      HTTP/1.1 200 OK
      Content-Type: application/json;charset=UTF-8
      Cache-Control: private, no-store, no-cache, must-revalidate
      Pragma: no-cache

     { "status": "success" }