Obtaining a token

Any service or application that wants to integrate with the Federated Directory API's needs to obtain an access token. This access token should be placed in the Authorization header of every API call as a Bearer token. Like this:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

In this chapter we will explain in more detail:

Audiences and roles

The combination of an audience (aud) and a role describe the authorizations of an access token.

An audience basically says for what kind of user the access token was created.

Audience Description
User A user represents a person and is contained in a user directory. It's main purpose is for the usage of the platform by a person.
Key A key is not directly linked to a natural person and its main intent is for system integration. There are two kind of keys: a directory key and a admin key. Both with a different role.

A role determines the authorizations given to an access token.

Role Description
User Not able to make changes any other user in or the configuration of the same Federated Directory
directoryKey Always a key (audience) that has admin permissions on one specific directory in your Federated Directory. Ideal for integration with your current corporate address book or IAM solution (like Azure AD, Google Directory or Okta)
admin Full administrative permissions. Can modify all users and settings

Retrieve and access token with a key

There are two sort of keys.

  1. Directory key (role = directoryKey)
  2. API key (role = admin)

Decide which key is appropriate for your integration scenario.

Create a directory key

Go to 'directories' and select the directory you want integrate with. Go to the "KEY" tab and create a new key by selecting the orange + button.

After the key has been created you will retrieve 3 things:

  1. issuer
  2. private key
  3. access token

The access token is only returned once. When you create the key. This access token is valid until you delete the directory key. So keep it save.

The 'issuer' and 'private key' can be used to create access tokens. These tokens have the same lifetime as a user session. This is configurable per tenant but has a default value of 480 minutes (8 hours).

Create an API key

An API key has the same permissions as a user with the 'administrator' role.

To create such a key, go to 'integrations' in the menu and press the orange plus button in the bottom right.

After the key has been created you will retrieve 2 things:

  1. issuer
  2. private key

The 'issuer' and 'private key' can be used to create access tokens. These tokens have the same lifetime as a user session. This is configurable per tenant but has a default value of 480 minutes (8 hours).

Create an access token with the issuer and private key

Place the 'issuer' value of your key in the below JSON.

{
  "iss": "<issuer>",
  "scope": [
    "directoryKey"
  ],
  "aud": "key"
}

Use RS256 encryption to create and parse a JWT token. Use your 'private key' for this. There are a a lot of libraries available that can do this.

This JWT can then be submitted by a POST action to this end-point :

method POST
url https://api.federated.directory/v2/Login/Oauth2/Token
body See below

Body

The JWT needs to be called "assertion" in the final payload :

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<JWT>"
}

Example Request

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0dXgwMGxoczVteDY2aXkyMXhpOW9yOGt2OTZoNHBheUBmZCIsInNjb3BlIjpbImRpcmVjdG9yeUtleSJdLCJhdWQiOiJrZXkiLCJpYXQiOjE0OTMwNjQzMjl9.EY-jOhBQQadXBBxTDn7o_zF1azhL66NoAYMV0hb-mqK4edHAV8Ho5ayUcTPi2-S1VpbMrSabUDbmpN5r9YNN0TPlqBHkizpMISKiUegnhjnM6VMxkOvJvhK-4QKsG9c3tjzstX2B_gNnDUF5AQ3D1W3tZOkDut0RWBPMEmn_hnQ"
}

Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS1kZXYuZmVkZXJhdGVkLmRpcmVjdG9yeS8iLCJhdWQiOiJrZXkiLCJqdGkiOiI1ZGNjZjJjMC0yOTI5LTExZTctYTkyMy02MWVmMTEwMTMxZDQiLCJleHAiOjE0OTMwNjQzNTl9._x8avb57kx731s9L9m3Ftf57BgPvos4Z7xeFlSBkAFc",
  "token_type": "Bearer",
  "expires_in": 28800
}

You can use this token by including it in the header of any following request as:
"Authorization" : "Bearer <access_token>"

Still need help? Get in touch!
Last updated on 9th Jul 2019