> 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, and enter your client credentials, 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**, and takes effect immediately.

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

Enter the email address of the person who administers your IdP and select **Email setup link**. To do the setup yourself, select **Open setup page myself** instead.

A setup link:

* is limited to your organization and your verified email domains;
* works once, and expires after 7 days;
* 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 same console steps in more detail, with screenshots:

* [Azure AD (OIDC)](/configuration/sso-configuration/azure-ad-oidc.md)
* [Google Workspace](/configuration/sso-configuration/google-workspace.md)
* [Okta Workforce Enterprise](/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 validates the issuer by reading its OpenID Connect discovery document, so the issuer must be reachable over HTTPS from the public internet. The client secret goes directly to the authentication service and is never stored in Silkline's database.

Select **Connect identity provider** to finish. Provisioning is immediate, and the link is used up.
{% endstep %}

{% step %}

#### Test the connection

The setup page offers a **Sign in to Silkline** button when the setup completes. Use it, or open <https://app.silkline.ai/landing> in a private browser window, and sign in with a company account on one of your registered domains. You should be handed to your IdP and returned to Silkline signed in.

Users who sign in this way 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. Completing 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

| 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. Each link works once and expires 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  | The account's email domain is outside your registered domains. Add the domain, or sign in with a covered account. |

## Auth0 connections

Some organizations have their SSO connection hosted in Auth0. Those connections appear on the **Auth0** tab of the Authentication section, and are managed through Auth0's own self-service flow rather than the setup link above.

For an Auth0 connection, the redirect URI registered in your IdP points at Auth0 rather than `auth.silkline.ai`:

| Value               | Auth0                                          |
| ------------------- | ---------------------------------------------- |
| Authentication host | `https://silkline.us.auth0.com`                |
| Redirect URI        | `https://silkline.us.auth0.com/login/callback` |

{% hint style="warning" %}
Do not register the Auth0 URLs for a new connection. New SSO setups use the URLs in [SSO Configuration](/configuration/sso-configuration.md). Contact <support@silkline.ai> if you are unsure which applies to your organization.
{% endhint %}