> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/account-management/workspaces-and-organization/how-to-set-up-single-sign-on.md).
# Set up single sign-on (SAML)
Connect your SAML 2.0 identity provider to Coupler.io so your team signs in through your company's identity provider, and optionally require single sign-on for every member of your organization.
{% columns %}
{% column %}
{% hint style="success" icon="user-key" %}
Role requirement: Organization Owner
{% endhint %}
{% endcolumn %}
{% column %}
{% hint style="info" icon="cart-circle-plus" %}
Plan requirement: Agency & Enterprise plan
{% endhint %}
{% endcolumn %}
{% endcolumns %}
Single sign-on (SSO) lets the members of your organization sign in to Coupler.io through your own identity provider using SAML 2.0 — the same way they sign in to your other company applications. Your identity provider decides who gets access, so you manage Coupler.io accounts from one place instead of one by one.
You can set SSO up alongside your existing sign-in methods, then require it for everyone once you've confirmed it works.
{% hint style="info" %}
Coupler.io works with any SAML 2.0 identity provider. **Okta** is the provider we've tested end to end, and it's used as the example throughout this guide — the steps are the same for any provider, only the screen names differ. If your provider needs different handling, contact support.
{% endhint %}
***
### Before you start
**This usually takes two people.** Setting up SSO means exchanging values between two systems:
* In **Coupler.io**, only an **Organization Owner** can open and change SSO settings — Admins cannot. If you're not the Owner, ask your Owner to do the Coupler.io steps or to make you an Owner.
* In **your identity provider**, you need administrator access to create a SAML application.
If those are two different people, you only need to pass two values between you — Step 1 tells you which.
You'll also need your organization on the **Agency & Enterprise** plan. On any other plan the SSO settings show an upgrade prompt instead of the configuration form.
***
### Where to find SSO settings
{% stepper %}
{% step %}
Go to Organization Settings. You can access it from the bottom-left sidebar menu.
{% endstep %}
{% step %}
Open the **Single sign-on** tab — it's the last tab, after Workspaces, Organization owners, and Settings.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Don't see the Single sign-on tab? You're either not an Organization Owner, or your organization isn't on the Agency & Enterprise plan.
{% endhint %}
***
### Step 1: Copy Coupler.io's service provider details
Open Organization Settings :arrow-right: **Single sign-on**. Under **Service provider details** you'll find two values, each with a copy button:
| Value in Coupler.io | What it's for |
| -------------------------------- | ---------------------------------------------------------------- |
| **Single sign-on URL (ACS URL)** | Where your identity provider sends users after they authenticate |
| **Audience URI (SP Entity ID)** | How your identity provider identifies Coupler.io |
**These two values are everything your identity provider administrator needs from Coupler.io.** If someone else administers your identity provider, send them both now.
{% hint style="success" %}
In Okta, the fields you paste these into have **exactly the same names** — *Single sign-on URL* and *Audience URI (SP Entity ID)*. Match them by name and you can't mix them up.
{% endhint %}
***
### Step 2: Create the SAML application in your identity provider
These steps use Okta. Other providers use different screen names but ask for the same values.
{% stepper %}
{% step %}
In the Okta Admin Console, go to Applications and Resources :arrow-right: Applications and click **Create App Integration**.
{% endstep %}
{% step %}
Choose **SAML 2.0** as the sign-in method, then click **Next**.
{% endstep %}
{% step %}
Give the application a name — for example, `Coupler.io`. Adding a logo is optional. Click **Next**.
{% endstep %}
{% step %}
In **Configure SAML**, paste the two values from Step 1: your Coupler.io ACS URL into **Single sign-on URL**, and your Audience URI into **Audience URI (SP Entity ID)**.
*Leave "Use this for Recipient URL and Destination URL" checked, and leave Default RelayState empty.*
{% endstep %}
{% step %}
Set **Name ID format** to `EmailAddress` and **Application username** to `Email`.
*Coupler.io identifies people by email address, so the value your provider sends must be the user's email.*
{% endstep %}
{% step %}
Click **Next**, then **Finish**. You can leave every signing and encryption setting at its default — Coupler.io accepts Okta's defaults as they come.
{% endstep %}
{% step %}
Assign the people who should have access. Go to Directory :arrow-right: People, open a user, switch to the **Applications** tab and click **Assign Applications** — or use the **Assignments** tab on the application itself.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Users who aren't assigned to the application cannot sign in.** If someone reports that SSO doesn't work for them, check their assignment first.
{% endhint %}
{% hint style="info" %}
**Why the email setting matters.** Coupler.io looks for the user's email address in the assertion, and falls back to the Name ID if no email attribute is sent. If your identity provider's usernames are email addresses, `Unspecified` happens to work — but setting `EmailAddress` explicitly is what makes it reliable. If your connection test later fails because no email was found, this is the first setting to check.
{% endhint %}
**You do not need to configure attribute statements.** Email is the only value Coupler.io requires, and the Name ID covers it. First and last name attributes are optional — send them if you want names to appear on member profiles.
***
### Step 3: Add your provider's details to Coupler.io
The quickest way is to let Coupler.io read your provider's metadata.
{% stepper %}
{% step %}
In Okta, open your application and go to the **Sign On** tab. Under **Metadata details**, copy the **Metadata URL**.
{% endstep %}
{% step %}
In Coupler.io, under **Identity provider details**, paste it into **IdP metadata URL** and click **Fill in from URL**.
*This fills in the Entity ID, Single sign-on URL and X.509 certificate for you.*
{% endstep %}
{% step %}
Check the filled-in values, then click **Save connection**.
{% endstep %}
{% endstepper %}
**Prefer to enter the values by hand?** In Okta, click **View SAML setup instructions** on the Sign On tab. It lists the Identity Provider Single Sign-On URL, the Identity Provider Issuer, and the X.509 Certificate. Paste them into **Single sign-on URL**, **Entity ID**, and **X.509 certificate**, then click **Save connection**. Use this route if your provider doesn't publish a metadata URL.
{% hint style="warning" %}
The metadata URL is used **once**, to fill in the fields — Coupler.io doesn't store it or check it again. If your provider's signing certificate is ever replaced, come back and repeat this step.
{% endhint %}
***
### Step 4: Test the connection
Saving the connection doesn't switch anything on. Coupler.io requires a successful test first, so a misconfigured connection can never capture your team's sign-ins.
{% stepper %}
{% step %}
Under **Test and activate**, click **Test connection**.
{% endstep %}
{% step %}
Coupler.io runs a real sign-in round-trip against your identity provider and brings you back to this page with the result.
{% endstep %}
{% endstepper %}
If the test fails, the message names the reason. The most common causes are that the signing certificate or single sign-on URL don't match, that no email address was found in the response (see Step 2), or that your own account isn't assigned to the application in your identity provider.
***
### Step 5: Enable single sign-on
Once the test has passed, turn on **Enable single sign-on**.
Your members **can** now sign in through your identity provider — and every existing sign-in method still works. Nothing is taken away at this stage, which makes this a safe point to stop and let a few people try it.
***
### Step 6: Require single sign-on (optional)
When you're ready for SSO to be the only way in, turn on **Enforce single sign-on**. Coupler.io asks you to confirm, because this changes how your team signs in.
{% hint style="warning" %}
Once enforcement is on, members and Admins can no longer sign in with a password or with Google, Microsoft or other social logins. Anyone who tries is sent to your identity provider instead.
**Organization Owners are exempt and keep password access.** This is deliberate — it means you can always get back in if something goes wrong with your identity provider.
{% endhint %}
Enforcement is all-or-nothing for the organization; there's no per-person setting. Before you turn it on, make sure everyone who needs Coupler.io is assigned to the application in your identity provider.
You can turn enforcement off again at any time, which returns everyone to the standard sign-in methods while leaving your SSO connection in place.
***
### What changes for your members
Once SSO is enabled, there are three ways in — all of them end at your identity provider:
| How they sign in | What happens |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **The SSO option on the Coupler.io login page** | They enter their email and are taken to your identity provider. |
| **Their old password or social login** (when enforcement is on) | They're redirected to your identity provider automatically — no error message, no dead end. |
| **The Coupler.io tile in your identity provider's portal** | Clicking it signs them straight in. |
**New members** you invite receive the usual invitation email. When they accept, they go straight to your identity provider to sign in — they never set a Coupler.io password. Invitations expire after 14 days, and pending invitations count towards your plan's user limit.
**Members don't need Coupler.io two-factor authentication.** For SSO sign-ins Coupler.io relies on your identity provider's own authentication policy, so whatever you require there — including MFA — is what applies.
***
### Maintaining the connection
**Replacing the signing certificate.** If your identity provider issues a new certificate, repeat Step 3 — either fill in from the metadata URL again or paste the new certificate into **X.509 certificate**. Leaving the certificate field empty keeps the one already stored.
**Changing identity provider details.** Saving changed details resets the connection: it stays disabled until a new test passes. Plan for a short gap, or make the change outside working hours.
**Turning SSO off.** Switch off **Enable single sign-on** and your members go back to their standard sign-in methods. Your configuration and enforcement setting are both kept, so you can switch it back on without setting anything up again.
***
### FAQ
Who can set up and manage SSO?
Only **Organization Owners**. Admins and other members can't view or change SSO settings. If you need someone else to manage it, make them an Organization Owner.
Is anyone exempt from enforced SSO?
Yes — **Organization Owners** keep their existing sign-in methods, including password and social login, even when enforcement is on. Everyone else, Admins included, must use SSO. This gives you a guaranteed way back in if your identity provider becomes unavailable.
What happens if we downgrade our plan?
SSO stops working and your members go back to signing in with their standard methods. Your configuration is preserved, so returning to the Agency & Enterprise plan restores SSO without any reconfiguration.
If a member only ever signed in through SSO and has no password, they can set one with **Forgot your password?** on the login page.
Can we connect more than one identity provider?
No. Each organization has one SAML connection. To switch providers, edit the existing connection with the new provider's details — remember that saving changes requires a new passing test before SSO works again.
Do we need to configure attribute statements or claims?
No. The only value Coupler.io needs is the user's email address, and the Name ID provides it. You can send first and last name attributes if you'd like names shown on member profiles, but they're optional.
The connection test fails. What should we check?
Work through these in order:
1. **Is your own account assigned to the application** in your identity provider? Unassigned users can't authenticate.
2. **Does the response include an email address?** Set Name ID format to `EmailAddress` (Step 2).
3. **Do the certificate and single sign-on URL match?** Re-run **Fill in from URL** to refresh them from your provider's metadata.
4. **Did you save after editing?** Changed details reset the connection until a new test passes.
Can members still use Google or Microsoft sign-in?
Until you turn on enforcement, yes — every existing method keeps working alongside SSO. Once enforcement is on, members and Admins are redirected to your identity provider instead. Organization Owners keep all their methods.
Do our members need Coupler.io two-factor authentication as well?
No. For SSO sign-ins Coupler.io trusts your identity provider to verify identity, so it doesn't ask for its own second factor. Whatever authentication policy you enforce in your identity provider — including MFA — is what your members experience.
We use a provider other than Okta. Is it supported?
Coupler.io supports any SAML 2.0 identity provider, and the setup is the same: exchange the two service provider values, then supply your provider's Entity ID, single sign-on URL and certificate. Okta is the provider we've tested end to end — if yours behaves differently or you get stuck, contact support and we'll help you connect it.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.coupler.io/account-management/workspaces-and-organization/how-to-set-up-single-sign-on.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.