Entitlements in Introspection

It is very common to need some form of permissions or entitlements when determining if a user should be able to call an API. This can be done using OAuth scopes, but often additional rights need to be verified. These permissions are often needed in the API gateway, so that it can check the user's right before forwarding the call to the back-end. This is also a convenient location when the API gateway is introspecting the token to convert it from a phantom token to a JWT (i.e., from an opaque GUID used on the Internet to a corresponding JSON Web Token used internally).

To save the rights of a user, the SCIM 2 user account model can be used. This schema defines a standard way of representing these user-specific entitlements. In that specification, it stipulates that a user may have a (possibly empty) set of rights that look like this (when encoded as JSON):

{
    "entitlements": [
        {"value": "a"},
        {"value": "b"},
        {"value": "c"}
    ],
    // ...
}

The Curity Identity Server supports the SCIM 2 standard and makes the user data available when the token is introspected. As of version 7.0 of the Curity Identity Server, a GraphQL API is also available for User Management. The following walk-through will explain how these features can be combined to solve this need. To follow along, make sure that the following is already setup:

• A Token Service with a client that can get an access token (e.g., via the code flow or assisted token flow) and another that can introspect it. The first will be the one used by a Web or mobile app and the second will be the one used by the API gateway.
• An authentication profile that allows the user to login via an HTML Form Authenticator
• Other basic facilities like a Data Source (DS) and cryptographic keys

Setting Entitlements for a User

The SCIM 2 API can be used to set entitlements of users through a standard mechanism. This API supports GET, POST, PUT, and PATCH on users and groups of users. This provides a known protocol that a customer support portal, for instance, can leverage to update all user attributes, not just entitlements.

In addition to the SCIM 2 API, the Curity Identity Server can be configured to expose a GraphQL API for User Management (version 7.0 and later). This could be used as an alternative mechanism to manage users and with that set entitlements.

Configuring a New User Management Profile

If a user management profile has been created, then this API is available. If not, however, it can be setup by performing the following steps in the Admin UI:

1. From the Profiles menu, click Add Profile to add a User Management profile.

2. Give it some name, e.g., user-management, and a URL Prefix, e.g., /um. Then click Next.

3. Select the Token Service that will be used. This defines the Token Service that a client, like the customer support portal, must obtain a token from in order to call the SCIM or GraphQL API.

   a) Optionally select an existing Authorization Manager or create a new one.

4. On the Data Sources page, first choose the type of User Data Store, data-sources or an account-manager. If the GraphQL API is to be used and linked accounts are used, choose the account-manager option here. Otherwise choose data-sources.

   a) If data-sources is chosen, select the Token Data Source where tokens are stored. Also select the User Account Data Source. In a simple deployment, these two data sources will be the same. Optionally select a Devices Data Source and a Credential Manager.

   b) If account-manager is chosen, select the Token Data Source where tokens are stored. Also select the Account Manager. Optionally select a Credential Manager.

5. Next select what nodes that the User Management profile should be deployed to. In a simple deployment this is probably the default node. Then click next and Commit the changes.

Testing the New API

If the configuration was accepted and committed, it should be ready to use. The endpoint(s) will be available on the node(s) that the configuration was deployed to. Each of those have a protocol (e.g., https), a listening address or interface (e.g., 0.0.0.0 for all interfaces on that server host), and a port (e.g., 8443). These together forms the Base URL:

https://localhost:8443

To call either the SCIM or GraphQL endpoints, a token is needed that authorizes the caller. This can be obtained in various ways. When the caller is a customer support portal, for instance, this token will usually be obtained using the client credentials flow. The client ID and secret that the portal uses will be some configured values that it keeps safe. With this, it can make a request such as this to obtain an access token:

POST /oauth/v2/oauth-token HTTP/1.1
Host: localhost:8443
Authorization: Basic Y2xpZW50LW9uZTowbmUhU2VjcmV0
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&
response_type=token

In this request, the client ID and secret may also be provided in body using the form elements client_id and client_secret. The result will be a JSON document that includes an access token:

{
    "access_token": "_0XBPWQQ_c25227b2-5e00-4324-934d-ba5ddccd54aa",
    "scope": "",
    "token_type": "bearer",
    "expires_in": 300
}

https://localhost:8443/um/Users

GET /um/Users HTTP/1.1
Host: localhost:8443
Authorization: Bearer _0XBPWQQ_c25227b2-5e00-4324-934d-ba5ddccd54aa
Accept: application/scim+json

{
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 50,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
    {
        "id": "VVNFUjoyOWZmODMzYWQ2NGM0MzY1YmY3Y2QzYjQ1YjM1NWI0Mw",
        "userName": "teddie",
        "active": true,
        // ...
    }]
}

Adding Entitlements to an Existing User

PATCH /um/Users/VVNFUjoyOWZmODMzYWQ2NGM0MzY1YmY3Y2QzYjQ1YjM1NWI0Mw HTTP/1.1
Host: localhost:8443
Authorization: Bearer 75398416-3958-4828-a738-6c27465204eb
Accept: */*
Content-Type: application/scim+json
 
{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations":[{
        "op":"add",
        "path":"entitlements",
        "value":[
            {"value": "a"},
            {"value": "b"},
            {"value": "c"}
        ]
    }]
}

Including Entitlements in Introspection Results

To include these new entitlements in the introspection results, we have to configure the Curity Identity Server to retrieve the attributes. This can be achieved in several different ways and will be done as an Authentication Action configured on the HTML Form Authenticator. The Attribute Query used by the Data Source will be modified, and a token issuance procedure configured that returns the user's rights when the token is introspected.

Custom Attribute Query

To include the entitlements attributes in the ones that are available for a user when that user's token is introspected, a custom attribute query is configured. This should be done on the Data Source that will be used by the Authentication Action assigned to the authenticator used. A custom credential query could be used instead; however, this will not be described in this walk-through. To configure the custom Attribute Query on the Data Source, do the following:

1. In the Facilities → Data Sources menu, find the Data Source that is used (should be the same as used by the User Management Service) and click Edit.
2. In the Attribute Query field, enter the following query:

SELECT * FROM accounts WHERE accounts.username = :subject

Here, :subject will be replaced with the username of the user that logged in (e.g., teddie).

Data Source Authentication Action

With the Attribute Query modified, a Data Source action can be added to the HTML Form Authenticator.

1. Go to Profiles → Authentication Service → Authenticators and click the HTML Form Authenticator to use.
2. In the Actions column and the Login lane, click Add and then click New Action.
3. Enter a name, e.g., getAttributes. Choose the Data Source type and then click Next.
4. Select the Data Source that was previously modified from the Attribute Data Source drop-down and click close.
5. From the Changes menu, click Commit.

The Authenticator configuration should now look like this:

Introspection Procedure

A custom introspection procedure is needed that can add the entitlements to the result. To do this in the UI, perform the following:

1. Open the Token Service profile that is being used.
2. Click Endpoints on the left-hand side.
3. Search for the introspection endpoint that is being used.
4. In the Flows dropdown associated with that endpoint, click the introspect procedure drop-down. Choose New Procedure and enter a name, e.g., entitlements-in-introspection. Click the Save button.
5. An editor will open. In this, replace the existing script with the following:

function result(context) {
    var responseData = {
        active: context.presentedToken.active
    };

    if (context.presentedToken.active) {
        appendObjectTo(context.presentedToken.data, responseData);

        responseData.entitlements = getEntitlements(context);
        responseData.token_type = context.presentedToken.type;
        responseData.client_id = context.presentedToken.delegation.clientId;
        responseData.expired_scope = context.presentedToken.expiredScopes;
    }

    return responseData;
}

function getEntitlements(context) {
    var subjectAttributes = context.subjectAttributes();
    var jsonAttributes = subjectAttributes["attributes"];

    if (jsonAttributes) {
        var parsedJsonAttributes = JSON.parse(jsonAttributes);

        return parsedJsonAttributes["entitlements"].map(function (x) {
            return x.value;
        });
    }
    else {
        return null;
    }
}

6. Click Update, and then close the editor
7. From the Changes menu, click Commit.

Checking the Introspection Results

To test the procedure, a token that represents the user is required. Tokens that represent a client only, like those issued when the client credential flow is used, will not work. A user-specific access token that runs the custom credential query and gets the entitlements will be issued after the user logs in with an HTML Form Authenticator that uses that Data Source. (The Data Source will not be used directly but through the Credential Manager that the HTML Form Authenticator uses.) With this token in hand, the API or the API gateway can introspect it. A sample request is shown in the following listing:

POST /oauth/v2/oauth-introspect HTTP/1.1
Host: localhost:8443
Authorization: Basic Y2xpZW50LW9uZTowbmUhU2VjcmV0
Content-Type: application/x-www-form-urlencoded
 
token=_0XBPWQQ_a7409965-43fb-4fef-9620-0ff9ae4fdc53

Here, the client ID and secret are supplied in the HTTP Authorization header using the basic authentication scheme. This credential is that of the API gateway (or if no such gateway is used, then the API itself). This client must have the introspection capability, and if it is only an API gateway, it should not have any other capabilities. The result will be a JSON document such as the following where the entitlements are returned as an array of values:

{
    "sub": "teddie",
    // ...
    "scope": "read openid write",
    "entitlements": [
        "a",
        "b",
        "c"
    ]
}

These will be the same ones set by the SCIM client at the beginning of the walk-through. With this information in hand, the gateway has not only the scopes but other permissions necessary to make a course-grained access control decision.

Conclusion

This writeup shows how to setup the Curity Identity Server as a SCIM 2 server and optionally enable the User Management GraphQL API by defining a user management profile. With that it's possible to add information to a user, such as entitlements. How that information can be used to enrich introspection results of tokens that are issued through the Curity Identity Server was also demonstrated. With this, an API gateway can enforce access control. In all of this, the APIs exposed through the Curity Identity Server are standards-based, making it fast and easy to integrate into existing customer portals, mobile apps, and web sites. This entire use case was implemented as configuration and required no custom coding and can be setup in just a few minutes.