# Single sign-on (https://docs.capy.ai/admin/single-sign-on)

> Connect Google Workspace, Okta, Microsoft Entra ID, or any SAML 2.0 identity provider so members on your domain sign in to Capy through it.

Single sign-on sends everyone with an email address on your domain to your company's identity provider when they sign in to Capy. Admins set it up in [Settings → Org → Identity & access](https://capy.ai/settings/org/identity), with no need to contact Capy.

## Before you start [#requirements]

| Requirement | Details |
| --- | --- |
| Role | You're an admin or owner of the organization. |
| Plan | A Lite, Pro, or Max plan, and the single sign-on add-on at \$100 a month. Enterprise plans include single sign-on. |
| Domain | A domain that your organization verified with DNS. See [Verify your domain](#verify-your-domain). |
| Identity provider | You can create an app in your identity provider, or you work with someone who can. |
| Google Workspace OAuth only | Your Capy account has a passkey or an authenticator app. |

Your organization has one single sign-on connection at a time, and the connection covers one domain.

## Verify your domain [#verify-your-domain]

Capy turns on single sign-on only for a domain that your organization proves it owns with a DNS record. Only one organization can verify a domain with DNS.

<Steps>
  <Step title="Add the domain">Under **Domains**, choose **Add domain** and enter the domain, for example `example.com`.</Step>
  <Step title="Get the DNS record">Choose **Verify with DNS** on the domain, then **Get DNS record**.</Step>
  <Step title="Add the TXT record">At your DNS provider, add a `TXT` record with the host `_capy-verification.example.com` and the value that Capy shows. The value starts with `capy-domain-verification=`.</Step>
  <Step title="Verify">Choose **Verify**. If your DNS provider hasn't published the record yet, wait and choose **Verify** again.</Step>
</Steps>

Keep the TXT record after verification. Capy checks it every day. If the record is missing for 7 days, Capy removes the verification and pauses single sign-on for the domain.

## Google Workspace OAuth or Google Workspace SAML [#google]

If your company uses Google Workspace, you can connect it in two ways. **Google Workspace OAuth** connects in one click, with nothing to set up in Google. It uses OpenID Connect, which is built on OAuth 2.0. **Google Workspace SAML** uses a SAML app that your Google admin creates in the Google Admin console.

| | Google Workspace OAuth | Google Workspace SAML |
| --- | --- | --- |
| Setup in Google | ✓ None | A custom SAML app in the Google Admin console |
| Who can sign in | Everyone with an account on the domain | ✓ Only people the app is turned on for |
| Removing access | Suspend or delete the user in Google | ✓ Turn off the app for the user, or suspend or delete the user |
| First and last name | ✓ From the Google account | ✓ From the attributes that you map |
| Require single sign-on | ✓ | ✓ |

Choose Google Workspace SAML when your Google admin wants to control who can sign in to Capy.

## Set up single sign-on [#set-up]

<Steps>
  <Step title="Open single sign-on">In [Settings → Org → Identity & access](https://capy.ai/settings/org/identity), find **Single sign-on** and choose **Set up**.</Step>
  <Step title="Add single sign-on to your plan">If your plan doesn't include single sign-on, Capy shows the amount due today and \$100 a month after that. Add it to continue. The add-on renews with your plan until you cancel it in [Billing](/admin/billing).</Step>
  <Step title="Pick your provider">Choose your identity provider, then choose **Continue**.</Step>
</Steps>

<Screenshot name="sso-picker" alt="The Set up single sign-on dialog with Google Workspace OAuth, Google Workspace SAML, Okta, Microsoft Entra ID, and other providers" caption="Pick the identity provider your company signs in with." />

If you picked **Google Workspace OAuth**, Capy connects the domain to Google. The connection shows **Connecting** and then **Active**.

If you picked a SAML provider, Capy opens a setup sheet:

<Steps>
  <Step title="Choose the domain">Under **Domain**, choose the verified domain. Everyone with an address on this domain signs in through your provider.</Step>
  <Step title="Add Capy to your provider">Create an app in your provider and copy Capy's values into it. Each value has a copy button. The [provider guides](#provider-guides) say where each value goes.</Step>
  <Step title="Connect your provider to Capy">Give Capy your provider's details. Most providers support **Metadata URL**. You can also choose **Paste values** and enter the sign-in URL, the entity ID, and the certificate.</Step>
  <Step title="Save and turn on">Choose **Save and turn on**. Capy checks the values and shows an error next to a field that is wrong. See [Troubleshooting](#troubleshooting).</Step>
  <Step title="Confirm">Read the dialog, then choose **Turn on**.</Step>
  <Step title="Do a test sign-in">Open the Identity & access page in a private browser window. Sign in with an email address on your domain, through your provider. **Copy link** on the connection copies the page link.</Step>
</Steps>

<Screenshot name="sso-saml-setup" alt="The Set up Okta sheet with the domain, the values to copy into Okta, and the metadata URL field" caption="Copy Capy's values into your provider, then give Capy your provider's metadata URL." />

If you close the sheet before you save, the connection stays as a **Draft**. Choose **Continue** on the connection to finish it.

The connection shows **Waiting for a test sign-in** until someone signs in through it. After that, it shows **Active** and the date of the test.

<Screenshot name="sso-saml-on" alt="Identity and access settings with an active Okta SAML connection and the Require single sign-on switch" caption="An active connection shows the date of its test sign-in." />

## Provider guides [#provider-guides]

Each guide says where to create the app and where each value from Capy goes. In every provider, assign the app to the people or groups who use Capy. People who aren't assigned can't sign in to Capy.

Capy matches each person to their Capy account by email address. To fill in first and last names, send the `firstName` and `lastName` attributes.

### Google Workspace SAML [#google-workspace-saml]

1. In the Google Admin console, open **Apps → Web and mobile apps → Add custom SAML app**.
2. On the **Google Identity Provider details** step, copy the **SSO URL**, **Entity ID**, and **Certificate**. You can choose **Download metadata** instead.
3. On the **Service provider details** step, paste Capy's **ACS URL** and **Entity ID**. Set **Name ID format** to `EMAIL` and **Name ID** to **Basic Information → Primary email**.
4. On the **Attributes** step, map **First name** to `firstName` and **Last name** to `lastName`.
5. Under **User access**, turn the app on for the people or groups who use Capy.
6. In Capy, choose **Paste values** and enter the SSO URL, entity ID, and certificate. You can choose **Metadata file** and upload `GoogleIDPMetadata.xml` instead.

### Okta [#okta]

1. In Okta, open **Applications → Create App Integration → SAML 2.0**.
2. On the **Configure SAML** step, paste Capy's **Single sign-on URL** and **Audience URI (SP Entity ID)**. Set **Name ID format** to `EmailAddress` and **Application username** to `Email`.
3. Under **Attribute Statements**, add `email`, `firstName`, and `lastName`.
4. On the **Assignments** tab, assign the app to people or groups.
5. In Capy, choose **Metadata URL** and paste the metadata URL from the app's **Sign On** tab. You can choose **Paste values** instead and enter the **Identity Provider Single Sign-On URL**, **Identity Provider Issuer**, and **X.509 Certificate**.

### Microsoft Entra ID [#microsoft-entra-id]

1. In Entra, open **Enterprise applications → New application → Create your own application**, then **Single sign-on → SAML**.
2. Under **Basic SAML Configuration**, paste Capy's **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)**.
3. Under **Attributes & Claims**, check that the email address, given name, and surname claims are present. Entra adds them by default.
4. Under **Users and groups**, assign people or groups.
5. In Capy, choose **Metadata URL** and paste the **App Federation Metadata Url** from **SAML Certificates**. You can choose **Paste values** instead and enter the **Login URL**, **Microsoft Entra Identifier**, and **Certificate (Base64)**.

### JumpCloud [#jumpcloud]

1. In JumpCloud, open **SSO Applications → Add New Application → Custom SAML App**.
2. On the **SSO** tab, paste Capy's **ACS URLs** and **SP Entity ID**. Set **SAMLSubject NameID** to `email`.
3. Add the attributes `email`, `firstName`, and `lastName`.
4. Give the user groups that use Capy access to the app.
5. In Capy, choose **Paste values** and enter the **IDP URL**, **IdP Entity ID**, and **IDP Certificate** from the app's **SSO** tab.

### OneLogin [#onelogin]

1. In OneLogin, add the **SAML Custom Connector (Advanced)** app.
2. On the **Configuration** tab, paste Capy's **Audience (EntityID)**, **ACS (Consumer) URL**, and **ACS (Consumer) URL Validator**.
3. Add the parameters `email`, `firstName`, and `lastName`.
4. Assign the app to the people who use Capy.
5. In Capy, choose **Metadata URL** and paste the **Issuer URL** from the **SSO** tab. You can choose **Paste values** instead and enter the **SAML 2.0 Endpoint (HTTP)**, **Issuer URL**, and **X.509 Certificate**.

### Keycloak [#keycloak]

1. In Keycloak, create a SAML client in your realm.
2. Paste Capy's entity ID as the **Client ID** and Capy's ACS URL in **Valid redirect URIs**. Set **Name ID format** to `email`.
3. Add mappers for `email`, `firstName`, and `lastName`.
4. In Capy, choose **Metadata URL** and paste the **SAML 2.0 Identity Provider Metadata** URL from **Realm settings → Endpoints**. You can choose **Paste values** instead and enter the SSO URL, the **Realm entity ID**, and the **Realm RS256 certificate** from **Realm settings → Keys**.

### Auth0 [#auth0]

1. In Auth0, create a Regular Web Application and turn on the **SAML2 Web App** add-on.
2. Paste Capy's ACS URL as the **Application Callback URL**.
3. In the add-on settings, map `email`, `firstName`, and `lastName`.
4. In Capy, choose **Metadata URL** and paste the **Identity Provider Metadata** URL from the add-on's **Usage** tab. You can choose **Paste values** instead and enter the **Identity Provider Login URL**, **Issuer**, and **Identity Provider Certificate**.

### Other SAML provider [#other-saml-provider]

Capy works with any SAML 2.0 identity provider.

1. In your provider, create a SAML app with Capy's **ACS URL** and **SP entity ID**. Some providers accept Capy's **SP metadata URL** instead.
2. Send the email address as the Name ID, and add the attributes `email`, `firstName`, and `lastName`.
3. In Capy, choose **Metadata URL** and paste the **IdP metadata URL**. You can choose **Paste values** instead and enter the **SSO URL**, **IdP entity ID**, and **X.509 certificate**.

## What members experience [#members]

When single sign-on is on, everyone with an email address on the domain signs in to Capy through your provider. This applies in every organization, so it includes people on the domain who aren't in your organization.

- People who are already signed in stay signed in. They use your provider at their next sign-in.
- A member's first sign-in through your provider opens their existing Capy account. Their threads, memberships, and settings stay.
- Capy counts a sign-in through your provider as two-step verification. Turn on MFA in your provider.
- People on the domain can't sign in to the Capy mobile apps. They sign in at capy.ai or in the desktop app.

## Require single sign-on [#require]

Until you require single sign-on, members on the domain can still sign in another way, for example with a password. After you turn on **Require single sign-on**, members whose email address is on the domain can use your organization only after they sign in through your provider.

You can turn on **Require single sign-on** when all of these are true:

- The connection is active.
- Someone signed in through the connection after its provider details last changed. The test sign-in from setup counts.
- The domain is verified with DNS.

**Require single sign-on** applies only while the connection is active. While Capy pauses the connection, members can sign in the way they did before.

<Warning>If your provider stops working while single sign-on is required, members on the domain can't use your organization. Keep at least one admin whose email address isn't on the domain, so that someone can turn off **Require single sign-on**. If nobody can, email [support@capy.ai](mailto:support@capy.ai).</Warning>

## Manage the connection [#manage]

Open the menu on the connection to change it.

| Action | Result |
| --- | --- |
| **Edit** | Changes your provider's details. Capy uses the new values from the next sign-in. If the sign-in URL, entity ID, or certificates change, the connection waits for a new test sign-in. Turn off **Require single sign-on** first. |
| **Add certificate** | Adds a certificate before your provider rotates its signing key. Capy trusts the old and the new certificate, so sign-ins keep working when your provider switches. A connection trusts up to 5 certificates. |
| **Turn off** | Stops single sign-on and keeps the connection's settings. Members sign in the way they did before. Turn off **Require single sign-on** first. |
| **Turn on** | Starts single sign-on again after **Turn off**. |
| **Remove** | Deletes the connection. Members sign in the way they did before, and their accounts and memberships stay. Turn off **Require single sign-on** first. |

To disconnect **Google Workspace OAuth**, choose **Disconnect** in its menu. Members go back to signing in with a password, a Google account, or an email code.

Capy pauses a connection in these cases:

- The domain loses its DNS verification.
- The single sign-on add-on ends. To end it, choose **Cancel single sign-on** in [Billing](/admin/billing). Single sign-on stays active until the end of the billing cycle.

A paused connection starts again when the domain is verified and the add-on is active.

## Switch providers [#switch]

To move to a different provider, for example from **Google Workspace OAuth** to **Google Workspace SAML**:

1. If **Require single sign-on** is on, turn it off.
2. Remove or disconnect the current connection. Members on the domain sign in the way they did before.
3. Set up the new provider and do a test sign-in.
4. Turn on **Require single sign-on** again.

Members keep their Capy accounts. Their next sign-in through the new provider opens the same account.

## Troubleshooting [#troubleshooting]

<AccordionGroup>
  <Accordion title="Could not read the metadata at this URL">Capy couldn't download metadata from the URL. Check that the app is assigned to at least one person, and that you copied the metadata URL, not the sign-in URL. If your provider shows the metadata only to signed-in users, choose **Paste values** instead.</Accordion>
  <Accordion title="Enter a URL that starts with https://">Capy accepts only `https://` URLs.</Accordion>
  <Accordion title="This is not SAML identity provider metadata">The URL or the file doesn't contain identity provider metadata. Copy the identity provider's metadata URL, not the service provider's, or download the identity provider metadata file.</Accordion>
  <Accordion title="Enter the identity provider's entity ID">The entity ID field is empty. Your provider can call it the issuer, the IdP entity ID, or the identifier.</Accordion>
  <Accordion title="This is not an X.509 certificate">Paste the whole certificate, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.</Accordion>
  <Accordion title="This metadata has no signing certificate">The metadata doesn't include the certificate that signs sign-ins. Check the app's signing certificate in your provider, or choose **Paste values** and paste the certificate.</Accordion>
  <Accordion title="This certificate expired">The certificate is past its expiry date. Create a new certificate in your provider and paste it.</Accordion>
  <Accordion title="Clerk did not accept these values">Capy's sign-in service rejected the values. Compare each value with your provider, then try again.</Accordion>
  <Accordion title="The test sign-in fails">Check that the app is assigned to you in your provider and that your email address is on the domain. An email address outside the domain can't sign in through the connection.</Accordion>
  <Accordion title="Set up is turned off">Your organization has no domain verified with DNS. [Verify your domain](#verify-your-domain) first.</Accordion>
</AccordionGroup>
