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

# Enterprise SSO (SAML)

Let your team sign in to Duro with your company's identity provider — Google Workspace, Microsoft Entra ID, Okta, JumpCloud, or any SAML 2.0 IdP.

Setup is self-serve and takes about twenty minutes. It happens on one screen in Duro, plus one visit to your IdP console and one DNS record. No ticket to Duro, no waiting on anyone.

**Where this lives:**

```
https://durohub.com/org/@<your-org-slug>/settings/authentication/saml
```

That is the address for organizations on `durohub.com`. On a dedicated instance or another region, use the host you sign in at — `https://acme.durohub.com/org/@<your-org-slug>/settings/authentication/saml`, for example.

Or navigate there: **Organization settings → Authentication → SAML single sign-on**. The page is directly linkable, so if the person who administers your IdP is not you, send them the URL.

## What your members will see

Once this is on, someone signing in types their email address, Duro recognizes the domain, and the form offers **Continue with SSO** instead of asking for a password.

```
  dana@acme.com typed on the Duro sign-in page
        │
        ▼
  Duro recognizes acme.com as your verified domain
        │
        ▼
  "Continue with SSO"  ─────────►  your identity provider
        │                                   │
        │                          user authenticates
        ▼                                   │
  signed assertion posted back to Duro ◄────┘
        │
        ▼
  session issued, browser lands in Duro
```

Duro is the Service Provider, and your IdP asserts directly to Duro. Each organization gets its own Entity ID and Reply URL, so an assertion minted for your organization cannot be used against another.

### Where a failed sign-in lands

SSO can be started from more than one place — the sign-in module embedded on `https://durohub.com/`, the `/login` page, or a link that sent someone to either. Duro remembers which page started the flow and returns the person there if the assertion is rejected, with the error code in the URL, so they see the failure in the form they were already using rather than on a page they never visited.

That memory is a short-lived cookie set when the flow starts. Because your IdP posts the assertion back cross-site, the cookie is issued with `SameSite=None; Secure`, which is what allows it to survive the round trip. A browser configured to block cross-site cookies entirely drops it — the sign-in still fails with the same error code, it just lands on the default sign-in page instead of the one the user started from.

Nothing about this is configurable, and it changes nothing in your IdP. It only affects where the user ends up when something is wrong; the error codes themselves are unchanged and are listed under [Troubleshooting](#troubleshooting).

## Before you start

|                             |                                                                                                                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Duro role**               | A role with the `organization.saml.configure` permission — Site Admin or Admin by default                                                                                         |
| **Plan**                    | Must include the `SSO_SAML` entitlement. Without it the page loads, but the first action fails: **Get DNS record** in Step 1 returns an error, and so does saving the IdP details |
| **IdP access**              | Administrator access to your identity provider                                                                                                                                    |
| **DNS access**              | Ability to add a TXT record to your email domain                                                                                                                                  |
| **A way in that isn't SSO** | Sign in with a password or Google to do this setup                                                                                                                                |

## The page unlocks in order

Worth knowing before you open it. The SAML page has an **Enable SAML single sign-on** switch at the top, then three cards: **Verify your domain**, **Identity provider**, and **Give these to your identity provider**. Things unlock in this order:

```
  1. Verify your domain              (card)   ← start here
        ↓
  2. Identity provider fields        (card)   ← "Verify your domain first" until step 1 passes
        ↓
  3. Enable SAML single sign-on      (switch) ← reads "Complete the steps below first"
        ↓                                       until an SSO URL is saved
  4. Create accounts automatically   (switch in the Identity provider card)
                                              ← disabled until SAML is enabled
```

The **Give these to your identity provider** card holds Duro's own values and is there from the start.

So expect to open the **Identity provider** card twice: once to save your IdP details, and again after you switch SAML on if you want automatic account creation.

## Step 1 — Verify your domain

SAML cannot be enabled until you have proven you control the email domain your users sign in with. Your IdP can assert any address it likes; this is what limits it to addresses that are yours.

1. Under **Verify your domain**, type your domain — `acme.com`, no scheme or path — and click **Get DNS record**
2. Duro shows a **Record name** and a **Value**, each with a copy button
3. Add the TXT record at your DNS provider
4. Click **I have added the record**

On success the input disappears and a green tag with your domain appears beside the heading. That tag is how you know the rest of the page is live.

### The DNS record

|                 |                                                                                                                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Type**        | `TXT`                                                                                                                                                                                                                                      |
| **Name / Host** | Duro's **Record name** shows the full name, `_duro-verification.acme.com`. Most DNS providers append your domain to whatever you enter — if yours does, enter only `_duro-verification`, or you get `_duro-verification.acme.com.acme.com` |
| **Value**       | `duro-domain-verification=k3Jd9vQ2…` — the whole string, including the prefix                                                                                                                                                              |

The token is unique to your organization. DNS changes usually take minutes and sometimes an hour, so click **I have added the record** again rather than assuming failure. Once verified, the record can be removed; verification does not re-run.

{% hint style="info" %}
**One domain, matched exactly.** Duro stores a single verified domain per organization, and the sign-in page routes an address to SSO only when the part after the `@` matches it exactly. With `acme.com` verified, `dana@mail.acme.com` gets the password form, not **Continue with SSO**. Verify the domain your users' addresses actually end in.
{% endhint %}

### If the domain is refused

| What Duro says                                                                     | What it means                                                                                               |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| *That is a public email provider. Use a domain your organization controls.*        | Consumer mail domains — `gmail.com`, `outlook.com`, `icloud.com` and the like — cannot be claimed by anyone |
| *Another organization has already verified that domain.*                           | Contact Duro support                                                                                        |
| *We could not find the TXT record yet. DNS changes can take a while to propagate.* | Not propagated, or the name or value does not match. Confirm with `dig TXT _duro-verification.acme.com`     |
| *We could not reach DNS to check that record. Try again shortly.*                  | A lookup failure on our side, not a wrong record                                                            |
| *That does not look like a valid domain.*                                          | Use a bare hostname — no scheme, path, port, or wildcard                                                    |

## Step 2 — Copy the two values Duro gives you

{% hint style="info" %}
**Five values change hands, and they travel in opposite directions.** Getting this backwards is the most common reason a setup stalls, because most IdP consoles put both sides on one screen without saying which is which.

|                | Direction           | Values                                           |
| -------------- | ------------------- | ------------------------------------------------ |
| **Step 2 → 3** | Duro **→** your IdP | Entity ID, Reply URL (ACS)                       |
| **Step 3 → 4** | your IdP **→** Duro | SSO URL, Issuer (Entity ID), signing certificate |

Both sides have something called an *Entity ID*. They are different values: Duro's names Duro; your IdP's names your IdP. Your IdP needs Duro's. Duro's **Issuer (Entity ID)** field for your IdP's is optional, but recommended — when it is set, Duro checks every assertion's issuer against it exactly.
{% endhint %}

At the bottom of the page, under **Give these to your identity provider**, are two values with copy buttons:

| Duro shows                                                         | Your IdP may call it                                  |
| ------------------------------------------------------------------ | ----------------------------------------------------- |
| **Entity ID** — `https://api.durohub.com/auth/saml/acme/metadata`  | Entity ID, Identifier, Audience URI, or SP Entity ID  |
| **Reply URL (ACS)** — `https://api.durohub.com/auth/saml/acme/acs` | ACS URL, Reply URL, or Assertion Consumer Service URL |

{% hint style="success" %}
**Skip the transcription.** Duro's Entity ID is also a live SP metadata document — the same URL, served as SAML XML. Most IdPs accept either the URL or a saved copy of it and fill in both fields for you, which removes the whole class of trailing-slash and wrong-host mistakes. Open the Entity ID in a browser tab and save the page if your IdP wants a file rather than a link.

Google Workspace, Entra ID, Okta and JumpCloud all take one or the other.
{% endhint %}

Duro does not sign AuthnRequests, so there is no SP certificate to install.

{% hint style="info" %}
**Duro does not ask for a particular authentication method.** Its AuthnRequests carry no `RequestedAuthnContext`, so how someone proves who they are is entirely your IdP's decision — password, MFA, a certificate, a passkey, Windows Hello, or an existing session it chooses to reuse. Whatever your conditional access or sign-on policy requires is what applies, and Duro accepts the assertion that comes back.
{% endhint %}

{% hint style="warning" %}
**Copy the host from your own settings page, do not assume `api.durohub.com`.** Dedicated tenants are served from their own hostname — `https://acme-api.durohub.com/auth/saml/…`, for example. The values shown under **Give these to your identity provider** are always correct for your deployment; the ones in this guide are illustrative.
{% endhint %}

## Step 3 — Configure your identity provider

You are setting the same four things whatever the IdP:

| Setting              | Value                                  |
| -------------------- | -------------------------------------- |
| Entity ID / Audience | Duro's **Entity ID** from Step 2       |
| ACS / Reply URL      | Duro's **Reply URL (ACS)** from Step 2 |
| NameID format        | Email address                          |
| NameID value         | The user's primary email               |

Then collect three values **back** from your IdP: its SSO URL, its Entity ID, and its signing certificate. Those go into Duro in Step 4.

{% hint style="info" %}
**An Entity ID is an identifier, not an address.** Nothing ever fetches it — not Duro, not your IdP. It looks like a URL by convention only; a URN such as `urn:duro:jumpcloud` is equally valid, and plenty of SAML deployments use one.

On most IdPs you **choose** this value rather than look it up. There is no correct answer to discover. It only has to be unique within your IdP, and character-for-character identical to what you put in Duro's **Issuer (Entity ID)** — when that field is set, the comparison is case-sensitive and exact, with no normalization.

Two things here are genuine addresses and do have to resolve: your IdP's **SSO URL**, and Duro's own **Entity ID**, which is a real URL because it doubles as our SP metadata document.
{% endhint %}

{% hint style="warning" %}
**Duro requires the assertion itself to be signed — not just the response.**

SAML lets an identity provider sign the `<Response>` wrapper, the `<Assertion>` inside it, or both. A number of IdPs sign only the response by default, and Duro rejects that: a signed wrapper around an unsigned assertion leaves the assertion's own contents unauthenticated, which is precisely what assertion-swapping attacks rely on.

Find the signing option in your IdP and set it to **Assertion**, or **Assertion and Response**. Signing the response alone fails every sign-in, and because the rejection happens before Duro trusts anything in the document, the error page cannot tell you which of several causes it was.

This is the single most common reason a correctly-configured SAML app still will not sign anyone in.
{% endhint %}

**Sign with SHA-256 or stronger.** Duro accepts RSA or ECDSA signatures with SHA-256 or SHA-512 digests. SHA-1 is rejected, so an IdP left on SHA-1 fails every sign-in with `saml_failed`.

{% hint style="info" %}
**Sign-in starts from Duro.** Launching from the IdP dashboard tile is not supported at this time — an Okta, Google, or JumpCloud app tile sends an assertion Duro did not ask for, and it is refused with `saml_failed`. Members sign in from the Duro sign-in page, which sends them to your IdP and back.
{% endhint %}

### Google Workspace

1. [admin.google.com](https://admin.google.com) → **Apps** → **Web and mobile apps** → **Add App** → **Add custom SAML app**
2. Name it `Duro`, click **Continue**
3. **Download the IdP metadata**, or note these manually:

   * **SSO URL** — `https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXXX`
   * **Entity ID** — `https://accounts.google.com/o/saml2?idpid=XXXXXXXXX`
   * **Certificate** — download the `.pem`

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Those two URLs look nearly identical and are not. One has <code>/idp</code>, one has <code>/saml2</code>. Swapping them is the single most common setup mistake.</p></div>
4. On **Service provider details**, paste Duro's Reply URL (ACS) and Entity ID from Step 2
5. **Name ID format**: `EMAIL`. **Name ID**: `Basic Information > Primary email`
6. Skip attribute mapping — click **Finish**
7. Open the app → **User access** → **ON for everyone**, or select specific organizational units → **Save**

Google takes a few minutes to propagate.

### Microsoft Entra ID

1. [entra.microsoft.com](https://entra.microsoft.com) → **Identity** → **Applications** → **Enterprise applications** → **New application** → **Create your own application**
2. Name it `Duro`, choose **Integrate any other application you don't find in the gallery**, click **Create**
3. **Users and groups** → **Add user/group** → assign who should have access
4. **Single sign-on** → **SAML** → **Edit** on **Basic SAML Configuration**:
   * **Identifier (Entity ID)** — Duro's Entity ID
   * **Reply URL** — Duro's Reply URL (ACS)
   * **Sign on URL** — leave blank
5. Save, then under **SAML Certificates** download **Certificate (Base64)**
6. Under **Set up Duro**, copy the **Login URL** — this is Duro's **SSO URL** — and the **Microsoft Entra Identifier**, which is Duro's **Issuer (Entity ID)**

### JumpCloud

1. [console.jumpcloud.com](https://console.jumpcloud.com) → **SSO Applications** → **Add New Application**
2. Search for **Custom Application**, select it, then **Next**
3. Choose **Manage Single Sign-On (SSO)** → **Configure SSO with SAML** → **Next**
4. Name it `Duro`, then **Save Application**
5. Open the app and select the **SSO** tab

Everything else happens on that one tab, which is where the confusion lives — it shows both sides of the exchange at once:

| Field on the SSO tab          | Direction        | What to do                                                                                                                                                                                                                                                          |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Service Provider Metadata** | Duro → JumpCloud | Upload Duro's SP metadata. This fills in the next two rows for you                                                                                                                                                                                                  |
| **SP Entity ID**              | Duro → JumpCloud | Duro's **Entity ID**                                                                                                                                                                                                                                                |
| **ACS URLs**, index `0`       | Duro → JumpCloud | Duro's **Reply URL (ACS)**                                                                                                                                                                                                                                          |
| **IdP Entity ID**             | JumpCloud → Duro | **You choose this.** JumpCloud does not generate it — its own tooltip says to enter a value matching the one configured on the service provider. Anything unique works; `urn:duro:jumpcloud` is fine. Copy it verbatim into Duro's **Issuer (Entity ID)** in Step 4 |
| **IDP URL**                   | JumpCloud → Duro | Copy it into Duro's **SSO URL** in Step 4                                                                                                                                                                                                                           |
| **IdP Certificate**           | JumpCloud → Duro | Download it — this is Duro's **Signing certificate**                                                                                                                                                                                                                |

{% hint style="warning" %}
**Two fields on this screen are called an Entity ID, and they are not interchangeable.**

**SP Entity ID** describes Duro and you paste it in. **IdP Entity ID** identifies JumpCloud for this connection and you author it, then carry it over to Duro.

If you are looking at an application someone set up previously and wondering where a value like `https://sso.jumpcloud.com/saml2/duro` came from: whoever built it typed it. It is not derived from anything, and there is no equivalent value waiting to be found for a new application.
{% endhint %}

Then **Save**, open the **User Groups** tab, and assign the groups who should have access — nobody can sign in until you do.

**Set `Sign` to `Assertion and Response`.** It is a radio group near the bottom of the SSO tab, below **Signature Algorithm**, and JumpCloud defaults it to **Response** — which Duro rejects. `Assertion` alone is also fine. Leave **Signature Algorithm** on `RSA-SHA256`.

No attribute mapping is needed. JumpCloud sets NameID to the user's email by default, and Duro reads the email from NameID when no email attribute is present. `SAMLSubject NameID Format` can stay on `unspecified`.

If you would rather read the SSO URL, Entity ID and certificate out of one document than off the form, **Export Metadata** at the top of the SSO tab gives you all three together.

### Okta, OneLogin, and others

Create a generic SAML 2.0 application, map the four settings above, then collect the SSO URL, Issuer / Entity ID, and X.509 signing certificate from the app's setup instructions.

## Step 4 — Paste your IdP's details into Duro

Back on the SAML page, the **Identity provider** card is now editable. Three fields:

| Field                   | What to paste                                 | Notes                                                                                                         |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **SSO URL**             | Your IdP's sign-in URL                        | Required. Must be `https`, with no credentials in it, and must not be a private or internal address           |
| **Issuer (Entity ID)**  | Your IdP's Entity ID, **not Duro's**          | Optional but recommended. JumpCloud calls it **IdP Entity ID**; Entra calls it **Microsoft Entra Identifier** |
| **Signing certificate** | The PEM text, or click **Upload certificate** | Accepts `.pem`, `.crt`, `.cer`, `.txt`. The file is read in your browser, not uploaded anywhere               |

Leave **Create accounts automatically** alone for now — it is greyed out until SAML is enabled. Click **Save**.

Once a certificate is stored, the card shows its **Fingerprint (SHA-256)** and **Expires** date. Every IdP console displays the same fingerprint, so compare the two screens to confirm you installed the right certificate. From then on the field's helper text changes to *Replacing this changes who can sign in* — a reminder that this box is a live dependency of everyone's sign-in, not a draft.

{% hint style="warning" %}
**A blank box means two different things here.**

The **Signing certificate** field is empty every time the page loads, even when a certificate is stored — Duro never sends the PEM back, only its fingerprint. Saving with it blank therefore keeps the stored certificate.

The **Issuer (Entity ID)** field is different: it is filled in from what is saved, so clearing it and saving genuinely clears it.
{% endhint %}

Duro validates before it stores. A certificate is rejected rather than saved if it will not parse, has already expired, is not yet valid, is an RSA key under 2048 bits, or uses a key type SAML IdPs do not issue. The reasoning is the same in every case: an organization with SAML on and an unusable certificate is an organization nobody can sign in to.

## Step 5 — Turn it on and test

Flip **Enable SAML single sign-on** at the top of the page. It commits immediately — there is no Save button for it. Until your domain is verified and an SSO URL is saved it stays disabled and reads *Complete the steps below first*.

Then, in a private browsing window:

1. Go to the Duro sign-in page and enter the address of someone who is **already a member** of your organization, on your verified domain
2. Confirm the form switches to **Continue with SSO** instead of asking for a password
3. Complete the redirect to your IdP and back
4. Check that you land in your organization with the right email address
5. Refresh, confirm the session survives, then sign out

Only once that round trip is clean should you consider the two switches below.

## Creating accounts automatically

Return to the **Identity provider** card. **Create accounts automatically** is now live, and turning it on means an assertion for someone with no Duro account creates one. With it off, that person is turned away and your IdP's sign-in appears to succeed while Duro sends them back to the sign-in page they started from, with `saml_failed` in the URL.

An account created this way takes its name from a `displayName`, `name`, or `cn` attribute in the assertion. Without one, the name is the part of the email address before the `@` — map a display-name attribute in your IdP if you want real names.

Flip it and click **Save**.

{% hint style="info" %}
This governs **accounts**, not membership. Someone who already has a Duro account with an address inside your verified domain can sign in through your IdP either way. Neither SAML sign-in nor automatic account creation adds anyone to your organization: membership comes from an [invitation](https://docs.durohub.com/account-management/creating-an-account.md#what-a-new-account-can-do), from [SCIM](https://docs.durohub.com/account-management/scim-provisioning.md) teams, or from domain auto-join. Someone with an account but no route in is signed in and can do nothing until one exists.

Understand the implication: anyone your IdP will authenticate can obtain a Duro account. For most organizations [SCIM provisioning](https://docs.durohub.com/account-management/scim-provisioning.md) is the better answer — it creates accounts deliberately from your directory, adds them to teams, and deprovisions them too.
{% endhint %}

Turning SAML off switches off automatic account creation and SCIM along with it.

{% hint style="danger" %}
**Turning SAML off does not switch off** [**SSO enforcement**](#requiring-sso)**.** If your organization requires SSO, members are left with no way in: password sign-in is still refused with `AUTH_SAML_ENFORCED`, and the sign-in page no longer offers SSO. Turn enforcement off first — or send `enforceSaml: false` in the same `configureSaml` call that sends `samlEnabled: false` — before you switch SAML off.
{% endhint %}

## Requiring SSO

Once SSO is working, you can stop members signing in with a password.

{% hint style="info" %}
**There is no toggle for this in the web app**, on purpose: an organization can enable it and lock itself out with no way back in through the product. Ask Duro support (<support@durolabs.co>) to set it, or set it through the API — see [Automating this](#automating-this).
{% endhint %}

Password sign-in is then refused with `AUTH_SAML_ENFORCED` — *Your organization requires signing in with SSO*.

{% hint style="warning" %}
**Three things to check before asking for this.**

It follows the person, not the organization they are currently working in. If any organization a user belongs to requires SSO, password sign-in is refused for them everywhere.

It breaks CAD plugins that sign in with a password rather than through a browser. The Onshape and SolidWorks integrations authenticate through a real browser and are unaffected; the Altium plugin uses a password and cannot complete a SAML flow, so affected users get `AUTH_SAML_ENFORCED` with no fallback.

It disables domain-based auto-join. Your IdP becomes the only way in, so anyone who needs access must be assigned the application there.
{% endhint %}

## Certificate rotation

Duro stores one certificate at a time, so rotation is a hard cutover: paste the new certificate into **Signing certificate** and save at the moment your IdP starts signing with the new key.

Watch the **Expires** date on the card. Expiry is checked when each assertion arrives, not only at upload, so an expired certificate fails sign-in for everyone — and with SSO enforced, there is no password fallback.

## Session policy

Not SAML, but it sits on the **Authentication** page one level up and is usually the next thing an IT admin wants.

| Field                           | Blank means         | Range                |
| ------------------------------- | ------------------- | -------------------- |
| **Sign out after inactivity**   | No inactivity limit | 5 minutes to 30 days |
| **Require sign-in again after** | The 30-day default  | 1 hour to 30 days    |

{% hint style="warning" %}
**Saving a session policy signs out every member of this organization immediately, including you.** Sessions carry the policy they were created under, so the only way to apply a new one is to end the old sessions. Duro confirms before it does this.

Members who also belong to another organization get the least restrictive limit of the ones that apply to them.
{% endhint %}

## Rate limits

The SAML routes are throttled per IP address:

| Route                                                                      | Limit, per IP address                         |
| -------------------------------------------------------------------------- | --------------------------------------------- |
| `GET /auth/saml/<slug>/start`                                              | 100 per 5 minutes                             |
| `POST /auth/saml/<slug>/acs`                                               | 100 per 5 minutes                             |
| Domain discovery on the sign-in page, and `GET /auth/saml/<slug>/metadata` | 300 per 5 minutes, one counter shared by both |

Past a limit, requests slow down rather than failing: each further attempt waits half a second longer, up to five seconds, and still goes through. Only far past it, once attempts beyond the limit exceed ten times the limit, is a request refused with `429 AUTH_RATE_LIMITED`, a `Retry-After` header, and `retryAfter` (seconds) in the body:

```json
{ "code": "AUTH_RATE_LIMITED", "message": "Too many attempts. Wait a moment and try again", "retryAfter": 42 }
```

An office or VPN that puts many people behind one address shares that address's counters. Each sign-in passes through `start` and `acs` once, so about 100 sign-ins from one address in 5 minutes reaches the limit. A large office signing in together, for example right after a session policy change signs everyone out, may see sign-ins slow down for a few minutes. That is expected and clears on its own. Only a `429` means something is looping.

## Troubleshooting

### Start with the status on the Authentication page

The **SAML single sign-on** row summarizes the whole setup in a few words, without your having to open the form:

| The row says                            | What is missing                                   |
| --------------------------------------- | ------------------------------------------------- |
| *Not configured*                        | No verified domain. Start at Step 1               |
| *Domain verified, no identity provider* | No SSO URL saved. Step 4                          |
| *Configured, not enabled*               | Everything is saved but the toggle is off. Step 5 |
| Your domain, e.g. `acme.com`            | SSO is live for that domain                       |

### The sign-in page asks for a password instead of offering SSO

Discovery routes an address to SAML only when all four are true: the domain is verified, SAML is enabled, an SSO URL is saved, and the address matches the verified domain exactly. The status row above covers the first three. For the fourth, remember `dana@mail.acme.com` does not match a verified `acme.com`.

### Your IdP rejects the request before showing a login screen

Almost always the Entity ID or Reply URL. Re-copy them from **Give these to your identity provider**, or point your IdP at the metadata URL instead of typing them.

On Entra ID, `AADSTS75011` — *Authentication method by which the user authenticated with the service doesn't match requested authentication method* — does not come from Duro's request, which asks for no authentication context. If you see it, it is coming from a policy in your IdP.

### Sign-in bounces back to the sign-in page with `saml_failed`

The assertion was rejected, and Duro returned the user to the page they started from with `saml_failed` in the URL — see [Where a failed sign-in lands](#where-a-failed-sign-in-lands). Check the signing setting first: if your IdP signs only the `<Response>` and not the `<Assertion>`, every sign-in fails this way even though the IdP reports success and nothing else is misconfigured. Set it to **Assertion** or **Assertion and Response**.

After that, check in this order:

* **Certificate** — the one saved in Duro is not the one signing, or it has expired. Compare the **Fingerprint (SHA-256)** shown in Duro against your IdP console
* **Audience** — your IdP's Entity ID / Audience is not Duro's **Entity ID**
* **Algorithm** — your IdP signs with SHA-1. Switch it to SHA-256
* **Started from the IdP** — the person launched Duro from the IdP dashboard tile, which is not supported at this time. Start from the Duro sign-in page
* **Address** — the email in the assertion is outside your verified domain (subdomains of it are accepted)
* **No account** — the person has no Duro account and **Create accounts automatically** is off. Turn it on, or invite or [provision](https://docs.durohub.com/account-management/scim-provisioning.md) them
* **Archived account** — the person's Duro account has been archived

All of these produce the same `saml_failed`, deliberately — the code is shown to whoever triggered it, so it does not report which check failed.

### Sign-in returns `429 AUTH_RATE_LIMITED`

Something at that IP address is hitting one of the throttled counters far past its limit. On the SAML `start` or `acs` route, that is usually a redirect loop between Duro and the IdP, a browser extension, or a script retrying a failed assertion. On the shared discovery and metadata counter, it is usually a script calling domain discovery or fetching `GET /auth/saml/<slug>/metadata` in a loop. Requests from that address will already have been slowing down before the refusal. Stop the loop, wait the `retryAfter` from the response, and try again. See [Rate limits](#rate-limits).

### Everyone was signed out unexpectedly

Someone saved a session policy. See [Session policy](#session-policy) — saving one ends every session in the organization by design.

### Saving fails with *Single sign-on is not included in your plan*

Your plan does not include the `SSO_SAML` entitlement. Contact your Duro account team. See [Entitlement Errors](https://docs.durohub.com/advanced-topics/error-handling.md#entitlement-errors).

## Automating this

Everything above is available through the GraphQL API at `https://api.durohub.com/graphql`, for organizations that manage tenant configuration as code. All of it requires the `organization.saml.configure` permission and an `x-organization` header naming your organization. The domain operations and `configureSaml` also require the `SSO_SAML` entitlement; `configureSessionPolicy` and `getSamlAdminConfig` do not.

{% hint style="info" %}
Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).
{% endhint %}

| Operation                                  | What it does                                                                                                                                                                             |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization.verifyOrganizationDomain`    | Issues the DNS challenge — returns `recordName` and `recordValue`                                                                                                                        |
| `organization.checkOrganizationDomain`     | Checks the TXT record and records success                                                                                                                                                |
| `organization.configureSaml`               | Writes the IdP details and the `samlEnabled`, `samlJitEnabled`, `enforceSaml` flags                                                                                                      |
| `organization.configureSessionPolicy`      | Sets the session policy — and revokes every session in the organization                                                                                                                  |
| `authentication.getSamlAdminConfig(slug:)` | Reads back the current configuration, including `spEntityId`, `spAcsUrl`, `certificateFingerprint` and `certificateExpiresAt`. `slug` must be the organization named in `x-organization` |

A configuration save looks like this, sent with `x-organization: @your-org-slug`:

```graphql
mutation {
  organization {
    configureSaml(input: {
      id: "550e8400-e29b-41d4-a716-446655440000"
      samlIdpEntryPoint: "https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXXX"
      samlIdpIssuer:     "https://accounts.google.com/o/saml2?idpid=XXXXXXXXX"
      samlIdpCertificate: "-----BEGIN CERTIFICATE-----\nMIID…\n-----END CERTIFICATE-----"
      samlJitEnabled: false
    }) { id }
  }
}
```

{% hint style="warning" %}
**Every field is written only when supplied**, so send only what changed. Do not echo values you did not mean to set: posting `samlEnabled: false` from a stale read turns "save my IdP details" into "switch SAML off", which also switches off automatic account creation and SCIM — and leaves SSO enforcement on, if it was on.
{% endhint %}

`enforceSaml` is the one setting with no web UI at all, for the reason given under [Requiring SSO](#requiring-sso):

```graphql
mutation {
  organization {
    configureSaml(input: {
      id: "550e8400-e29b-41d4-a716-446655440000"
      enforceSaml: true
    }) { id }
  }
}
```

Note that `samlIdpCertificate` is never returned by any query — only its fingerprint and expiry — so there is no read-modify-write available for that field.

## Next steps

* [SCIM Provisioning](https://docs.durohub.com/account-management/scim-provisioning.md) — provision users and teams from the same IdP
* [Role-Based Access Control](https://docs.durohub.com/advanced-topics/rbac.md) — what those users can do once they are in


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/account-management/enterprise-sso.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
