> For the complete documentation index, see [llms.txt](https://docs.silkline.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkline.ai/configuration/sso-configuration/okta-workforce-enterprise.md).

# Okta Workforce Enterprise

Configure SSO with Okta Workforce Identity Cloud as the OIDC identity provider so users can sign in to Silkline with Okta credentials

## Overview

**Time to complete:** about 10 minutes

This document outlines the process for configuring Single Sign-On (SSO) to Silkline using your Okta Workforce Identity Cloud account. This setup allows your users to log in to Silkline with their Okta credentials, with Okta acting as the identity provider (IdP).

## Steps

Create and configure an OIDC Web application in Okta, connect it through the Silkline setup page, and test sign-in.

{% hint style="info" %}
Start with a setup link from **Settings → Single sign-on**. Open the link, choose **Okta Workforce**, and use the callback shown on its setup page. Your organization admin can share the link with your IdP administrator. See [Self-service SSO setup](https://docs.silkline.ai/configuration/sso-configuration/self-service-sso.md).
{% endhint %}

### **1. Create a New App Integration in Okta**

First, you will need to log in to your Okta administrator dashboard to begin.

1. Navigate to the **Applications** section and select **Applications**.
2. Click on **Create App Integration**.
3. For the sign-in method, choose **OIDC - OpenID Connect**.
4. For the application type, select **Web Application** and proceed by clicking **Next**.

### **2. Configure the Application**

On the application settings page, you will need to input the following details:

| Field                     | Description                                                                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **App integration name**  | Enter a descriptive name, such as Silkline.                                                                                                                                  |
| **Sign-in redirect URIs** | `https://auth.silkline.ai/realms/silkline/broker/<org-id>/endpoint` (production) or `https://dev-auth-gov.silkline.ai/realms/silkline/broker/<org-id>/endpoint` (test / Gov) |
| **Assignments**           | Assign only the intended users or groups to this application. Group membership alone does not grant access unless that group is assigned to this app.                        |

Use an Okta-generated client ID, **Authorization Code**, and **Client secret** authentication for this confidential Web app. The Client Credentials grant and Okta API scopes are not required for user sign-in.

After filling in the necessary information, click **Save** to create the application.

{% hint style="info" %}
`<org-id>` is specific to your organization. Generate a setup link in **Settings → Single sign-on**, then copy the full sign-in redirect URI from its setup page.
{% endhint %}

Trusted Origins are not required for Silkline's server-side redirect flow. See Okta's [OIDC application wizard](https://help.okta.com/en-us/Content/topics/apps/apps_app_integration_wizard_oidc.htm).

### **3. Gather Application Credentials**

Once the application is created, you will be taken to its general settings page. You will need to record the following information from the **General** tab:

* **Client ID**
* **Client Secret**: use the copy control for an active secret; do not copy the masked display.

Keep the secret in a password manager or enter it directly in the setup form. Do not include it in screenshots, logs, or support messages.

Also identify the authorization server whose issuer the connection uses:

| Authorization server | Issuer example                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------ |
| Organization server  | `https://example.okta.com`                                                                 |
| Custom server        | `https://example.okta.com/oauth2/default` or `https://example.okta.com/oauth2/<server-id>` |

Copy the selected server's exact issuer. Preserve its `/oauth2/...` path and omit `/.well-known/openid-configuration`. The Workflows site, Admin Console, and application launch URL are not OIDC issuers. See Okta's [authorization server guide](https://developer.okta.com/docs/concepts/auth-servers/).

If the Okta option rejects a regional or branded tenant hostname, contact Silkline support. The form currently recognizes `.okta.com`, `.okta-gov.com`, and `.oktapreview.com`; a hostname rejection does not establish that the provider's issuer is invalid.

### **4. Connect the Identity Provider**

Return to the setup page and enter the Okta issuer URL, Client ID, and Client Secret. Select **Connect identity provider**, then test sign-in.

### **5. Test SSO Configuration**

1. Access the [Silkline application](https://app.silkline.ai/landing)
2. Sign in with an active user assigned to this OIDC application. Complete the required passkey, MFA, and consent steps. Do not weaken the app's sign-on policy to avoid a challenge.
3. Confirm that the dashboard opens with the intended account and organization. For callback, assignment, issuer, or email-claim errors, see [Troubleshooting](#troubleshooting).

A connected setup page does not prove that the Client ID, user assignment, sign-on policy, callback, and email claim all work together. Complete the real sign-in test. In particular, an unknown Okta Client ID can currently pass the setup preflight and fail during sign-in.

For a failure, open **Reports → System Log** in Okta and inspect the matching application and transaction around the test time. Preserve the full error and request/transaction ID. Confirm the source profile has a populated email and that the broker receives an email on one of the domains shown in Silkline SSO settings; an email-shaped Okta username is not sufficient.

## Troubleshooting

For setup-link, browser-session, and shared account/domain errors, see [shared SSO troubleshooting](https://docs.silkline.ai/configuration/sso-configuration/troubleshooting.md).

Use the full `error_description` and matching **Reports → System Log** event. An OAuth error code, an Okta API response, and a System Log reason can use different names for the same attempt.

| Error or symptom                                                                                              | Check and common solution                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied` with `User is not assigned to the client application`                                         | Assign the intended active user or group to the exact OIDC app. Membership in a group is sufficient only when that group is assigned to this app. Retry from Silkline after the assignment is saved.                                                                                           |
| `access_denied` without that assignment message                                                               | Inspect the System Log transaction for assignment, user/app status, consent, or sign-on policy denial. This broad code does not identify the cause by itself.                                                                                                                                  |
| `invalid_client` / `The client secret supplied for a confidential client is invalid`                          | Check the Client ID and active secret from the same Web app, using the secret copy control. Confirm secret-based client authentication is configured. A log reason such as `invalid_client_secret` is supporting evidence, not a separate OAuth error code.                                    |
| `Invalid value for 'client_id' parameter`                                                                     | Recopy the Client ID from the intended OIDC app and confirm the issuer belongs to the same tenant. Okta can return this as `errorCode: invalid_client`; the setup preflight can currently miss that response and display connected. A real sign-in is required.                                |
| `invalid_scope`                                                                                               | Identify whether this came from the setup-only credential probe or the user sign-in. For sign-in, inspect the selected authorization server and the actual requested `openid profile email` scopes. Do not grant Okta API permissions or enable machine-to-machine access as a general remedy. |
| `invalid_request` with `The 'redirect_uri' parameter must be a Login redirect URI in the client app settings` | Compare the requested callback with this app's **Sign-in redirect URIs**. Copy the exact URL from the Silkline setup page; do not put it under Trusted Origins.                                                                                                                                |
| `invalid_request`, `unauthorized_client`, or another redirect URI error                                       | Inspect the full description. Confirm an OIDC **Web Application** with Authorization Code enabled and compare the actual `redirect_uri` with **Sign-in redirect URIs**, including the entire path and trailing slash. Generic codes alone do not prove a callback mismatch.                    |
| `issuer discovery returned HTTP 404` with a Workflows or Admin Console URL                                    | Use the selected authorization server's issuer, not the Workflows site, `-admin` hostname, app launch URL, or metadata-document URL.                                                                                                                                                           |
| `Expected an Okta domain such as https://your-company.okta.com` with a regional or branded issuer             | Contact support to review the issuer. The Okta option recognizes `.okta.com`, `.okta-gov.com`, and `.oktapreview.com`; documented EMEA and other tenant domains can be rejected by this form. Do not change a valid issuer just to satisfy the host check.                                     |
| Issuer or discovery mismatch                                                                                  | Match the setup issuer, discovery `issuer`, and token issuer to the same server. The organization issuer is the root tenant URL; a custom server includes `/oauth2/<server-id>`. Preserve that path when it is the selected issuer.                                                            |
| `login_required`                                                                                              | Start an interactive login from Silkline. `login_required` can occur when an authorization request requires an existing Okta session but none is available; it does not establish a setup-credential failure.                                                                                  |
| A passkey, MFA, enrollment, or consent screen appears                                                         | Complete the tenant's required verification. Assignment does not bypass sign-on policy. Ask the Okta admin to inspect a repeated challenge or denial; do not disable the policy to finish setup.                                                                                               |
| Okta authenticates the user but Silkline rejects the email                                                    | Check the user's populated profile email and the selected server's email scope/claim configuration. Verify the returned email domain against Silkline's verified domains. A username or requested scope alone does not prove an email was returned.                                            |

Both the organization server (`https://example.okta.com`) and a custom server (`https://example.okta.com/oauth2/default`) can support OIDC SSO. Selecting a different issuer changes the server and its policies; it is not just a URL format correction. See Okta's [authorization servers](https://developer.okta.com/docs/concepts/auth-servers/) and [tenant domain guidance](https://developer.okta.com/docs/guides/find-your-domain/).

Silkline's setup preflight separately makes a `client_credentials` request without an Okta scope. It detects selected explicit credential errors; it does not complete user authentication. Okta's machine-to-machine grant has different scope and authentication requirements from OIDC user sign-in. See Okta's [Client Credentials grant](https://developer.okta.com/docs/guides/implement-grant-type/clientcreds/main/).

Trusted Origins are not the app's callback allowlist and are not required for Silkline's server-side OIDC redirect flow. Use the app's **Sign-in redirect URIs**. Provider references: [OIDC app configuration](https://developer.okta.com/docs/guides/build-sso-integration/openidconnect/main/), [OAuth errors](https://developer.okta.com/docs/reference/error-codes/), [System Log queries](https://developer.okta.com/docs/reference/system-log-query/), and [Trusted Origins](https://help.okta.com/en-us/Content/topics/security/api-trusted-origins.htm).
