# 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.

<figure><img src="https://2414485336-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUGN3Vu2Hi1voQQLrIVGO%2Fuploads%2F0PrI1XR2udSh6cWHrnsx%2Fimage.png?alt=media&#x26;token=f1741b0c-1534-4ef9-8243-fb373dcde6bd" alt=""><figcaption><p>Fig1: Application Settings</p></figcaption></figure>

### 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.

<figure><img src="https://2414485336-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUGN3Vu2Hi1voQQLrIVGO%2Fuploads%2F61jkolyI2fl7t2B3eGBT%2Fimage.png?alt=media&#x26;token=376f17f7-94d1-48f0-89c2-7a168fff1f8b" alt=""><figcaption><p>Fig3: Allowed Callback URLs</p></figcaption></figure>

**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.

<figure><img src="https://2414485336-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUGN3Vu2Hi1voQQLrIVGO%2Fuploads%2FSLnKX3C6RvEw2wvW5iyA%2Fimage.png?alt=media&#x26;token=34df47f4-845c-4908-b139-3ca301f503e0" alt=""><figcaption><p>Fig4: Allowed Web Origins</p></figcaption></figure>

**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.&#x20;

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}
```

4. Select "Selected Initiators Only" in Back-Channel Logout Initiators.
5. Enable Specific Logout Conditions: Ensure that the following options are selected:
   1. Account Deleted
   2. Account Deactivated

<figure><img src="https://2414485336-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUGN3Vu2Hi1voQQLrIVGO%2Fuploads%2FQaS8oDLFDnJEy8oHnJSc%2Fimage.png?alt=media&#x26;token=4c48caa2-123a-42f4-a4d3-642af396307e" alt=""><figcaption><p>Fig5: OKTA Configuration</p></figcaption></figure>

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.&#x20;