Written by Javed Shah
Please note that the EA program for Microservices has ended. The code provided in this post is not supported by ForgeRock.
In 2017 ForgeRock introduced an Early Access program (aka beta) for the ForgeRock Identity Microservices. In summary the capabilities offered include token issuance using the OAuth2 client credentials grant, token validations of OAuth2/OIDC tokens (and even ssotokens) and token exchange based on the draft OAuth2 token exchange spec. I wrote a press release here and an introductory community blog post here.
The github repository for the microservices kubernetes and docker evaluation artifacts is here.
In this article we will discuss how to implement delegation as per the OAuth2 Token Exchange draft specification. An overview of the process is worth discussing at this point. A sequence diagram is shown below:
Code for Sequence Diagram above is from sequencediagram.org.
We basically first want to grab hold of an OAuth2 token for our client to use in an Authorization header when calling the Token Exchange service. Next, we need our Authorization Server such as ForgeRock Access Management in our example, to issue our friendly neighbors Alice and Bob their respective OIDC id_tokens. Note that Alice wants to delegate authority to Bob. While we shall show the REST calls to acquire those, the details of setting up the OAuth2 Provider will be left out. We shall however discuss the custom OIDC Claims Script for setting up the delegation framework for authenticated users, as well as the Policy that sets up allowed actors who may be chosen for delegation.
But first things first, so we start with acquiring a bearer authentication token for our client who will make calls into the Token Exchange service. This can be accomplished by having the Authentication microservice issue an OAuth2 access token with the exchange scope using the client-credentials grant_type. For the example we shall just use a JSON backend as our client repository, although the Authentication microservice supports using Cassandra, MongoDB, any LDAP v3 directory including ForgeRock Directory Services.
The repository holds the following data for the client:
{
"clientId" : "client",
"clientSecret" : "client",
"scopes" : [ "exchange", "introspect" ],
"attributes" : {}
}
The authentication request is:
POST /service/access_token?grant_type=client_credentials HTTP/1.1
Host: localhost:18080
Content-Type: multipart/form-data
Authorization: Basic ****
Cache-Control: no-cache
After client authenticates, the Authentication microservice issues a token that when decoded looks like this:
{
"sub": "client",
"scp": [
"exchange",
"introspect"
],
"auditTrackingId": "237cf708-1bde-4800-9bcd-5db5b5f1ca12",
"iss": "https://fr.tokenissuer.example.com",
"tokenName": "access_token",
"token_type": "Bearer",
"authGrantId": "a55f2bad-cda5-459e-8620-3e826bad9095",
"aud": "client",
"nbf": 1523058711,
"scope": [
"exchange",
"introspect"
],
"auth_time": 1523058711,
"exp": 1523062311,
"iat": 1523058711,
"expires_in": 3600,
"jti": "39b72a84-112d-46f3-a7cb-84ce7513e5bc",
"cid": "client"
}
Bob, the actor, authenticates with AM and receives id_token:
{
"at_hash": "Hgjw0D49EfYM6dmB9_K6kg",
"sub": "user.1",
"auditTrackingId": "079fda18-c96f-4c78-90f2-fc9be0545b32-111930",
"iss": "http://localhost:8080/openam/oauth2",
"tokenName": "id_token",
"aud": "oidcclient",
"azp": "oidcclient",
"auth_time": 1523058714,
"realm": "/",
"may_act": {},
"exp": 1523062314,
"tokenType": "JWTToken",
"iat": 1523058714
}
Alice, the user also authenticates with AM and receives a special id_token:
{
"at_hash": "nT_tDxXhcee7zZHdwladcQ",
"sub": "user.0",
"auditTrackingId": "079fda18-c96f-4c78-90f2-fc9be0545b32-111989",
"iss": "http://localhost:8080/openam/oauth2",
"tokenName": "id_token",
"aud": "myuserclient1",
"azp": "myuserclient1",
"auth_time": 1523058716,
"realm": "/",
"may_act": {
"sub": "Bob"
},
"exp": 1523062316,
"tokenType": "JWTToken",
"iat": 1523058716
}
Why does Alice receive a may_act claim but Bob does not? This has to do with Alice’s group membership in DS. The OIDC Claims script attached to the OAuth2 Provider in AM checks for membership to this group, and if found retrieves a value for the assigned “actor” or delegate. In this case Alice’s has designed actor status to Bob (via some out of band method, such as on a user portal, for example). The script retrieves the actor from the user’s manager attribtue and sets a special claim with its value: may_act. The claims script is shown here in part:
Next, we must define a Policy in AM. This policy could be based on OAuth2 scopes or URI, whatever you choose. I chose to setup an OAuth2 Scopes policy but whatever scope you choose must match the resource you pass into the TE service. Rest of the policy is pretty standard, for example, here is a summary of the Subject tab of the policy:
{
"type": "JwtClaim",
"claimName": "iss",
"claimValue": "http://localhost:8080/openam/oauth2"
}
I am checking for an acceptable issuer, and thats it. This could be replaced with a subject condition for Authenticated users as well although the client would then have to send in Alice’s “ssotoken” as the subject_token instead of her id_token when invoking the TE service.
This also implies that delegation is “limited” to the case where you are using a JWT for Alice, preferably an OIDC id_token. We cannot do delegation without a JWT because the TE depends on the presence of a “may_act” claim in Alice’s subject_token. When using only an ssotoken or an access_token for Alice we cannot pass in this claim to the TE service. Hopefully thats clear as mud now (laughter).
Anyway… back to the policy setup in AM. Keep in mind that the TE service expects certain response attributes: “aud” and “scp” are mandatory. “allowedActors” is optional but needed for our discussion of course. It contains a list of allowed actors and this list could be computed based on who the subject is. One subject attribute must also be returned. A simple example of response attributes could be:
The subject must also be returned from the policy and one way to do that is to parse the id_token and return the sub claim as a response attribute. A scripted policy condition attached to the Policy Environment extracts the sub claim and returns it in the response.
This policy script is attached as an environment condition as follows:
The extracted sub claim is then included as a response attribute.
At this point we are ready to setup the Token Exchange microservice to invoke the Policy REST endpoint in AM for resource-match, allowed actions and subject evaluation. Keep in mind that the TE service supports pluggable policy backends – a really powerful feature – using which one could have specific “pods” of microservices running local JSON-backed policies, other “pods” could have Open Policy Agent (OPA)-powered regex policies and yet another set of “pods” could have the TE service calling out to AM’s policy engine for evaluation.
The setup for when the TE is configured for using AM as the token exchange policy backend looks like this:
{
// Credentials for an OpenAM "subject" account with permission to access the OpenAM policy endpoint
"authSubjectId" : "&{EXCHANGE_OPENAM_AUTH_SUBJECT_ID|service-account}",
"authSubjectPassword" : "&{EXCHANGE_OPENAM_AUTH_SUBJECT_PASSWORD|****}",
// URL for the OpenAM authentication endpoint, without query parameters
"authUrl" : "&{EXCHANGE_OPENAM_AUTH_URL|http://localhost:8080/openam/json/authenticate}",
// URL for the OpenAM policy-endpoint, without query parameters
"policyUrl" : "&{EXCHANGE_OPENAM_POLICY_URL|http://localhost:8080/openam/json/realms/root/policies}",
// OpenAM Policy-Set ID
"policySetId" : "&{EXCHANGE_OPENAM_POLICY_SET_ID|resource_policies}",
// OpenAM policy-endpoint response-attribute field-name containing "audience" values
"audienceAttribute" : "&{EXCHANGE_OPENAM_POLICY_AUDIENCE_ATTR|aud}",
// OpenAM policy-endpoint response-attribute field-name containing "scope" values
"scopeAttribute" : "&{EXCHANGE_OPENAM_POLICY_SCOPE_ATTR|scp}",
// OpenAM policy-endpoint response-attribute field-name containing the token's "subject" value
"subjectAttribute" : "&{EXCHANGE_OPENAM_POLICY_SUBJECT_ATTR|uid}",
// OpenAM policy-endpoint response-attribute field-name containing the allowedActors
"allowedActorsAttribute" : "&{EXCHANGE_OPENAM_POLICY_ALLOWED_ACTORS_ATTR|may_act}",
// (optional) OpenAM policy-endpoint response-attribute field-name containing "expires-in-seconds" values
"expiresInSecondsAttribute" : "&{EXCHANGE_OPENAM_POLICY_EXPIRES_IN_SEC_ATTR|}",
// Set to "true" to copy additional OpenAM policy-endpoint response-attributes into generated token claims
"copyAdditionalAttributes" : "&{EXCHANGE_OPENAM_POLICY_COPY_ADDITIONAL_ATTR|true}"
}
The TE services checks the response attributes shown above in the policy evaluation result in order to setup claims in the signed JWT it returns to the client.
The body of a sample REST Policy call from the TE service to an OAuth2 scope policy defined in AM looks like as follows:
{
"subject" : {
"jwt" : "{{AM_ALICE_ID_TOKEN}}"
},
"application" : "resource_policies",
"resources" : [ "delegate-scope" ]
}
Policy response returned to the TE service:
[
{
"resource": "delegate-scope",
"actions": {
"GRANT": true
},
"attributes": {
"aud": [
"images.example.com"
],
"scp": [
"read"
],
"uid": [
"Alice"
],
"allowedActors": [
"Bob"
]
},
"advices": {},
"ttl": 9223372036854775807
}
]
Again, whatever resource type you choose for the policy in AM, it must match the resource you pass into the TE service as shown above.
We have come far and if you are still with me, then it is time to invoke the TE service and get back a signed and exchanged JWT with the correct “act” claim to indicate delegation was successful. The decoded JWT claims set of the issued token is shown below. The new JWT is issued by the Token Exchange service and intended for consumption by a system entity known by the logical name “images.example.com” any time before its expiration. The subject “sub” of the JWT is the same as the subject of the subject_token used to make the request.
{
"sub": "Alice",
"aud": "images.example.com",
"scp": [
"read",
"write"
],
"act": {
"sub": "Bob"
},
"iss": "https://fr.tokenexchange.example.com",
"exp": 1523087727,
"iat": 1523084127
}
The decoded claims set shows that the actor “act” of the JWT is the same as the subject of the “actor_token” used to make the request. This indicates delegation and identifies Bob as the current actor to whom authority has been delegated to act on behalf of Alice.
Helpful Links
Microservices Docs