> 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/self-service-sso.md).

# Self-service SSO setup

Connect your identity provider to Silkline with a setup link — pick your provider, register the redirect URI, enter your client credentials, and test a sign-in, with no Silkline account needed

## Overview

**Time to complete:** about 10 minutes

**What this does:** Connects your identity provider (IdP) to Silkline so your users sign in with their company accounts. Setup happens on a dedicated page opened from a **setup link**, takes effect immediately, and ends with a test sign-in on the same page.

**Who can do this:** an organization admin with permission to manage SSO issues the link. Whoever administers your IdP completes the setup — they do not need a Silkline account, so you can hand the link to your IT team as it is.

**Supported identity providers:** Microsoft Entra ID (Azure AD), Okta Workforce, Google Workspace, and any other provider that supports OpenID Connect.

## Before you start

* Your organization's email domains must be registered and verified with Silkline. The SSO settings page tells you if they are not — contact <support@silkline.ai> to have them added.
* Whoever completes the setup needs admin access to your IdP so they can create an application and read its client secret.

## Steps

{% stepper %}
{% step %}

#### Issue a setup link

Go to **Settings → Single sign-on**, or open **Settings → Users and Access**, scroll to the **Authentication** section, and select the **Keycloak** tab.

Select **Generate setup link**, copy the displayed link, and share it securely with the person who administers your IdP. Open the link yourself if you are completing the setup. The full link is shown only when it is generated.

A setup link:

* is limited to your organization and your verified email domains;
* works until you select **Done** on the setup page, it is revoked, or 7 days pass;
* can be submitted again to replace the connection it created;
* can be revoked at any time from the **Outstanding setup links** list.

Silkline support can also issue a link on your behalf.
{% endstep %}

{% step %}

#### Choose your identity provider

The link opens a setup page on Silkline's authentication service. Select Microsoft Entra ID, Okta Workforce, Google Workspace, or **Other (generic OpenID Connect)**.

The page then lists the steps to perform in that provider's admin console, with your organization's redirect URI already filled in.
{% endstep %}

{% step %}

#### Create the application in your IdP

Follow the on-screen steps to create an OIDC web application, and register Silkline's redirect URI on it. The redirect URI has this shape:

```
https://auth.silkline.ai/realms/silkline/broker/<org-id>/endpoint
```

Copy the exact value shown on the setup page rather than typing it — `<org-id>` is specific to your organization, and a mismatch causes the IdP to reject the sign-in.

{% hint style="info" %}
On the Silkline test / Gov environment the host is `dev-auth-gov.silkline.ai` instead of `auth.silkline.ai`. The setup page always shows the right one for the environment you are in.
{% endhint %}

The provider-specific guides cover the console steps in more detail:

* [Azure AD (OIDC)](https://docs.silkline.ai/configuration/sso-configuration/azure-ad-oidc.md)
* [Google Workspace](https://docs.silkline.ai/configuration/sso-configuration/google-workspace.md)
* [Okta Workforce Enterprise](https://docs.silkline.ai/configuration/sso-configuration/okta-workforce-enterprise.md)
  {% endstep %}

{% step %}

#### Enter your credentials

Back on the setup page, paste in the values your IdP produced:

| Provider               | Values required                            |
| ---------------------- | ------------------------------------------ |
| Microsoft Entra ID     | Issuer URL, Client ID, Client secret       |
| Okta Workforce         | Okta issuer URL, Client ID, Client secret  |
| Google Workspace       | Client ID, Client secret, Workspace domain |
| Generic OpenID Connect | Issuer URL, Client ID, Client secret       |

The authentication service reads the issuer's OpenID Connect discovery document and checks for explicit rejection of the client credentials. The issuer must be reachable over public HTTPS on port 443. Enter the issuer itself, without the `/.well-known/openid-configuration` suffix. The client secret goes directly to the authentication service and is stored in its connection configuration.

Select **Connect identity provider**. The connection is live immediately, and the setup page moves on to testing it.

Setup does not prove that a user is assigned to the IdP application, can satisfy its sign-in policies, or receives the required email claim. The test in the next step does.
{% endstep %}

{% step %}

#### Test the connection on the setup page

Select **Test sign-in**. Silkline's sign-in page opens in a new tab. Sign in with your own company account on one of the listed domains; you are handed to your IdP and returned to Silkline. A private browser window avoids reusing an existing Silkline session.

Keep the setup page open. It checks for the result every few seconds and shows one of:

| What the setup page shows                     | Meaning                                                                                                                                                                           |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No sign-in through this connection yet**    | No test has reached Silkline. After 90 seconds the page suggests checking your IdP application.                                                                                   |
| **Verified:** *email* **signed in at** *time* | The connection works end to end.                                                                                                                                                  |
| **Sign-in in progress**                       | Your IdP returned to Silkline and the sign-in is still finishing.                                                                                                                 |
| An error message                              | The sign-in failed. The message says what to fix; see [Troubleshooting SSO](https://docs.silkline.ai/configuration/sso-configuration/troubleshooting.md#setup-page-test-results). |

If the test fails because of the connection, select **Fix the connection**. The page returns to the credentials form with your values filled in. Submitting it again replaces the connection, and you can test again.

When the test is verified, select **Done**. Done ends the setup link; the connection stays as configured. **Finish without testing** does the same without a verified test.

Users who sign in through the connection are created in Silkline automatically on first sign-in. See [Users and Access](https://docs.silkline.ai/for-customers/profile-and-settings/organization-settings/organization-users) for how SSO changes user management.
{% endstep %}
{% endstepper %}

## After setup

* The SSO settings page shows the active connection and the domains it covers.
* To change a connection's client ID, secret, or issuer, issue a new setup link. Submitting it replaces the current connection.
* Access is controlled in your IdP from this point on. Removing a user's access to the Silkline application in your IdP blocks their sign-in; marking them inactive in Silkline only hides them from selections.

## Troubleshooting

See [Troubleshooting SSO](https://docs.silkline.ai/configuration/sso-configuration/troubleshooting.md) for setup messages, Entra error codes, Okta and Google errors, missing email claims, and the evidence to send support.

| What you see                                           | What to do                                                                                                                                                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "No verified SSO email domains"                        | Ask Silkline support to register and verify your email domains.                                                                                                                             |
| The setup link reports it is invalid, used, or expired | Issue a new link from the SSO settings page. A link ends when **Done** is selected, when it is revoked, or after 7 days.                                                                    |
| The issuer is rejected as unreachable or invalid       | Confirm the issuer serves `<issuer>/.well-known/openid-configuration` over public HTTPS on the default port.                                                                                |
| Your IdP reports a redirect URI mismatch               | Re-copy the redirect URI from the setup page into your IdP application.                                                                                                                     |
| Sign-in is refused after authenticating with your IdP  | While the setup link is open, **Test sign-in** on its setup page names a missing email claim or an email outside the verified domains. Otherwise ask support, with the time of the attempt. |
