Configuring Token Exchange#

Blitz Identity Provider supports the OAuth 2.0 Token Exchange technology. A typical usa case of this technology in Blitz Identity Provider is the interaction of the Blitz Keeper security gateway with the authorization service to gain access to protected services.

To configure Token Exchange, follow the sequence described below.

Step 1. Create service access rules#

Token Exchange rules to access protected services are created in the /usr/share/identityblitz/blitz-config/token_exchange/rules/ directory. Each rule is created as a separate text file without extension.

Example of a file with an access rule (the specialize type):

{
    "name": "rule-name",
    "type": "specialize",
    "desc": "",
    "subjectTokenCond": {
        "clientRights": [],
        "userRights": [],
        "scopes": ["openid"],
        "userClaims": {},
        "userGroups": []
    },
    "issue": {
        "ttlInSec": 3600,
        "allowedScopes": ["openid","profile"],
        "allowedClaims": ["sub","global_role","org_id","rights"],
        "addingScopes": [],
        "addingClaims": []
    }
}

Example of a file with an access rule (the impersonate type):

{
    "name": "rule-name",
    "type": "impersonate",
    "desc": "",
    "subjectTokenCond": {
        "clientRights": [],
        "userRights": [],
        "scopes": ["openid"],
        "userClaims": {},
        "userGroups": []
    },
    "authClientCond": {
        "requiredRights":[
            {
                "rights": ["right1"],
                "target": {
                    "type": "its",
                    "name": "app1"
                }
            }
    },
    "issue": {
        "ttlInSec": 3600,
        "allowedScopes": ["openid","profile"],
        "allowedClaims": ["sub","global_role","org_id","rights"],
        "addingScopes": [],
        "addingClaims": []
    }
}

Following attributes of the access rule must be set:

name - name of the rule, which must match the name of the file with the access rule;
type – type of the rule. The following rule types are supported:
- specialize – according to this rule, an application requests the exchange of an access token issued to the same application. The exchange is performed for the purpose of specializing the access token: replacing permissions (scope), attributes (claims), the list of recipients (audience, aud), or the token format (jwt or opaque);
- impersonate – according to this rule, an application requests the exchange of an access token issued to another application. The exchange is carried out provided that in the access token being exchanged, the requesting application is in the list of recipients (audience, aud). Such an exchange is used when application A initially received an access token, prepared it for transmission to application B (via an exchange using the specialize rule type), passed it on to application B, so that application B issued its own token based on the received one ( through an exchange using the impersonate rule type).
desc - description of the rule. You can enter any text information;
subjectTokenCond - conditions of rule fulfillment. If all the conditions specified in the rule are met, the rule is considered to be executed. If at least one of the conditions in the rule is not fulfilled, the whole rule is considered unfulfilled. The conditions of rule fulfillment can be as follows:
- clientRights - check if the application has the specified access rights;
  
  Example of the rule:
```
"clientRights": [
{
    "rights": ["right1"],
    "target": {
    "type": "its",
    "name": "app1"
    }
}
]
```
  In this example, the calling application checks whether the calling application has the right1 access right with respect to another application (app1). The its parameter in the target setting specifies the type of object against which the access right is checked. Possible values: its - right to an application; grps - right to an access group; no type - right to a user account.
- userRights - check if the user has the specified access rights.
  
  Example 1 of a rule:
```
"userRights": [
{
    "rights": ["right2"],
    "target": {
    "type": "grps",
    "name": "org1",
    "ext": "orgs"
    }
}
]
```
  In the example, it checks whether the user has the right2 access right with respect to the user group (org1). In case of the access group object type, an additional parameter ext is specified to define the access group profile (see Enabling the display of groups in blitz.conf).
  
  Example 2 of a rule:
```
"userRights": [
{
    "rights": ["security_administrator"],
    "target": {
    "type": "grps",
    "name": "${org_id}",
    "ext": "orgs"
    }
}
]
```
  This rule checks whether the user has the security_administrator access right with respect to the user group from the orgs profile, which has an identifier that matches the value of the org_id attribute from the original access token. In contrast to Example 1, this example illustrates the possibility to specify not a specific object value as the name of the access right object, but to refer to the object based on the values from the submitted access token ($org_id).
  
  Example 3 of a rule:
```
"userRights": [
{
    "rights": ["right3"],
    "target": {
    "type": "its",
    "name": "app1"
    }
}
]
```
  The above example checks if the user has the right3 access rights with respect to application app1.
- scopes - checks the presence of the required permissions in the access token (see General OAuth 2.0 settings);
  
  Example of the rule:
```
"scopes": ["scope1"]
```
  This example checks if the original access token scopes with the name scope1.
- userClaims - checks that the attributes of the user account have specified values.
  
  Example of the rule:
```
"userClaims": {"role":"FIN"}
```
  This example checks if a user has the role attribute in the account with the FIN value filled in. Only attributes with String type can be used.
- userGroups - checks if the user account is part of the specified access groups.
  
  Example of the rule:
```
"userGroups": [
{
    "name": "admin",
    "profile": "roles"
}
]
```
  This example checks that the user is in the admin access group with roles profile.
authClientCond – conditions for replacing client_id. These conditions are only checked for the impersonate rules. The rule verifies that the new application has the permissions to exchange the access token. The requiredRights condition is supported.

Example of the rule:
```
"requiredRights":[
  {
    "rights": ["right1"],
    "target": {
      "type": "its",
      "name": "app1"
    }
  }
]
```
In this example, the calling application checks whether the calling application has the right1 access right with respect to another application (app1). The its parameter in the target setting specifies the type of object against which the access right is checked. Possible values: its - right to an application; grps - right to an access group; no type - right to a user account.
issue - rules for issuing a new access token, applied in case the rule was successfully executed. The rules for issuing a new access token consist of:
- ttlInSec - the lifetime (in seconds) of the issued access token;
- allowedScopes - the scopes that allowed in the issued access token;
- allowedClaims - user attributes that allowed in the issued access token;
- addingScopes - the scopes added to the access token;
- addingClaims - user attributes added to the access token.

Step 2. Configuring access token exchange#

To define how access tokens will be exchanged over Token Exchange, specifically for which protected services which access rules should be applied, add the blitz.prod.local.idp.token-exchange configuration block to the blitz.conf configuration file as follows:

"token-exchange" : {
  "resources" : [
    {
      "uri" : "http://secured_service_host/api/service1",
      "methods" : ["GET","POST"],
      "rules" : [
        "rule1",
        "rule2"
      ]
    },
    {
      "audience" : "secured-api",
      "rules" : [
        "rule3"
      ]
    },
    …
  ]
}

In the resources block you need to fill in the settings for each service:

rules – list the names of service access rules. Each rule corresponds to its own configuration file. Access to the service is allowed if at least one of the rules from this list is executed. If all the listed rules are not met, then access to the service will be denied;
uri – optional parameter, can specify the address of the protected service. In specifying the service address it is allowed to use an asterisk (*) to skip one component of the address path and a double asterisk (**) to skip the rest of the service address path;
methods - optional parameter, specifies the list of HTTP methods of the invoked service;
audience – optional parameter, can specify the application name. This value will be included in the issued new access token in the aud attribute. It is mandatory to specify one of the parameters uri or audience.