OKTA Integration

OKTA is an OAuth2 authentication service that allows different organizations to be used for authentication in Zus services.

To integrate OKTA with Zus, an organization must follow a structured onboarding process that involves coordination with Zus management and proper configuration of authentication and user management settings.

Below are the steps and required details for setting up an OKTA organization in Zus.

1. Prerequisites

Before integrating OKTA with Zus, organizations must coordinate with Zus management to facilitate the onboarding process. This includes:

• Setting up an OKTA organization.

• Creating an Admin User who will have full access to all user wallets, including those of deleted users.

2. Required Organization Details

The organization must provide the following details to Zus management to enable integration:

Basic Information

These details will be displayed on Zus services and are essential for the organization’s identity:

• Name – The organization's name as it should appear on Zus services.

• URL – The official website link of the organization.

• Description – A short description of the organization's operations and purpose.

OKTA Application Credentials

These credentials must be retrieved from the OKTA Application Settings page in the OKTA dashboard:

• Domain – The organization's domain from OKTA.

• Client ID – Unique identifier for the OKTA application.

• Client Secret – Secret key associated with the OKTA application for secure authentication.

• Admin Client ID – The Admin User's Client ID, specifically created to manage user wallets, even if users are deleted.

Where to Find These Credentials?

1. Navigate to Okta OAuth2 Manage Dashboard > Applications > Applications > (Selected Application) > Settings

2. Copy Domain, Client ID, and Client Secret.

3. Create an Admin User and retrieve its Client ID.

Fig1: Application Settings

3. Configuring Application URIs and Web Origins

To ensure proper redirection after successful authentication, the following settings must be configured in the OKTA application:

Allowed Callback URLs

After the user authenticates, OKTA will redirect the user to one of these URLs.

Fig3: Allowed Callback URLs

Example:

https://blimp.software/authentication

Multiple valid URLs can be specified, separated by commas. Ensure that the URLs start with https:// as callbacks will fail otherwise.

Allowed Web Origins

This setting ensures that Zus services can properly interact with OKTA authentication.

Fig4: Allowed Web Origins

Example:

https://blimp.software

Wildcards can be used at the subdomain level, but query strings and hash information are ignored.

These settings must be configured by the organization owner to allow proper redirection to Zus services after user authentication.

4. Setting Up User Removal Webhook

To ensure account deletions are properly managed, the organization needs to configure a User Removal Webhook in OKTA.

Here are steps to Configure Back-Channel Logout Webhook.

1. Navigate to Okta OAuth2 Manage Dashboard → Applications → Applications → (Selected Application) → Settings → OpenID Connect Back-Channel Logout.

2. Locate the "Back-Channel Logout" section. Enter the Webhook URL: Use the Zus-provided webhook endpoint

https://0box.mainnet.zus.network/v2/okta/webhook?name={organization_name}

1. Select "Selected Initiators Only" in Back-Channel Logout Initiators.

2. Enable Specific Logout Conditions: Ensure that the following options are selected:

   1. Account Deleted

   2. Account Deactivated

Fig5: OKTA Configuration

If organization is intended to rotate secrets. Please connect with Zus management and we will enable removal_protection mode not to remove the organization because of non-actual secrets.

By following these steps, organizations can seamlessly integrate OKTA with Zus, ensuring secure, automated user management.