# 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" |



```HTTP
POST https://id.aritma.io/{tenant}/connect/token HTTP/1.1
Host: id.aritma.io
Content-Type: application/x-www-form-urlencoded

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


```HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "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 |



```HTTP Request
POST https://id.aritma.io/{tenant}/connect/token HTTP/1.1
Host: id.aritma.io
Content-Type: application/x-www-form-urlencoded

    client_id=CLIENT_ID&
    client_secret=CLIENT_SECRET&

    grant_type=delegation&
    token=YOUR_TOKEN&
    scope=SCOPE&
    provider=IDP_PROVIDER
```


```HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "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 |



```HTTP Request
POST https://id.aritma.io/connect/token HTTP/1.1
Host: id.aritma.io
Content-Type: application/x-www-form-urlencoded

    client_id=CLIENT_ID&
    client_secret=CLIENT_SECRET&

    grant_type=delegation&
    token=YOUR_TOKEN&
    scope=SCOPE&
    provider=PROVIDER&
    email=EMAIL&
    password=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.