# Single sign-on

> How By Dawn signs your people in through your company's identity provider, what to set up first, and how a first sign-in works.

This page helps you let your people sign in to By Dawn with the account they already have at work. By
the end you'll know what to set up and in what order, and you'll have added your first connection.

With single sign-on (SSO), someone at your company types their work email on By Dawn's sign-in page.
By Dawn sends them to your company's identity provider, which checks who they are and sends them back
signed in to your organization. You manage who can sign in from your identity provider, so people
who leave can't sign in to By Dawn through it once you switch off their work account.

Single sign-on needs the Enterprise plan. Without it, **Settings › Organization › Single sign-on**
shows **Single sign-on is not on your plan** (see [Plans and billing](https://docs.bydawn.com/billing/)). Verifying a domain works on
every plan.

## Words on these pages

- **Identity provider (IdP)**: the service that holds your company's accounts and checks
  passwords, such as Okta, Microsoft Entra ID or Google Workspace.
- **Verified domain**: an email domain, such as `acme.com`, that your organization has proved it
  owns by adding a DNS record. See [Verify a domain](https://docs.bydawn.com/sso-domains/).
- **SSO connection**: the link between your By Dawn organization and your identity provider. It holds
  what each side needs to trust the other.
- **OIDC and SAML**: the two standard ways an identity provider can talk to By Dawn. Both work. They
  differ in what you copy between the two sides.

## Before you start

You need to be your organization's **owner**. Admins can open **Settings › Organization › Single sign-on**
and read it, but every change is the owner's: the page says "Only the organization owner can change single
sign-on." Members don't see the section.

## The order to set things up

1. **Verify your email domain.** By Dawn only signs someone in through your connection if their email
   is at one of your verified domains (see [the email rule](#the-email-rule)), so a connection can't be
   activated without one. [Verify a domain](https://docs.bydawn.com/sso-domains/).

2. **Add a connection** in By Dawn, and the matching app in your identity provider. Each provider's
   page walks you through both sides:
   - [Okta](https://docs.bydawn.com/sso-okta/)
   - [Microsoft Entra ID](https://docs.bydawn.com/sso-entra-id/)
   - [Google Workspace](https://docs.bydawn.com/sso-google-workspace/)
   - [Any other SAML 2.0 or OIDC provider](https://docs.bydawn.com/sso-generic-saml/)

3. **Test it, then activate it.** Testing signs you in through the connection without changing
   anything for anyone else. Once it's active, your people see **Continue with SSO** when they type their work
   email (see [Enforcement](#enforcement)).

## OIDC or SAML?

If your identity provider offers both, use **OIDC**. It needs only three values from your
provider (an issuer URL, a client ID and a client secret), and there are no certificates to
rotate. Okta, Microsoft Entra ID and Google Workspace all support it.

Use **SAML** when your provider only speaks SAML (Active Directory Federation Services, for
example), or when your security team asks for it. SAML needs your provider's signing certificate,
so you'll update the connection when that certificate is replaced.

## Add a connection

Open **Settings › Organization › Single sign-on**. Each provider's page tells you which of its
values goes where.

1. Under **How does your identity provider connect?**, pick **OpenID Connect (OIDC)** or **SAML 2.0**. Give
   the connection a **Name** your admins will recognise, such as `Okta`, and choose **Create draft**. The
   connection appears as a card marked **Draft**.

2. Under **Give your identity provider these**, copy By Dawn's values into your identity provider. Each has a
   copy button. Always copy them from there rather than typing them, because they're specific to your
   connection:
   - for **OIDC**, the **Redirect URI (sign-in redirect / callback URL)**;
   - for **SAML**, the **SP entity ID (audience)** and the **ACS URL (single sign-on URL)**. By Dawn also
     offers an **SP metadata URL** carrying both, for providers that can import it.

3. Under **From your identity provider**, fill in your provider's values, then choose **Save changes**:
   - for **OIDC**, the **Issuer URL** and **Client ID**. Paste the client secret into its own box and choose
     **Save secret**. By Dawn encrypts it and never shows it again ("Set · updated" and a date). To change it,
     paste a new one and choose **Replace secret**.
   - for **SAML**, paste the provider's metadata XML into **Paste your IdP's metadata XML (optional)** and
     choose **Fill in from metadata**. By Dawn fills in the **IdP entity ID (issuer)**, **IdP sign-in URL** and
     **IdP signing certificate**, which you can also type by hand.

4. Under **New people**, choose whether **Create accounts on first sign-in** is on, and **Their role**:
   **Member** or **Admin**. See [First sign-in](#first-sign-in).

5. Choose **Test connection**. By Dawn sends you through your identity provider and back to this page, which says
   whether the connection passed, and why not if it didn't. Nobody else is affected. Testing works from By Dawn
   on the web, not the desktop app.

6. Choose **Activate**. It's available once the connection passed a test in the last 24 hours, your changes
   are saved and you have a verified domain. Until then By Dawn says what's missing, such as "To activate, verify
   a domain, then pass a test in the last 24 hours."

One connection is active at a time. To switch providers safely, choose **New connection**, set up and test the
new one as a draft, then activate it: activating swaps out the connection that was active.

You can **Disable** an active connection at any time. Nobody can sign in through it any more, and
**Enforcement** goes back to **Off**, so people sign in the other ways your organization allows. A connection that isn't active can be deleted with
**Delete**, which discards its settings and client secret.

## Enforcement

The **Enforcement** card decides whether people at your verified domains sign in through single sign-on.

| Setting | What it means |
| --- | --- |
| **Off** | People sign in however the sign-in policy allows. Single sign-on is not offered. |
| **Optional** | People at your verified domains are offered single sign-on first, and can still use other sign-in methods. |

Activating your first connection moves **Enforcement** from **Off** to **Optional** for you, so the connection
is offered straight away. Set it back to **Off** to stop offering it without disabling the connection. **Optional** needs an active connection, so without one it says
"Needs an active connection." The setting only reaches people at your verified domains. Contractors whose email is at another company sign in the
way they do today.

> **Required isn't available yet:** The card also lists **Required**, which turns every other sign-in method away for your verified domains, with
> a passkey sign-in kept for the owner. By Dawn can't save it yet, because it's switched off while the desktop and
> mobile apps finish their single sign-on support. This page will say how to use it once it's on.

## How your people sign in

- **On the web**, they type their work email on By Dawn's sign-in page. By Dawn finds your connection from the email's
  domain, says "Your organization uses single sign-on. Continue to your company's sign-in page." and offers
  **Continue with SSO**. They can also go straight to your organization's **SSO address**: By Dawn's web address
  followed by `/sso/` and your organization's **URL slug** from
  **Settings › Organization › General**. Put it on your intranet, or in your identity provider's
  app list.
- **In the desktop app**, **Continue with SSO** opens the system browser, so your identity provider's
  usual sign-in page, saved passwords and device checks all work. When it's done, the browser
  hands them back to the app, signed in.

People can't start from a tile in your identity provider's app dashboard (an IdP-initiated
sign-in). By Dawn only accepts a sign-in that By Dawn itself started, because an answer nobody asked for
is easier to replay or forge. Each provider's page says how to point a dashboard tile at your SSO
address instead.

A session that started through single sign-on lasts at most 24 hours. After that By Dawn sends the person back
through your identity provider, which usually signs them in again without asking. So someone you switch off
there loses By Dawn within a day, or at once if you use [SCIM provisioning](https://docs.bydawn.com/scim/).

## First sign-in

With **Create accounts on first sign-in** on, which is how a new connection starts, the first time someone
signs in through your connection By Dawn creates their account if they don't have one and adds them to your
organization with the role in **Their role**. They land in your organization straight away, with no
invitation needed. A first sign-in can never make someone an owner: only an owner can do that, inside By Dawn.

With it off, only people who are already members, or who have an invitation to that email, can sign in
through SSO. Anyone else is turned away and nothing is created. Choose this if you'd rather
[invite people](https://docs.bydawn.com/members/) one by one.

Someone who already has a By Dawn account with the same work email signs in to that same account, so
their tickets and history stay theirs. An existing member keeps their role. To change roles from your
identity provider, use [group mappings](https://docs.bydawn.com/scim/#map-groups-to-roles), which need SCIM provisioning.

Each new person takes a seat. An organization at its member limit turns the sign-in away: "This organization
is at its member limit."

## The email rule

A connection only signs in people whose email is at one of **your organization's verified
domains**. If your identity provider sends back any other email, By Dawn refuses the sign-in and doesn't link
that identity to any By Dawn account. Your people see "That email address isn't on one of your organization's
verified domains, so single sign-on can't sign it in."

The rule is there to protect every By Dawn customer, including you. Whoever runs an identity provider
decides what email it reports. Without the rule, an admin elsewhere could set up a provider that
claims to be `you@yourcompany.com` and sign in as you. Checking the email against domains your
organization has proved it owns closes that door.

In practice this means:

- add every domain your people's emails use, such as `acme.com` and `acme.co.uk`, before you
  activate;
- contractors whose email is at another company sign in the way they do today, not through your
  connection;
- if a domain stops being verified, its people can't sign in through SSO until you verify it again
  (see [Verify a domain](https://docs.bydawn.com/sso-domains/#keep-the-record-in-place)).

After the first sign-in, By Dawn recognises the person by the ID your identity provider gives them, not by their
email. So someone who edits their email in your identity provider can't take over a colleague's By Dawn account.

## FAQ

**What does a failed test mean?**

The banner names the reason. The most common are "Your identity provider signed you in with an email address
outside this organization's verified domains" (check which email your provider sends, or verify that domain)
and "SAW couldn't accept the identity provider's response" (check the settings, and for SAML the certificate).

**Can people still use an email code or Google once SSO is on?**

Yes. With **Enforcement** at **Optional**, single sign-on is offered first and the other ways still work, as
far as your [sign-in policy](https://docs.bydawn.com/security/#sign-in-methods) allows them.

**Does By Dawn read groups from our identity provider?**

Through SCIM, yes: [group mappings](https://docs.bydawn.com/scim/#map-groups-to-roles) can make a group's members admins or put them
on a project. A sign-in through SSO alone doesn't change anyone's role.

## Where to go next

- [Verify a domain](https://docs.bydawn.com/sso-domains/), if you haven't yet.
- Your provider's page: [Okta](https://docs.bydawn.com/sso-okta/), [Microsoft Entra ID](https://docs.bydawn.com/sso-entra-id/),
  [Google Workspace](https://docs.bydawn.com/sso-google-workspace/) or [any other provider](https://docs.bydawn.com/sso-generic-saml/).
- [SCIM provisioning](https://docs.bydawn.com/scim/), to add and remove people from your identity provider.

Source: https://docs.bydawn.com/sso/