Single Sign-On

Enterprise SSO lets your team, and optionally your partners, sign in to Journeybee through your own identity provider: Okta, Entra ID, Google Workspace, or any SAML or OIDC provider. Accounts are governed by your IdP, so joiners and leavers are handled where you already handle them.

This is different from the Google and Microsoft buttons on the sign-in page. Those are social sign-in, available to everybody. Enterprise SSO is a configured connection with domain claims, enforcement and role mapping.

Where to find it: Go to Settings, then Single Sign-On (under Workspace).

Who can use this: Admins only, and only when the Enterprise SSO module is enabled. The page does not appear otherwise. Contact Journeybee support to have it turned on.

The two surfaces

SSO is enabled per surface, and the two are independent:

App: your own team signs in to Journeybee through your IdP.
Portal: partners sign in to your partner portal through an IdP.

Portal SSO needs a verified custom domain. Without one, portal SSO sign-ins will not work. See Custom Domains. Partners must also open the portal on your custom domain address to see the single sign-on option: the shared portal address never offers it, so a partner who bookmarked the old address will not find it there.

Each surface is switched on separately by Journeybee, so one can be on while the other is off. The Enabled for line at the top of the page shows which surfaces are on for your company.

On a portal that offers single sign-on, the sign-in card carries a Single sign-on option. Choosing it opens a dedicated view where the partner enters their work email and clicks Continue, and Journeybee sends them to the right identity provider. Back to sign in returns them to the other methods, and if single sign-on is not available for the email they enter, they are told so and can try another.

Where enforcement covers a partner, the magic link and phone code options tell them their organisation requires single sign-on instead of sending anything.

How your team signs in with SSO

The sign-in page starts with the email address. After Continue, Journeybee checks what applies to it: where single sign-on is required the person is sent straight to your identity provider; where it is available but not required they see Continue with SSO (or the connection's own name) and a Use password instead option; everywhere else they get the usual password step.

Someone who belongs to more than one workspace lands on Choose a workspace after signing in. Each workspace shows Open, Sign in or Sign in with SSO: Open enters it directly, while the other two mean that workspace needs its own sign-in first — for example a workspace that requires single sign-on. The company list in the navigation marks those workspaces Sign in required.

Step 1: Register Journeybee with your IdP

The Service provider details panel holds the values your identity provider needs when you create the Journeybee application at their end:

Entity ID
ACS URL (the assertion consumer service, for SAML)
Metadata URL
OIDC Redirect URI (for OIDC providers)

There is also Download SP metadata XML, which most SAML providers will accept as an upload so you do not have to copy fields by hand.

These values are specific to the region your Journeybee workspace is hosted in. Always copy them from this panel rather than from another workspace, a colleague's notes or a provider's generic guide.

Step 2: Create the connection

Click Add connection.

Name and provider

Give the connection a name your team will recognise, such as "Okta", then choose SAML or OIDC.

The provider type is fixed once the connection is created. To switch, delete the connection and create a new one.

Scope

Company-wide: for your own team, available to any user in your company.
Partner organisation: scoped to one specific partner, so that partner's people sign in to your portal through their own IdP.

Scope is also fixed after creation.

Provider configuration

For SAML, supply the IdP's metadata either as a Metadata URL or by pasting the metadata XML.

For OIDC, supply the Discovery URL, Client ID and Client secret.

Additional scopes (optional) adds extra scopes to the request sent to your provider, separated by spaces; openid and email are always included, so most providers can leave it empty, and clearing the field removes them again. Azure AD B2C is the exception: add the app registration's client ID here or sign-in does not complete.

The client ID cannot be changed after creation. You can rotate the client secret or replace the SAML metadata at any time by editing the connection; leaving those fields blank keeps what is already saved.

Step 3: Claim your domains

A connection routes users by their email domain, so you have to prove you own the domain. Verification matters beyond routing: only a verified domain lets the connection create new accounts for it, link an existing account to it, or take an updated email address from your provider. An unverified domain still routes people to the connection, but nothing more.

Add the domain, for example acme.com.
Journeybee shows a TXT record name and value. Add it at your DNS provider.
Click Verify.

DNS takes a few minutes to propagate, so a first Verify that fails is usually just impatience. The connection row shows how many of its domains are verified.

If Journeybee tells you the DNS lookup timed out, your record may well be correct: that message means the lookup itself did not complete, not that the record is wrong. Wait a few minutes and verify again.

Verified domains are re-checked automatically from time to time. If the record cannot be found on three checks in a row, the domain loses its verification, your admins are notified, and the routing and just-in-time provisioning that depend on that domain stop until you verify it again. Put the record back and click Verify. A check that simply times out does not count towards this.

A domain can only be verified by one organisation. If it has already been claimed elsewhere, contact Journeybee support.

Step 4: Choose the settings

Enforce SSO

For a company-wide connection, enforcement requires SSO for every active member of your team, whatever their email domain and whatever their role: Admin, Partnerships and Indirect users are all covered, including Indirect users signing in to your partner portal. Domains are used only to route people to the right connection. For a partner-scoped connection, enforcement applies only to that partnership's portal sign-in.

Once enforced, other sign-in methods, including password, magic link and the Google and Microsoft buttons, stop working for the people covered. There is no admin password fallback, so before enabling make sure everyone affected, including you, exists in your identity provider. If an identity provider outage locks you out, contact Journeybee support, who can switch the connection and its enforcement off after verifying the request.

Turning enforcement on also ends existing sessions that were not established through the connection. Team members who are currently signed in by password or with a Google or Microsoft account are signed out at their next request and have to sign back in through your IdP. Pick a quiet moment and tell your team before you flip the switch.

Just-in-time provisioning

Creates the account automatically the first time someone signs in through the connection. For your own team, a new account is created only when the person's email domain is one your organisation has verified — an address on any other domain is told no account was found, even with provisioning on. With Just-in-time provisioning off, only existing team members and existing partner contacts can sign in; anyone else has to be invited first.

Portal provisioning

When just-in-time provisioning is on for a connection that serves the portal, you choose how new partner contacts may be created:

Approved partnership domains: a new contact is created only when their email domain is an approved domain on one of your active partnerships. Available on company-wide connections.
Trusted IdP mapping: you set the IdP claim name and map each Claim value to one active partnership, so your identity provider states exactly which partnership each person belongs to. Each mapping needs a unique claim value. Available on company-wide connections.

On a partner-scoped connection there is nothing to choose: new contacts can only ever be created for that connection's partnership.

If someone's sign-in matches more than one partnership, they are asked to choose which one to enter.

Default role

The role given to a user created by JIT when no group mapping applies.

Group to role mapping

Set the Group attribute your IdP sends, then map IdP group names to Journeybee roles. Group names are matched case-insensitively, and each group can only be mapped once.

Anyone whose groups do not match a mapping gets the default role.

Step 5: Test, then enable

A new connection is created disabled. That is on purpose: test it first.

Run test opens a new tab, sends you through the IdP, and shows you the profile that was asserted, including the groups. No session is created and nobody is signed in, so it is safe to run against a live connection.

Test works while the connection is still disabled, and it covers both surfaces: a partner-scoped or portal connection is tested with the same Run test button. The surface being tested has to be on for your company; if it is not, the panel tells you so instead of offering the button.

If the test cannot complete, Journeybee tells you why: the domain is not currently authorised for the connection, the connection is disabled or unavailable, the tested identity is not authorised for this company or partner, or the configuration needs checking. A test is held to the same domain rules as a real sign-in, so testing an address on a domain you have not verified fails on the domain reason rather than succeeding.

When the asserted profile looks right, switch the connection to Enabled.

Partner SSO from the partner page

You do not have to start from the Single Sign-On page to see where a partner stands. Open the partner, and the Settings section of the sidebar shows a Partner SSO card telling you whether that partner's portal sign-in connection is configured and enabled, configured but disabled, or not configured at all.

Configure opens the Single Sign-On page focused on that partner: it says it is managing Partner SSO for them and lists only their connection, and a connection you create there is fixed to that partner and to portal sign-in. Once they have one, use Show all to drop the filter and work with every connection again.

The card is shown to admins only, and only when the Enterprise SSO module is enabled.

Managing connections

The connection list shows each connection's name, scope, verified domain count, and its Enabled, Enforce and JIT switches. You can toggle those from the row.

There is no per-connection sign-in link to distribute. People start from the normal sign-in page and enter their email address, and Journeybee routes them to the right connection.

For SAML connections, Journeybee warns your admins by email and by in-app notification 30 days, 7 days and one day before the identity provider's signing certificate expires. Update the metadata at your provider before it does.

Delete removes the connection. Anyone who signs in through it loses that route immediately, so make sure they have another way in first.

What Enterprise SSO does not do

The first release covers sign-in. It deliberately leaves out:

Automatic user provisioning and deprovisioning (SCIM). Removing someone from your IdP stops them signing in, but their Journeybee account stays until you disable it under Team Management.
Single logout. Signing out of your IdP does not end an existing Journeybee session, and signing out of Journeybee does not end your IdP session.
IdP-initiated sign-in. Starting from a tile in your IdP's app dashboard is not supported. People start from the Journeybee or portal sign-in page and enter their email.
Partner self-service. A partner cannot configure their own connection from the portal. You set up partner-scoped connections for them.
An API for SSO settings. Connections, domains and mappings are managed from this page only.

Troubleshooting

The Single Sign-On page is not in my settings

It needs the Enterprise SSO module and the Admin role. Contact Journeybee support to have the module enabled.

Domain verification keeps failing

Check the TXT record name and value against what is shown, and give DNS a few minutes. If the domain is already verified by another organisation, contact support.

Run test seems to do nothing

If a test is refused before it reaches your identity provider, for example because the domain is not verified yet or the surface is not enabled, and you are signed in to Journeybee in the same browser, you are returned to the app home page instead of being shown the reason. Run the test again from a private window, or after signing out, and the message appears.

A user signs in but lands with the wrong role

Run the test and look at the asserted groups. Either the group attribute is not the one your IdP actually sends, or the group name does not match a mapping, in which case they get the default role.

With just-in-time provisioning off, they need an invitation before their first SSO sign-in. With it on, their email domain still has to be verified for your organisation — an address on an unverified domain gets No account found for this email. Verify the domain, invite them, or check they are using the expected address.

The email address asserted by the partner's identity provider must match the email on their contact record exactly. A contact whose Journeybee account was set up with a different address is refused on purpose, so that one person cannot take over another's account. Bring the two addresses into line, either on the contact in Journeybee or in the partner's IdP, and try again.

There is no password fallback while enforcement is on. Contact Journeybee support, who can switch the connection and its enforcement off after verifying the request.

This appears when creating or deleting a connection did not finish cleanly, and it clears once the configuration is recovered. Editing an existing connection does not cause it: sign-in carries on as normal throughout an edit. Contact Journeybee support if it does not clear.

Too many single sign-on attempts

Repeated attempts in quick succession are throttled on purpose. Anyone who sees this should wait a moment and try again.

Portal SSO requires a verified custom domain, and partners have to be using it. Check Settings, then Portal Settings, confirm the domain shows as Live, and confirm the partner is opening the portal on that address rather than the shared one.

Good to know

Provider type and scope are locked after creation. Everything else, including secrets and metadata, can be rotated in place.
Test before enabling, every time. The test shows you the real asserted profile rather than making you guess from a failed login.
Company-wide enforcement covers every active member of your team, whether or not their email is on a claimed domain. Domains only decide which connection a sign-in is routed to.
Partner-scoped connections let a large partner use their own IdP for your portal, which is often what unblocks an enterprise partner's security review.
Journeybee updates a person's email address to match your identity provider only when both the old and the new domain are verified for your organisation. Otherwise their existing address keeps working.

Company Profile: the sign-in methods available to your team.
Custom Domains: required before portal SSO will work.
Portal Settings: where your custom domain and portal access options live.
Team Management: the roles your group mappings assign.
Partner Portal: how partners sign in generally.