> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on

> Claim the email domains your people use, so they can sign in through your own identity provider.

export const ssoTokenLength = "32";

export const ssoSweepCadence = "every hour";

export const ssoRecheckWindow = "23 hours";

export const ssoRecheckCadence = "about once a day";

export const ssoPlans = "Business";

export const ssoLapseWindow = "14 days";

export const ssoDomainMaxLength = "233";

export const ssoChallengeValuePrefix = "vumasign-verify=";

export const ssoChallengePrefix = "_vumasign-challenge";

export const ssoAlreadyClaimed = "already claimed by another Vumasign organisation";

Single sign-on lets your people sign in to Vumasign through your organisation's own identity
provider, such as Microsoft Entra ID, Google Workspace or Okta, instead of with a password.

<Note>
  **What is available today is the first step: claiming your domains.** You can prove which email
  domains belong to your organisation now. Connecting your identity provider, and signing in through
  it, is coming next and is not available yet. Until it arrives, claiming a domain changes nothing
  about how anybody signs in.
</Note>

## Who can use it

Single sign-on comes with {ssoPlans}:

| Plan | Single sign-on |
| - | - |
| Free | No |
| Team | No |
| Business | Yes |
| API | No |

Only an **owner** or an **admin** of the organisation can set it up. The plan is checked when a
domain is **added**. A domain you already claimed keeps working if you change plan later, and you
can still verify it or remove it.

## Claim a domain

A domain claim says that addresses at a domain, such as `acme.co.za`, belong to your
organisation, because you control that domain's DNS.

1. Go to **Settings → Single sign-on** and enter the domain under **Domains**. You can paste an
   email address or a web address; only the domain is kept, in lower case.
2. Publish the TXT record the page shows at your DNS provider. It has this shape:

| Type | Host | Value |
| - | - | - |
| `TXT` | `_vumasign-challenge.acme.co.za` | `vumasign-verify=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

The host is <code>{ssoChallengePrefix}.</code> followed by your domain. The value is
<code>{ssoChallengeValuePrefix}</code> followed by a token of {ssoTokenLength} characters that
belongs to this claim alone. If you already publish a record on that host to prove a sending
domain, add this one beside it; both can exist together.

3. Press **Verify**. DNS changes can take a few hours to appear, so if the record is not found
   yet, wait and press **Verify** again.

Each claim covers **exactly one domain**. A claim on `acme.co.za` does not cover `eu.acme.co.za`;
claim each subdomain on its own. A domain can be at most {ssoDomainMaxLength} characters, so that
its record's host fits within the limit DNS sets for a name.

## One organisation per domain

A domain can be verified by **one Vumasign organisation at a time**. If another organisation has
already verified it, yours is told the domain is {ssoAlreadyClaimed}; contact support. Claiming a
domain without verifying it reserves nothing.

## Keep the record published

Every verified domain is checked again {ssoRecheckCadence}, so leave the record in place after
verifying. (The check runs {ssoSweepCadence}, and looks again at each domain once {ssoRecheckWindow}
have passed since its last check.)

* **The first time the record is missing**, the organisation's owners are emailed. The email names
  the date from which the claim will lapse.
* **If the record is still missing {ssoLapseWindow} after it was first found missing**, the claim
  **lapses**: the domain stops counting as your organisation's, and the owners are emailed again.
  Publish the record and press **Verify** to claim it back.
* **If the record comes back** before then, the claim carries on as if nothing happened.
* **A day on which your domain's DNS does not answer at all** does not count against the claim by
  itself. If it goes on for {ssoLapseWindow}, the record is treated as missing from then on.

The settings page shows when a claim was last checked, and since when its record has been missing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.