Scope attributes

Overview

This article describes scope attributes.

This feature is available since Authlete 2.0.

What are scope attributes?

Scopes attributes are arbitrary key-value pairs associated with a scope. You can configure multiple scope attributes for each scope and utilize them for authorization decision and other processing in your authorization server. Some of attributes are predefined by Authlete to be used for system settings.

The key and value of a scope attribute are string values and each scope can have multiple scope attributes. 
How to create scope attributes

---

You can create scope attributes at Service Owner Console as below.

1. Open the edit page for your service at Service Owner Console.
2. Click “Create Scope” button to open a dialog box for creating a new scope.
3. Click “New Attribute” button.
4. Enter a key-value pair of the attribute and then click “Create” button. Note that key and value are string type.

Video for instructions: Scope attributes.mov 5.63 MB

Predefined scope attributes

The scope attributes listed below are predefined by Authlete for special purposes.

Attribute key	Attibute value	Description
access_token.duration	number	This attribute is used to configure access token duration for each scope. For more details, see “Token duration per scope”.
refresh_token.duration	number	This attribute is used to configure refresh token duration for each scope. For more details, see “Token duration per scope”.
fapi	r	This is used to enable FAPI read-only API profile on Authlete. For more details see “How to use FAPI feature”.
fapi	rw	This is used to enable FAPI read-and-write API profile on Authlete. For more details see “How to use FAPI feature”.
regex	regular expression	This attribute is used to use a scope string with a dynamic value as a part of it. For more details see “Using “parameterized scopes””.
fapi2	sp	This is used to enable FAPI2 Security profile on Authlete. For more details see “Authorization Code Flow in FAPI 2.0 Security Profile”
fapi2	ms-authreq	This is used to enable FAPI2 Message Signing profile for Authorization Requests on Authlete. You can associate a scope with both this attribute and (fapi2, ms-authres).
fapi2	ms-authres	This is used to enable FAPI2 Message Signing profile for Authorization Responses on Authlete. You can associate a scope with both this attribute and (fapi2, ms-authreq).

How to use scope attributes

You can utilize scope attributes for various use cases, like tagging risk level to scopes, required ACR for granting the scope, among other use case already covered by the predefined scopes attribute.

The authorization response

The authorization response from Authlete from /api/auth/authorization endpoint includes the scope attributes as the response body below

{
    "type": "authorizationResponse",
    "resultCode": "...",
    "resultMessage": "...",
    "acrEssential": false,
    "action": "...",
    "client": {...},
    "clientIdAliasUsed": false,
    "maxAge": 0,
    "responseContent": "...",
    "scopes": [
        {
            "defaultEntry": false,
            "description": "A permission to request an OpenID Provider to issue an ID Token. See OpenID Connect Core 1.0, 3.1.2.1. for details.",
            "name": "openid"
        },
        {
            "defaultEntry": false,
            "name": "payment"
        }
    ],
    "service": {
        ...
        "supportedScopes": [
            {
                "defaultEntry": false,
                "description": "A permission to request an OpenID Provider to issue an ID Token. See OpenID Connect Core 1.0, 3.1.2.1. for details.",
                "name": "openid"
            },
            {
                "attributes": [
                    { "key": "meta", "value": "this profile requires a second factor authentication" },
                    { "key": "fapi", "value": "rw" }
                ],
                "defaultEntry": false,
                "name": "payment"
            },
            ...
        ],
        ...
    }
}

Using Java Authlete library

The following code snippet of an authorization server is an example using Authlete’s /auth/authorization API for parsing an authorization request from a client, and doing something  based on attributes of scopes included in the request.

// Call Authlete /api/authorization API.
AuthorizationResponse res = callAuthorizationAPI();

// Get scopes contained in the original authorization request.
Scope[] scopes = res.getScopes();

if (scopes == null || scopes.length() == 0) {
    return;
}

// Check each scope's attributes.
for (Scope scp in scopes) {
    // Get the scope attributes of the scope.
    Pair[] attributes = scp.getAttributes();

    if (attributes == null || attributes.length() == 0) {
        continue;
    }

    // Check each attributes.
    for (Pair attr in attributes) {
        // The key of the attribute.
        String key = attr.getKey();

        // The value of the attirbute.
        String value = attr.getValue();

        // If the key is the target one.
        if ("targetkey".equals(key)) {
            // Do something with the value.
            doSomething(value);
        }
    }
}