# Connect a SAML provider

> Let your people sign in through any SAML 2.0 identity provider, such as Okta, Microsoft Entra ID, Google Workspace, OneLogin or JumpCloud.

Source: https://docs.bifrostorbit.com/orbit/admins/connect-saml-sso/

## Before you start

SAML 2.0 is the older single sign-on standard many companies still use. Orbit acts as the service provider and your identity provider signs people in. If your provider also speaks OpenID Connect, [an OpenID Connect connection](https://docs.bifrostorbit.com/orbit/admins/connect-oidc-sso/) is quicker to set up; both work as well.

You need:

- an administrator account in your identity provider,
- the email domains your people use, such as `northwilds.com`. Orbit only lets in addresses on these domains through the connection, whatever your provider says.

## 1. Start the connection in Orbit

1. In Orbit, open **Organisations**, choose your organisation, then the **Sign-in** tab.
2. Under **Ways to sign in**, switch on **SAML**, then choose **Save changes**.
3. In the **SAML** section, choose **Add SAML provider**.
4. Copy the two values at the top of the dialog:

| In Orbit | Also called |
| --- | --- |
| **Entity ID** | Audience URI, SP entity ID, identifier. It ends in `/metadata`, and Orbit's metadata XML is at that address. |
| **ACS URL** | Single sign-on URL, assertion consumer service URL, reply URL. It ends in `/acs`. |

Both contain the connection's own ID, so copy them from this dialog. Keep it open while you set up your provider.

## 2. Create the app in your provider

Create a SAML app with the two values from step 1. Use the person's email address as the NameID, and send the attributes below. Orbit needs the response or the assertion to be signed; most providers sign the assertion by default.

| Attribute | Usual name |
| --- | --- |
| Email (required) | `email` |
| First name | `firstName` |
| Last name | `lastName` |
| Groups, for role mapping | `groups` |

Orbit also understands the names Microsoft Entra ID sends by default, so you only change the names in Orbit if your provider uses others.

**Okta:**

1. In the Okta Admin Console, go to **Applications** > **Applications** > **Create App Integration** and choose **SAML 2.0**.
2. Name it *Bifröst Orbit*. Under **SAML Settings**, paste the ACS URL into **Single sign-on URL** and the entity ID into **Audience URI (SP Entity ID)**.
3. Set **Name ID format** to *EmailAddress* and **Application username** to *Email*.
4. Under **Attribute Statements**, add `email`, `firstName` and `lastName` from `user.email`, `user.firstName` and `user.lastName`. Under **Group Attribute Statements**, add `groups` with a filter such as *Starts with* `northwilds-`.
5. Finish, assign people on **Assignments**, then copy the **Metadata URL** from the **Sign On** tab.

**Microsoft Entra ID:**

1. In the Microsoft Entra admin center, go to **Enterprise applications** > **New application** > **Create your own application**, and choose *Integrate any other application you don't find in the gallery*.
2. Open **Single sign-on** and choose **SAML**.
3. Under **Basic SAML Configuration**, paste the entity ID into **Identifier (Entity ID)** and the ACS URL into **Reply URL**.
4. Under **Attributes & Claims**, the defaults work. To map groups, choose **Add a group claim**.
5. Assign people under **Users and groups**, then copy the **App Federation Metadata Url** from **SAML Certificates**.

Microsoft Entra ID also works through [Microsoft SSO](https://docs.bifrostorbit.com/orbit/admins/connect-microsoft-sso/), which reads app roles and lists your directory when you add members. Choose SAML only if your IT team prefers it.

**Google Workspace:**

1. In the Google Admin console, go to **Apps** > **Web and mobile apps** > **Add app** > **Add custom SAML app**.
2. Name it, then download the **IdP metadata** on the next page.
3. Paste the ACS URL into **ACS URL** and the entity ID into **Entity ID**. Set **Name ID format** to *EMAIL* and **Name ID** to *Basic Information > Primary email*.
4. Under **Attribute mapping**, map *Primary email* to `email`, *First name* to `firstName` and *Last name* to `lastName`. For groups, add the groups under **Group membership** and name the app attribute `groups`.
5. Switch the app on for your people under **User access**.

**OneLogin and JumpCloud:** add a custom SAML connector (OneLogin: *SAML Custom Connector (Advanced)*; JumpCloud: **Custom Application** with SAML), paste the entity ID and ACS URL, use the email as the NameID, add the attributes above, and copy the metadata URL or download the metadata file.

## 3. Finish the connection in Orbit

Back in the dialog:

1. Enter a **Button name**, such as *Okta*. People see **Continue with Okta** on your sign-in page.
2. Paste the provider's **Metadata URL**, or paste the metadata file under **Or metadata XML**. Orbit reads the identity provider entity ID, sign-in URL and signing certificate from it when you save. Without metadata, fill in **Identity provider entity ID**, **Sign-in URL** and **Signing certificate** by hand.
3. Change the **Attribute names** only if your provider uses other names.
4. Enter your **Work email domains**, such as `northwilds.com`. Verify them under **Domains** first.
5. Choose **Save connection**.

Each domain can belong to only one organisation, and to one of your connections. Once saved, the dialog shows each certificate's name, fingerprint and expiry date.

## 4. Choose who gets in

This works the same as for OpenID Connect: **Everyone the provider lets in** gives everyone on your domains the access under **Everyone gets**, and **Role mapping** gives a group's members a role and satellites. Type each group exactly as your provider sends it. See [Connect an OpenID Connect provider](https://docs.bifrostorbit.com/orbit/admins/connect-oidc-sso/).

## Certificates expire

Identity providers renew their signing certificate every year or few years. Before yours expires:

1. Create the new certificate in your provider, without switching to it yet.
2. Paste both the current and the new certificate under **Signing certificate** and save. Orbit accepts either.
3. Switch your provider to the new certificate, then remove the old one in Orbit.

An expired certificate shows **Certificate expired** next to the connection.

## What happens next

- People type their work email on the main sign-in page and go straight to your provider, or choose **Continue with** and your button name on your sign-in address.
- Sign-in starts in Orbit. Orbit refuses sign-ins your provider starts on its own (from its app dashboard), because they cannot be tied to a request. Point your dashboard tile to your Orbit sign-in address instead.
- To add and remove people automatically, set up [SCIM provisioning](https://docs.bifrostorbit.com/orbit/admins/set-up-scim/).

## If something goes wrong

**Your company's sign-in sent an answer Bifröst Orbit could not trust:** the signature, audience, ACS URL or time did not match. Check the entity ID and ACS URL in your provider match Orbit's exactly, the certificate in Orbit is the one your provider signs with, and the clocks on your provider's servers are right.

**That sign-in took too long or was already used:** start again from your sign-in page. Each sign-in can be used once, within a few minutes.

**Your company's sign-in did not send an email address:** send the email as the NameID, or as an attribute named as in **Attribute names**.

**Your company's sign-in vouched for an email address this organisation does not use:** add the person's domain to the connection.
