SSO

Single sign-on (SSO) lets your team log into Guidebook with the credentials they already use for work, instead of creating and managing a separate Guidebook account. This article walks through how SSO works in Guidebook, the configuration options available, and what is needed from your IT team to get set up.

What is SSO?

SSO (single sign-on) lets your team log into Guidebook with the credentials they already use for work, school or at your institution, such as the same login they use for email or other internal tools, instead of creating and managing a separate Guidebook account.

SSO may be a good fit for your organization if you want:

• Centralized user management: When someone joins or leaves, your IT team can handle it in a single system instead of updating Guidebook separately. This is the most common reason organizations adopt SSO.
• Stronger security: Your IT team controls the password policy, and any 2FA or MFA configured through your identity provider carries over to Guidebook. Guidebook does not offer these features natively, so SSO is the way to extend them to your guides.
• Fewer passwords for your users: One login covers everything they need.

Gated vs. Non-Gated SSO

When SSO is enabled on a Space, you can choose whether to gate it, meaning users must log in before they can see anything at all.

SSO is configured at the Space level, not the App level. For single-guide or multi-guide branded Apps, this distinction does not affect configuration since each App contains only one Space. The Guidebook flagship app contains many Spaces, some of which are gated and some of which are not.

Gated Spaces

Users hit the splash screen and immediately get the SSO login. They cannot see the home screen, browse guides, or do anything else until they have authenticated.

Non-Gated Spaces

Users can browse the home screen without logging in. Whether they can open a guide depends on its privacy setting.

To log in, users tap the profile icon in the top-right corner of the App.

Logging in is technically optional in Non-Gated Spaces, but users will need to do it to use features like check-in, chat, photo sharing, or posting to the Interact feed.

Non-Gated Spaces can also be configured to let users register with a regular Guidebook account, giving them the option to log in with SSO or a Guidebook account.

Guide Privacy Settings

Guidebook offers three App types (single-guide branded, multi-guide branded, and the Guidebook flagship app), three Guide privacy settings (public, passphrase, invite-only), and two gating options (gated, non-gated). The sections below describe how each privacy setting works across these combinations.

Public Guides

Anyone with access to the Space can find and download these by name.

For multi-guide Apps and the flagship app, the Space may be gated, but once a user authenticates they can access any public Guide inside it.

Single-guide branded Apps only support public or Invite-Only Guides.

Passphrase Guides

These do not appear in the Space unless a user has the passphrase. Once they enter it in search, the Guide appears in their My Guides tab.

Like public Guides, multi-guide and flagship Spaces may require users to authenticate before they can download a passphrase Guide.

Passphrase Guides are not supported in single-guide branded Apps, as there is no UI for entering a passphrase.

Invite-Only Guides

Only users who have been specifically invited (through Builder or the API) can access these. They must be logged in.

For invite-only to work alongside Gated SSO, your IdP must return an email address and domain verification must be configured on Guidebook's end. Invited users must also be added with the SSO option enabled. See Inviting Users with SSO for details.

In single-guide branded Apps, Guide data is pre-bundled into the App itself, so the content cannot be fully hidden. A non-invited user could see the content if they authenticate, but they would not be able to add or change anything.

For multi-guide Apps and the flagship app, users must be both signed in and invited for the Guide to appear in their search.

SSO Configuration Requirements

Guidebook supports SAML 2.0 for SSO. If your organization uses a different framework, your IT team should confirm compatibility before configuration begins.

The following items are required from your IT team. Items marked required are non-negotiable; the rest help Guidebook configure the integration correctly for your setup.

• IdP URL: Where Guidebook will send users during login. Required.
• IdP Entity ID: The unique URL that identifies your SAML identity provider. Required.
• IdP public x.509 Certificate: Required.
• Test account: Username and password. Required.
• Signed authnRequests: Does your IdP expect signed authnRequests?
• Signed SAML Responses: Does your IdP sign SAML Responses?
• Unique email addresses: Does your IdP send unique email addresses in the SAML response?
• Multi-factor authentication: Does your IdP use MFA?
• Session length: How long should users stay signed in (for example, 30 seconds, 36 hours, 3 days)? The default is 5 days.

If your IdP does not send unique email addresses, the integration can still be set up, but users will not be identifiable in Builder. They will appear as anonymous accounts with a generated email like random_string@example.com. Contact your Account Manager to discuss options if this will be a problem for your team.

The following details are typically owned by your Guidebook admin rather than your IT team, but they are still required to complete configuration:

• Gating: Should access to the Space or App be gated or non-gated?
• Go-live date: What is your target go-live date for production? Does it need to flip on at a specific date and time?

The expected SAML attributes are:

• email: urn:oid:0.9.2342.19200300.100.1.3
• first_name (givenname): urn:oid:2.5.4.42
• last_name (surname): urn:oid:2.5.4.4

To test on a staging environment before flipping production live, contact your Account Manager. The required values will be needed for both environments.

Guidebook's Service Provider Details

These are the values your IT team will need when configuring the integration on their side:

• Assertion Consumer Service: https://builder.guidebook.com/api/auth/saml/assertion-consumer-service/?format=json
• Entity ID: https://builder.guidebook.com
• Service Provider MetaData: https://builder.guidebook.com/api/auth/saml/metadata/

Logging in to Builder with SSO

Once the integration is complete, your team can log into Builder via SSO. Each Space has its own dedicated login page at:

https://builder.guidebook.com/#/login/space-short-name

The space-short-name piece is whatever your Space uses for its landing page short name. For example, the Guidebot login page is https://builder.guidebook.com/#/login/guidebotsso.

Anyone invited via email will receive the correct link directly in their invite, so they do not need to remember the URL.

Domain Verification

Domain verification means users must log in with an email from a specific list of verified domains. It is useful when you want to ensure that only your own people can get into a Space, for example only users with a @yourcompany.com email address.

Domain verification is required when using:

• Invite-only Guides with Gated SSO: When your IdP returns an email address. See Guide Privacy Settings.
• Auto-merge: Auto-merging an SSO account with an existing Builder account that has the same email.

To set up domain verification, contact your Account Manager.

Inviting Users with SSO

When inviting users to an Invite-Only Guide on a Space with Gated SSO, the Import as SSO Users toggle must be enabled in the invite flow. When enabled, invited users will not receive a temporary password for a Builder account. They will be required to log in using their SSO credentials instead.

The toggle is available from both the Invite manual flow and the Bulk Invites CSV import flow, and is off by default.

Manual Invites

From the guide dashboard, open Audience Management and click Invite. Fill in the user's details, then enable the Import as SSO Users toggle before clicking Save or Send invitation.

Bulk Invites

From the guide dashboard, open Audience Management, click Bulk invites, and select CSV/Excel import. Download the template, complete it, and upload the completed file. Before uploading, enable the Import as SSO Users toggle in the Email options section.

For details on the rest of the user invite process, see Invite Your Users.

FAQ

Which attributes does Guidebook require?
Email, first name, and last name. If your IdP cannot send email as a unique identifier, the integration can still be set up, but Guidebook will need to know what your unique identifier is. A few Builder features (such as Audience Management and User Invites) will not work without an email.

Can other attributes besides first name, last name, and email be mapped to a user in Builder?
Not currently. Anyone with Builder access can update their own account info on the account configuration page, just like any other Builder user.

What happens if a user already has a Builder account with the same email they are using for SSO?
If domain verification is set up for your IdP, the two accounts are auto-merged. The user can then log in either with their SSO credentials (in Spaces where their SSO provider is set up) or with their Builder credentials. Your IdP must return email addresses and domain verification must be configured for this to work.

Does the user list look any different for SSO vs. non-SSO guides?
No, it looks the same. Behind the scenes, Guidebook creates a Builder account for SSO users.

Can a Non-Gated SSO Space be configured to only allow SSO logins (no Builder login option)?
Yes.

Can SSO be used to gate access to Builder?
Yes, as long as Builder logins are disabled and SSO is configured on the Space.

If both Builder logins and SSO logins are enabled and a user's SSO access is revoked, can they still get in via Builder's password reset flow?
Yes. They will still be able to access everything in that Space through their Builder account, so Builder logins should be disabled entirely if SSO is being used for offboarding control.

If multiple opportunities under the same account use SSO, are they billed separately?
If credentials are all verified against the same source, no. One group can share the cost internally.

Still have questions? Reach out to the Guidebook team at support@guidebook.com for help.