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	Required	The user's unique subject id.
iss	Required	A unique identifier for your token issuer, e.g. https://myissuer.example.com
aud	Required	The intended receiver of the token, e.g. https://mytenantid.login.futureordering.com
email	Optional	The user's email address.
given_name	Optional	The user's given name.
family_name	Optional	The user's family name.
extid:*	Optional	Additional external ids to associate with the user. See additional external ids for more information.

Example JWT payload:

{
    "sub": "my-unique-subject-id",
    "email": "johndoe@example.com",
    "given_name": "John",
    "family_name": "Doe",
    "extid:myprovider": "my-external-id",
    "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.

Additional external ids

In addition to the subject id, a user can be associated with additional external ids. An additional external id is an opaque value, keyed by a provider name, that links the Future Ordering user to an identity in another system.

To associate an additional external id with a user, include an extid:<provider> claim in the ID token, where <provider> is the name of the provider the id belongs to.

Additional external ids are separate from the sub claim. They are not used to identify the user when authenticating, and they are not required to be unique, so several users can share the same external id for a given provider.

To include a user's external id in an access token, request the scope extid:<provider> in the token request. The access token will then include an extid:<provider> claim with the user's external id for that provider.

info

Additional external ids must be activated before they can be used. Contact Future Ordering to activate them and register the provider names you intend to use.