Simple User Provisioning and Authentication

Using this flow, it is possible to authenticate a user and provisioning their account (if it does not already exist) in a single operation.

❗️

This service is not activated on new trial accounts by default.

If you wish to utilise this service, please contact us so that we can discuss your requirements and add this service to your API key.

This is useful for customers who:

• Wish to use their own identity management in their client and
• Don't wish to implement their own STS server

Now, with our custom grant (see below), you can create an Altitude Angel User Identity, obtain the User token for it and authenticate with it in a single operation!

Client vs. User tokens (Background)

Normally, a client would request a Client Token using an OAuth token request with a grant_type of client_credentials. However, this would only result in the issuance of a Client token. You will need to instead obtain a User token if:

• Your license type is "per-user", or
• The API method you are calling requires it

The normal OAuth mechanism for generating User tokens is to use the grant_type = authorization_code, after using the /authorize endpoint to request user login and permissions. This, however, requires a more complete implementation of an OAuth client and only supports external user identities through OAuth delegation, requiring the owning entity to support OAuth fully with their own secure token server (STS).

To simplify this process for our customers that do not have their own STS or wish to implement one, we offer the alternative grant_type = client_with_profile.

Client With Profile custom grant

This grant type allows you, acting as a "Trusted 3rd Party" to Altitude Angel, to request user tokens for users that you have provisioned through your Client ID. In essence, these users are unique to your Client and can only be managed by you.

We will automatically provision an Altitude Angel User Account when we cannot find an existing user identity in your segregated user account store using the profile you have supplied.

This provides an easy mechanism to provision users and acquire an access token for them in a single step in server-to-server flows.

Security

To ensure the integrity and security of our user data we implement that following restrictions:

• Only trusted partners are able to use this grant type and the Client ID requesting the token must be specifically enabled to support this.
• User access tokens can only be requested using this mechanism for users provisioned using this mechanism. Regular (global) Altitude Angel users cannot be requested in this manner.
• Users provisioned in this manner will be partitioned such that only the provisioning client can access them. Such accounts are also solely restricted to logins within the Client ID that provisioned them.

Concept

To enable Simple User Provisioning, your client will form a largely standard OAuth request but with an additional field that will contain your user's profile.

The JSON blob for the profile looks like this:

JSON

{
    "external_id": "YOUR_SYSTEM_USER_ID",
    "email": "[email protected]",
    "country_code": "GB",
    "first_name": "James",
    "last_name": "Kirk"
}

If we can't find a match for the external_id and email you have specified, we'll provision a new user account; that's auto-provisioning! Otherwise, we'll provide the matching (existing) user account's token. Simple!

Considerations for User IDs

The external_id must be unique per organisation.

Failure to adhere to this principle may make it impossible for us to later merge your now segregated user account into our Global UTM products, which would create a lot more work for you at a later stage if you later wish to re-integrate with national UTM systems.

How to implement

Follow the steps below to implement Simple User Provisioning and Authentication within your client.

Request format

Clients form a largely standard OAuth client_credentials request with a single additional field. This field includes the user profile as a JSON encoded blob.

Sample request:

HTTP

POST /oauth/v2/token HTTP/1.1
content-type: x-www-form-urlencoded

grant_type=client_with_profile
&scope=query_mapdata%20manage_flightreports
&client_id=123456
&client_secret=abcdef
&profile=%7B%22external_id%22%3A%22users+external+id%22%2C%22email%22%3A%22user%40somewhere.com%22%2C%22country_code%22%3A%22GB%22%2C%22first_name%22%3A%22James%22%2C%22last_name%22%3A%22Kirk%22%7D

The JSON blob for the profile looks like this:

JSON

{
    "external_id": "users external id",
    "email": "[email protected]",
    "country_code": "GB",
    "first_name": "James",
    "last_name": "Kirk"
}

This will result in a user access token and refresh token being returned. We will auto-provision the user if no match is found.

Subsequent future requests should still send the profile as this will be used to validate the user.

The fields are explained below:

Field Name	Description
external_id	Immutable, unique identifier for the user from the organisation provisioning / logging in on behalf of the user
email	The email address of the user
country_code	The ISO 3166-1 alpha-2 country code that the user resides in
first_name	The user's first (given) name
last_name	The user's last (family) name