How to create an Okta API token for ellie.ai

Owned by Juha Korpela
Last updated: Feb 27, 2023 by Hugo Fournier

Target

This guide is intended for organizations with ellie.ai integrated to their Okta platform.

Outcome

This guide will let you assign users to ellie.ai roles by mapping them to Okta groups.

Explanation

The way ellie.ai has been integrated to the Okta authentication platform (OIN OIDC application) does not allow us to get the groups of an authenticated user.

This can be a problem if you want to take advantage of ellie.ai's role features (read, write, admin).

Ellie.ai needs access to your Okta API to read the list of groups a user is a member of.

In Okta, API tokens have the same permissions as the user who creates them, and if the user permissions change, the API token permissions also change. Okta documentation

It means you could simply create a new API token from your super admin account and you would be sure to give ellie.ai the necessary access. However, we do not recommend you to give super admin API tokens to any third party for security reasons.

Instead, this guide will show you how to create an API token with permissions limited to our minimal requirements.

To do so, we are going to create a new Okta user, upgrade it to an admin role, create a new API token from it and finally downgrade it to our minimal requirements with a custom admin role.

Okta does not let custom admin create an API token, that is the reason why we need to give our user a temporary standard admin role.

Prerequisite

You should have already created Okta groups for ellie.ai that will be mapped to ellie.ai roles. There should be at least three groups, one for each ellie.ai role: read, write and admin.

Here is our recommended Okta group management:

This tutorial will be based on this context case.

Steps

There are different ways to obtain the same result, here is one example:

 

  1. Sign in onto your Okta admin dashboard with your Okta super admin account

  2. Create a new user that we are going to refer as ellie.ai custom user for the rest of this guide

    1. Go to Directory > People

    2. Click on Add person

    3. Fill the form at your convenience, here are some advices but nothing mandatory:

      1. In Activation select “Activate now”

      2. Check “I will set password” and fill the password input

      3. Uncheck “User must change password on first login”

    4. Click on Save

  3. Grant ellie.ai custom user a standard admin role

    1. Go to Security > Administrators

    2. Click on Add administrators

    3. In Admin select our newly created ellie.ai custom user

    4. In Role select “Read-only Administrator” (or any other standard admin role as it is just temporary)

    5. Click on Save Changes

  4. Sign out from the Okta dashboard

  5. Sign in again but this time with your ellie.ai custom user

  6. Create a new API token

    1. Go to Security > API

    2. Go to Tokens tab

    3. Click on Create token

    4. Fill in a name (i.e. ellie-api-token)

    5. Click on Create token

    6. Save the token value (This token will be sent to ellie.ai by email)

    7. Click on OK, got it

  7. Sign out from the Okta dashboard

    We are not done yet, it is important to finish all the steps. You now have an API token, but we are going to downgrade its privileges to the minimal requirements.

  8. Sign in with your Okta super admin account

  9. Create a new custom admin role

    1. Go to Security > Administrators

    2. Go to Roles tab

    3. Click on Create a new role

    4. Fill in a name (i.e. view-users-and-groups-only)

    5. Fill in a description (i.e. “Lets the admin view users and groups details”)

    6. Check in User permissions: “View users and their details”

    7. Check in Group permissions: “View groups and their details”

    8. Click on Save role

  10. Create a new resource set (More informations about resource sets below)

    1. Go to Security > Administrators

    2. Go to Resources tab

    3. Click on Create a new resource set

    4. Fill in a name (i.e. ellie-groups)

    5. Fill in a description (i.e. “Constrains to ellie.ai groups only”)

    6. Define the first resource

      1. In Resource type select “Users”

      2. In Group names select all groups assigned to your ellie.ai application (there should be only one group: “ellie”). This group selection will define the list of users ellie.ai can view (it should mirror the list of users assigned to the ellie.ai application).

    7. Click on Add another resource type

    8. Define the second resource

      1. In Resource type select “Groups”

      2. Check “Constrain to all groups” (Recommended, otherwise you will likely have to update this resource type every time you want to change your mapping between groups and ellie.ai roles)

      3. Otherwise, in Group names select the groups ellie.ai can view (i.e. “ellie-read”, “ellie-write”, “ellie-admin” and “ellie”)

    9. Click on Save resource set

  11. Downgrade our ellie.ai custom account to our newly created custom admin role

    1. Go to Security > Administrators

    2. Go to Admins tab

    3. Find the ellie.ai custom account in the list

    4. Click on Edit assignments in the Edit dropdown

    5. In Role replace “Read-only Administrator” with the newly created custom role (from step 9)

    6. In Resource set select the newly created resource set (from step 10)

    7. Make sure there is only one role left in the assignments list

    8. Click on Save Changes

You now have an API token (from step 6) downgraded to the minimal permissions.

Resource sets

When defining a resource set, you can configure two different scopes: the users scope and the groups scope.

Ellie.ai will only use {{url}}/api/v1/users/{{userId}}/groups which correspond to an intersection of both scopes. However keep in mind that you are actually giving access to the union of both scopes (view only).

Examples

In purple: what the API token gives access to on the user scope (view only).
In blue: what the API token gives access to on the group scope (view only).
In violet: what ellie.ai is actually going to view (intersection of both scopes).
In rose: what the API token does not have access to on their respective scope.

On the tables the ✓symbol represents the membership of a user. A cell left empty means that the user is not member of the group.

Restrictive resource set

Here is a representation of the most restricted configuration.

Permissive ressource set

Here is a more permissive configuration.

It is recommended if you need to regularly update your mapping between groups and ellie.ai roles.