---
sidebar_label: 'Overview'
sidebar_position: 1
---

# Authenticating external users

Future Ordering supports signing into user accounts via external identity providers, with or without user interaction.

## Authentication without user interaction

To authenticate users and request access tokens without user interaction, a special backchannel grant type for the OAuth token endpoint is provided. This allows an external identity provider to exchange a signed OIDC ID token of an external identity for an access token of a Future Ordering user connected to that external identity, reversing the standard OAuth/OIDC authentication flow.

```mermaid
sequenceDiagram
    participant fo as Future Ordering
    participant idp as External Identity Provider

    idp ->>+ fo : POST /connect/token<br/>Grant type: 'backchannel_external_token'<br/>Subject token: Signed ID token with user data
    note over fo : If a user connected to the external identity does not exist,<br/>it is created with the personal data provided.
    note over fo : If a user connected to the external identity already exists,<br/>it is updated with the personal data provided.
    fo ->>- idp : Access token JWT<br/>for the user connected to the external identity
```

### Token request properties
| Property | Description |
| --- | --- |
| `grant_type` | The grant type: `backchannel_external_token` |
| `client_id` | The client ID <!-- todo --> |
| `client_secret` | The client secret <!-- todo --> |
| `subject_token` | A signed [OIDC ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) JWT of the user to authenticate. See [below](#generating-an-id-token) for more information. |
| `subject_token_type` | The subject token type: `urn:ietf:params:oauth:token-type:id_token` |
| `scope` | A space separated list of scopes for the requested access token, e.g. `fo:auth` |

*Example token request:*
```bash
curl -L -X POST 'https://<tenantId>.login.futureordering.com/connect/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=backchannel_external_token' \
    --data-urlencode 'client_id=<clientId>>' \
    --data-urlencode 'client_secret=<clientSecret>' \
    --data-urlencode 'subject_token=<subjectToken>' \
    --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
    --data-urlencode 'scope=<scopes>'
```

### Generating an ID token

To authenticate the token request, a signed [OIDC ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) is included. This token must at least include a *subject ID* - a value used to uniquely and persistently identify the user. Subsequent token requests with a given subject id will yield access tokens for a single user account in Future Ordering.

The token may also optionally include the user's personal data, such as name and e-mail address. The following claims are currently supported:
| Claim | Description |
| --- | --- |
| `sub` | The user's unique subject id. **Required** |
| `iss` | A unique identifier for your token issuer, e.g. `https://myissuer.example.com` **Required** |
| `aud` | The intended receiver of the token, e.g. `https://mytenantid.login.futureordering.com` **Required** |
| `email` | The user's email address. *Optional* |
| `given_name` | The user's given name. *Optional* |
| `family_name` | The user's family name. *Optional* |

*Example JWT payload:*
```json
{
    "sub": "my-unique-subject-id",
    "email": "johndoe@example.com",
    "given_name": "John",
    "family_name": "Doe",
    "nbf": 1789390374,
    "exp": 1789390674,
    "iat": 1789390374,
    "iss": "https://myissuer.example.com",
    "aud": "https://mytenantid.login.futureordering.com"
}
```

*Example JWT header:*
```json
{
    "alg": "ES256",
    "kid": "my-key-id",
    "typ": "JWT"
}
```

When the payload been built, encode a JWT and sign it using the `ES256` signing algorithm and include it in the token request.

:::info
To get started using this authentication flow, contact Future Ordering and provide
- a PEM encoded public key,
- the key id of the key used to sign the tokens,
- the value that will be sent in the `iss` claim.
:::