# Set up Okta

This guide walks through connecting Okta as your SSO provider. Pick the protocol that fits your environment — **SAML 2.0** or **OIDC**. You only need to set up one.

Before you begin, make sure you have:

- Okta administrator access
- Agility Credit administrator access for your tenant
- The list of Okta groups (or a user attribute) that should map to Agility roles

## Pick a protocol

|                      | SAML 2.0                                    | OIDC                                  |
| -------------------- | ------------------------------------------- | ------------------------------------- |
| Setup complexity     | Higher (certificates, attribute statements) | Lower (a few URLs)                    |
| Certificate rotation | Required                                    | Not applicable                        |
| Recommended when     | Your security policy mandates SAML          | You have no specific SAML requirement |

---

## Option A — SAML 2.0

### Step 1: Open the Identity page in Agility

1. Sign in to the Agility Credit portal as an administrator.
2. Open **Settings** from the main navigation.
3. Select **Account**, then **Identity**.
4. On the **SSO** tab, choose **SAML 2.0** as the protocol.

Keep this page open — you'll copy values from the **SP Metadata** panel into Okta, and then come back to paste Okta's values here.

### Step 2: Create the SAML app in Okta

1. Sign in to your Okta admin console.
2. Go to **Applications → Applications**, then click **Create App Integration**.
3. Choose **SAML 2.0** and click **Next**.
4. Set **App name** to `Agility Credit` (or your preferred label) and click **Next**.

### Step 3: Configure SAML settings in Okta

From the **SP Metadata** panel in Agility, copy these values into Okta:

| Okta field                                         | Value to paste                                                                         |
| -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Single sign-on URL**                             | The **ACS URL** from Agility (e.g. `https://sso.agilitycredit.net/auth/saml/callback`) |
| **Use this for Recipient URL and Destination URL** | Checked                                                                                |
| **Audience URI (SP Entity ID)**                    | The **SP Entity ID** from Agility (e.g. `https://sso.agilitycredit.net`)               |
| **Name ID format**                                 | `EmailAddress`                                                                         |
| **Application username**                           | `Email`                                                                                |

*(Screenshot: Agility OKTA SAML config)*

### Step 4: Add attribute statements

Under **Attribute Statements**, add the following. Agility uses these claims to populate the user record.

| Name           | Value                      |
| -------------- | -------------------------- |
| `given_name`   | `user.profile.firstName`   |
| `family_name`  | `user.profile.lastName`    |
| `phone_number` | `user.profile.mobilePhone` |

For `given_name`, `family_name`, and `phone_number`, use Okta's expression syntax (`user.profile.firstName` etc.) rather than the older shorthand. `phone_number` is optional — only add it if you want the user's phone to be synced into Agility on sign-in.

Under **Group Attribute Statements** (optional, only needed if you use **From IdP groups** role mapping) — this section uses Okta's legacy group-claim configuration, which is still the supported path for SAML group statements:

| Name     | Name format | Filter                                                                    |
| -------- | ----------- | ------------------------------------------------------------------------- |
| `groups` | Unspecified | Matches regex `.*` (or a narrower filter for the groups you want to send) |

*(Screenshot: OKTA SAML 2)*

Click **Next**, fill out the feedback form, then **Finish**.

### Step 5: Copy Okta's SAML details back to Agility

1. In the Okta app, open the **Sign On** tab.
2. Find the **Metadata URL** (sometimes labeled "Identity Provider metadata"). Copy it.
3. Back in the Agility **Identity** page:
   - Paste the URL into **Metadata URL** and click **Import**. Agility will fetch and fill the SSO URL, Entity ID, and signing certificate automatically.
   - Or, if you prefer to fill manually, copy the **Identity Provider Single Sign-On URL**, **Identity Provider Issuer**, and **X.509 Certificate** from Okta into the corresponding fields.

*(Screenshot: AGC SAML 3)*

### Step 6: Assign users in Okta

In your Okta app, go to **Assignments** and assign the users (or groups) who should have access to Agility.

### Step 7: Test and enable

1. Back in Agility, click **Test Connection** to verify the configuration.
2. Configure your [role mapping](https://apidocs.agilitycredit.com/sso/role-mapping).
3. Toggle **Enable SSO** at the top of the page.
4. Click **Save**.

Users in the assigned Okta groups can now sign in via the **Login with SSO** button on the Agility login page.

:::caution Don't use Okta's built-in SSO test
Okta's app-level test (the **Sign On → Test** option) and the "tile launch" from a user's Okta dashboard trigger an IdP-initiated flow that Agility doesn't accept — it returns `Missing RelayState`. This is by design: Agility only allows sign-ins that start from the Agility login page (SP-initiated), which is the flow your real users will take.

To test, open the Agility login page in a private/incognito window, click **Login with SSO**, and complete the flow from there.
:::

---

## Option B — OIDC

### Step 1: Open the Identity page in Agility

1. Sign in to the Agility Credit portal as an administrator.
2. Open **Settings → Account → Identity**.
3. On the **SSO** tab, choose **OIDC** as the protocol.

Keep this page open — the **SP Metadata** panel shows the **Redirect URI** you'll paste into Okta in Step 3.

### Step 2: Create the OIDC app in Okta

1. Sign in to your Okta admin console.
2. Go to **Applications → Applications**, then click **Create App Integration**.
3. Choose **OIDC - OpenID Connect**.
4. Set **Application type** to **Web Application** and click **Next**.

*(Screenshot: OKTA OIDC 1)*

### Step 3: Configure the OIDC app

Fill in the Okta form:

| Okta field                 | Value                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **App integration name**   | `Agility Credit`                                                                                             |
| **Grant type**             | Authorization Code                                                                                           |
| **Sign-in redirect URIs**  | The **OIDC Redirect URI** from Agility (e.g. `https://sso.agilitycredit.net/auth/oidc/callback/<tenant-id>`) |
| **Sign-out redirect URIs** | Leave blank or set to your portal URL                                                                        |
| **Controlled access**      | Choose who can access the app                                                                                |

Click **Save**.

*(Screenshot: OKTA OIDC 2)*

### Step 4: Copy Okta credentials to Agility

From the Okta app's **General** tab, copy:

| Okta value                                                                                                                | Agility field     |
| ------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **Okta domain** + `/.well-known/openid-configuration` (e.g. `https://your-org.okta.com/.well-known/openid-configuration`) | **Discovery URL** |
| **Client ID**                                                                                                             | **Client ID**     |
| **Client Secret**                                                                                                         | **Client Secret** |

Click **Verify** next to the Discovery URL — Agility will fetch the document and show the resolved issuer, authorization endpoint, and token endpoint. This catches typos before you save.

*(Screenshot: OKTA OIDC 3)*

### Step 5: Assign users and test

1. In Okta, go to **Assignments** and assign users or groups.
2. In Agility, click **Test Connection**.
3. Configure your [role mapping](https://apidocs.agilitycredit.com/sso/role-mapping).
4. Toggle **Enable SSO** and click **Save**.

---

## What Okta needs to send

For both SAML and OIDC, Agility expects the following claims:

| Claim          | Required    | Notes                                                                          |
| -------------- | ----------- | ------------------------------------------------------------------------------ |
| `email`        | Yes         | Primary identifier for matching to existing Agility users                      |
| `given_name`   | Recommended | Used for the user's display name; empty if omitted                             |
| `family_name`  | Recommended | Used for the user's display name; empty if omitted                             |
| `phone_number` | Optional    | Synced into the user record on every sign-in if sent                           |
| `groups`       | Optional    | Required only if you use **From IdP groups** role mapping                      |
| `roles`        | Optional    | Required only if you use **From IdP attribute** role mapping with name `roles` |

For OIDC, Agility requests the scopes `openid email profile phone`. Okta returns `phone_number` automatically under the `phone` scope — no extra configuration needed on the Okta side.

## Next steps

- [Role mapping](https://apidocs.agilitycredit.com/sso/role-mapping) — Map Okta groups or attributes to Agility roles
- [SCIM provisioning](https://apidocs.agilitycredit.com/sso/scim-provisioning) — Auto-provision users from Okta via SCIM
- [Troubleshooting](https://apidocs.agilitycredit.com/sso/troubleshooting) — If sign-in fails after configuration

Source: https://apidocs.agilitycredit.com/sso/setup-okta