Token Delegation

Aritma ID supports token delegation aka token exchange.

Delegating internal tokens

Some times you want to exchange a Aritma token with a new Aritma token with different scopes. For example a SPA login token that only has the openid and profile scopes, but your backend needs to call the bankservice API and then must have the BankService scope aswell. To be able to make delegation token requests your client needs to have the delegation grant_type enabled.

Parameter Value
grant_type "delegation"
client_id your client id
client secret your client secret
token jwt access token
scope desired scopes separated by space. f.ex. "profile"
Copy
Copied
POST /connect/token HTTP/1.1
Host: id.aritma.io
Content-Type: application/x-www-form-urlencoded

grant_type=delegation&client_id=MyDelegatingClient&client_secret=MyClientSecret&token=<your token: eyJhb... etc.>&scope=profile

The response will be a standard token response:

Copy
Copied
{
    "access_token": "eyJhb...aKw",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Delegating external tokens

We support delegation of external provider tokens for a select group of external providers. This means that if your identity server is one of these, it is possible to take a token from your identity server and transform it into a Aritma token with any scopes that your Aritma ID client is allowed to use. If you think your identity server should be a trusted delegation source, please contact us.

To delegate an external token you can make the following request:

Parameter Value
grant_type "delegation"
client_id your client id
client secret your client secret
token jwt access token
scope desired scopes separated by space. f.ex. "profile"
provider external provider id that matches token
Copy
Copied
POST /connect/token HTTP/1.1
Host: id.aritma.io
Content-Type: application/x-www-form-urlencoded

grant_type=delegation&client_id=MyDelegatingClient&client_secret=MyClientSecret&token=<your token: eyJhb... etc.>&scope=profile&provider=<externalprovider>

The response will be a standard token response:

Copy
Copied
{
    "access_token": "eyJhb...aKw",
    "expires_in": 3600,
    "token_type": "Bearer"
}

External provider delegation with user linking

The above example will only work if the subject of the token is already connected with a Aritma user. It is also possible to connect the subject of the token with an existing Aritma user by using the token delegation grant type. To do this you will have to supply the email address and password of the user you are attempting to connect.

If your userinfo endpoint supplies one of the claims email or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, you can leave the email parameter out of the request.

Parameter Value
grant_type "delegation"
client_id your client id
client secret your client secret
token jwt access token
scope desired scopes separated by space. f.eks. "profile"
provider external provider id that matches token
email the Aritma username/email address
password the Aritma user's password
Copy
Copied
POST /connect/token HTTP/1.1
Host: id.aritma.io
Content-Type: application/x-www-form-urlencoded

grant_type=delegation&client_id=MyDelegatingClient&client_secret=MyClientSecret&token=<token>&scope=profile&provider=softrig&email=<aritma user email>&password=<aritma user password>

External provider autoprovisioning

If your user does not have an existing user in Aritma ID it is possible to autoprovision users using the delegation grant. However, this has some additional requirements for your identity server. Your userinfo endpoint needs to provide the following claims:

  • email or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • family_name or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • given_name or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname ( middle_name is optional)
  • phone_number or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone

The provisioned user will get a username that is the same as the email claim.