Onboarding externalized authorization

Account details

For each new OneWelcome Identity Platform customer, a tenant is created and the following values are communicated to the customer via email:

• tenant code, which is used in the API endpoints
• Support Desk account

The tenant can be configured via the OneWelcome Identity Platform Config API. Access to this API is granted through an invitation from Thales. A member of your organization will be invited to become the Security Admin for your organization in our system. Upon accepting this role, the Security Admin is free to invite Config Editors (via self-servicing in our developer portal), which will receive the claims needed for accessing the Config API on behalf of your organization.

How to access the Config API

Each request to the Config API requires a user access token obtained by a user with the correct administrator permissions.

1. Log in at https://manage.scaledaccess.com with your personal username and password.
2. Go to Settings and click Advanced Settings.
3. Copy the displayed user access token. This token is valid for 24 hours.

1. Place the access token in the authorization header of subsequent requests to the Config API:

   • Consent Config API
   • Relationship Config API
   • Authorization Config API
   • Event Stream API
   • Logs API

How to access the management APIs

1. Send an HTTP request to obtain a user access token from the authorization API or one of our trusted authorization servers, such as Auth0 and Okta. The access token must apply with the following:

   • the issuer and JWKS endpoint have been configured for your tenant,
   • the token signature algorithm is ES256 (ECDSA) or RS256 (RSA),
   • the sub claim is available, and
   • the aud claim is (one of) the allowed audiences as configured for your tenant.

   Note

   Tenant configuration changes can be requested via support@onewelcome.com or can be made by the administrator (only for the Relationship Management API).

2. Place the access token in the Authorization Header of subsequent requests to the Consent Management API, Relationship Management API, or Mail API.

Example: Obtain a user access token with the Authorization Code grant type

step 1A

curl --location --request GET 'https://myauthenticationserver.com/auth?client_id=c96hhv8j7ece9ga4g5wm85m5abwvxr9m&response_type=code&scope=openid&redirect_uri=https://example.com/callback&state=dacfe1341a7d499e88ffa61a0417c1a5&nonce=dd305f270a9f4738899747d0ac56e8e8' \

step 1B

curl --location --request POST "https://myauthenticationserver.com/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic cjRTd0Zab1NGRG92VGJENmVnbEM4YWNLYXE1VEVBd1FQOmRab3pqeGViY1lWMEdVY0dsSFdTRUJaNHhpOVRobnZTTw==" \
  --data "grant_type=authorization_code&code=cd89d399f60046b20449&redirect_uri=https://example.com/callback \

Integration with Auth0

This how-to helps you get up and running by integrating the Externalized Authorization module with Auth0.

Auth0 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 Auth0 that enables the enrichment of its access tokens with claims based on, for example, your users' relationships (see relationship-based access control). All you need to do is to define a custom rule in the Auth0 dashboard and specify which scope you want to add.

How to add a custom relationship claim

You can test your setup using Postman by following the instructions in Testing token enrichment in Postman.

Auth0 setup

Step 1. Create a custom action

1. Create a new custom action in Auth0 to be used in a post-login flow.

2. Go to Actions > Library and click Build Custom.

3. Choose a name for your Action.

4. Copy the script on the right in the online editor and paste it on the Create Action page.

5. Click Secrets, which is the key icon on the left.

6. Enter the Key and Value for the following secrets (click Add Secret to add multiple entries):

   Key	Value
   TENANT	Your tenant code provided by the OneWelcome Identity Platform (see account details). This code can be found in manage.scaledaccess.com after your sandbox environment is set up.
   APIKEY	The API key connected to your OneWelcome Identity Platform tenant. Create and use the API key for your tenant (see set up webhook configuration).

7. Click Deploy.

Step 2. Use the custom action in a login flow

1. Create a Login Flow in Auth0 that uses the Custom Action.

2. Go to Actions > Flows and click Login.

3. Drag the Custom Action you made in the previous step.

4. Click Apply.

Obtaining and using an enriched access token

Step 3. Request an Auth0 access token

The Auth0 custom action that you define here adds a custom claim with an array of relationships. If the array is empty, there are no relationships (yet). If the custom claim is missing, the custom action is not working.

1. Use your regular method to request an access token.

2. Confirm that the access token contains the custom claim (for example, by copying the token into jwt.io).

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 custom claim.

    exports.onExecutePostLogin = async (event, api) => {
        const HOOK_URL = "https://hooks.scaledaccess.com";
        const CUSTOM_CLAIM_ID = "https://scaledaccess.com/relationships";
        const { TENANT, APIKEY } = event.secrets;
        const { user_id } = event.user;

        if (!TENANT || !APIKEY) {
            console.error(
                "Please provide a ReBAC tenant and an associated API key."
            );
            return;
        }

        const response = await fetch(`${HOOK_URL}/${TENANT}`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                apiKey: APIKEY,
            },
            body: JSON.stringify({ user: { id: user_id } }),
        });

        if (!response.ok) {
            const errorResponse = await response.text();
            console.error(`Could not connect to ${HOOK_URL}.`, errorResponse);
            return;
        }

        const { relationships } = await response.json();

        if (!relationships) {
            console.error(
                `Something went wrong processing the relationships of user with id "${user_id}".`
            );
            return;
        }

        api.accessToken.setCustomClaim(CUSTOM_CLAIM_ID, relationships);
    };

Testing token enrichment in Postman

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

The instructions in this how-to are an application of the explanation in how to add a custom relationship claim.

Auth0 setup

Step 0. Prepare the client application for Postman callbacks

1. Add the following URL to the allowed callback URLs for your client application in the Auth0 dashboard: https://getpostman.com/oauth2/callback

Steps 1-3. Add the Auth0 custom action

Follow the instructions in steps 1-3 of how to add a custom relationship claim to create the Auth0 custom action.

Obtaining an enriched access token in Postman

Step 4. Request an Auth0 access token

1. Start a new request.

2. Go to the Authorization tab and select type OAuth 2.0.

3. Click Get New Access Token. A new screen will open.

4. Fill in the requested parameters as shown below. Make sure to replace the variables with the values found in the Auth0 dashboard.

   Note

   The audience query parameter in the callback URL is required for use of the access token.

   Parameter	Value
   Token Name	(Optional)
   Grant Type	Authorization Code
   Callback URL	https://{auth0_tenant}.auth0.com/authorize?audience={auth0_audience}
   Access Token URL	https://{auth0_tenant}.auth0.com/oauth/token
   Client ID	{auth0_client_id}
   Client Secret	{auth0_client_secret}
   Scope	openid
   State	randomstate
   Client Authentication	Send as Basic Auth header

5. Click Request Token.

   

The obtained token has a custom claim with relationships. The content of the enriched access token can be viewed by copying the token into jwt.io.