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.

Token request properties

Property	Description
grant_type	The grant type: backchannel_external_token
client_id	The client ID
client_secret	The client secret
subject_token	A signed OIDC ID token JWT of the user to authenticate. See below 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:

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 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:

{
    "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:

{
    "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.