Integration with Okta

This how-to helps you get up and running by integrating the OneWelcome Identity Platform with Okta.

Okta is a solution to add authentication and authorization services to your applications. It can be connected with the identity provider of your choice and can be extended with other applications. The OneWelcome Identity Platform provides an extension to Okta that enables the enrichment of its access tokens with a claim based on your users' relationships (see Relationship-based Access Control). All you need to do is to set up an Okta inline hook.

How to set up the Okta inline hook?

Okta setup

Step 1. Create an inline hook

1. Log in to your Okta account.

2. Go to Workflow > Inline Hooks.

3. Click Add Inline Hook and select Token from the drop-down menu.

4. Enter the following values:

   Field Name	Value	Description
   Name	ReBAC
   URL	https://hooks.scaledaccess.com/{tenant}/okta	Your tenant code provided by the OneWelcome Identity Platform. This code can be found in manage.scaledaccess.com after your sandbox environment is set up.
   Authentication field	apiKey
   Authentication secret	The API key connected to your OneWelcome Identity Platform tenant.	Create and use the API key for your tenant (see set up webhook configuration)

5. Click Save.

Step 2. Activate the inline hook

1. Go to Security > API.
2. Select the default authorization server.
3. Click Edit.
4. Go to the Access Policies tab.
5. For the Default Policy, edit the Default Policy Rule by clicking the pencil icon.
6. In the Use this inline hook field, select ReBAC from the drop-down menu.
7. Click Update Rule.

Obtaining and using an enriched access token

Step 3. Request an Okta access token

1. Use your regular method to request an access token.
2. Confirm that the access token contains the scaledaccess_relationships claim (for example, by copying the token into jwt.io). If the user has no relationships (yet), the array will be empty.

Step 4. Make access decisions based on relationships

1. Use the enriched access token to access a protected resource at your API service.
2. The API service must provide a mechanism to grant or deny access based on the scaledaccess_relationships claim.

Testing token enrichment in Postman

This how-to gives detailed instructions on how to use Postman to obtain an Okta access token enriched with the relationships of the authenticated user.

Okta setup

Make sure to first complete the instructions in how to set up the Okta inline hook.

Step 1. Create a demo application

1. Log in to your Okta account.
2. Go to Applications > Applications and click Add Application.
3. Click Create New App.
4. Select Native Service from the Platform drop-down menu.
5. Click Create.
6. Name your application, such as OneWelcome Demo.
7. Click Add URI and enter a dummy URL, such as http://localhost.
8. Click Save.
9. Edit the General Settings in the General tab:
10. In the Allowed grant types field, select the Resource Owner Password check box.
11. Click Save.

Step 2. Assign the demo application to a test user

1. Go to Directory > People.
2. Create a test user:
3. Click Add Person.
4. Fill in the form. (For a test user, we recommend selecting Set by admin from the Password drop-down menu, and deselecting User must change password on first login.)
5. Click Save.
6. Select the test user.
7. Click Assign Applications.
8. Click Assign next to OneWelcome Demo.
9. Click Save and Go Back.
10. Click Done.

Obtaining an enriched access token in Postman

Step 3. Request an Okta access token

1. Start a new request in Postman.
2. Select POST and enter {issuer_uri}/v1/token in the URL field. The Issuer URI for the default Authorization Server can be found in the Security > API page.
3. Go to the Body tab and select x-www-form-urlencoded.

4. Enter the key-value pairs:

   Key	Value
   grant_type	password
   scope	openid
   client_id	The client ID* of the OneWelcome Demo application.
   username	The username of the user in step 2.
   password	The password of the user in step 2.

   *The client credentials can be found by selecting the OneWelcome Demo in the Applications > Applications page.

5. Click Send.

Step 4. Check the enriched token

1. Copy the access token in the response.
2. Paste the token in jwt.io.
3. Confirm that the token contains the scaledaccess_relationships claim. If the user has no relationships (yet), the array will be empty.