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.
How-to guide6 min read
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 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.
1Start the connection in Orbit
- In Orbit, open Organisations, choose your organisation, then the Sign-in tab.
- Under Ways to sign in, switch on SAML, then choose Save changes.
- In the SAML section, choose Add SAML provider.
- Copy the two values at the top of the dialog:
/metadata, and Orbit's metadata XML is at that address./acs.Both contain the connection's own ID, so copy them from this dialog. Keep it open while you set up your provider.
2Create 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.
emailfirstNamelastNamegroupsOrbit also understands the names Microsoft Entra ID sends by default, so you only change the names in Orbit if your provider uses others.
Okta:
- In the Okta Admin Console, go to Applications > Applications > Create App Integration and choose SAML 2.0.
- 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).
- Set Name ID format to EmailAddress and Application username to Email.
- Under Attribute Statements, add
email,firstNameandlastNamefromuser.email,user.firstNameanduser.lastName. Under Group Attribute Statements, addgroupswith a filter such as Starts withnorthwilds-. - Finish, assign people on Assignments, then copy the Metadata URL from the Sign On tab.
Microsoft Entra ID:
- 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.
- Open Single sign-on and choose SAML.
- Under Basic SAML Configuration, paste the entity ID into Identifier (Entity ID) and the ACS URL into Reply URL.
- Under Attributes & Claims, the defaults work. To map groups, choose Add a group claim.
- Assign people under Users and groups, then copy the App Federation Metadata Url from SAML Certificates.
Microsoft Entra ID also works through 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:
- In the Google Admin console, go to Apps > Web and mobile apps > Add app > Add custom SAML app.
- Name it, then download the IdP metadata on the next page.
- 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.
- Under Attribute mapping, map Primary email to
email, First name tofirstNameand Last name tolastName. For groups, add the groups under Group membership and name the app attributegroups. - 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.
3Finish the connection in Orbit
Back in the dialog:
- Enter a Button name, such as Okta. People see Continue with Okta on your sign-in page.
- 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.
- Change the Attribute names only if your provider uses other names.
- Enter your Work email domains, such as
northwilds.com. Verify them under Domains first. - 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.
4Choose 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.
Certificates expire
Identity providers renew their signing certificate every year or few years. Before yours expires:
- Create the new certificate in your provider, without switching to it yet.
- Paste both the current and the new certificate under Signing certificate and save. Orbit accepts either.
- 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.
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.
Was this page helpful?