Configure SSO in the Staffbase Studio

Learn how to configure SSO for the Staffbase platform.

Staffbase Email
beta

In this article, you will learn how to set up using the or protocol in the Staffbase Platform.

You can set up the configuration in three steps:

  1. Prepare for integration in your IdP
  2. Add SSO configuration in Staffbase Studio
  3. Test the configuration

Before configuring SSO in Staffbase, complete the setup in your IdP.

Prerequisite:

Staffbase provides documentation for the following commonly used IdPs:

Refer to the relevant guide for your IdP and follow its documentation to complete these steps in your IdP:

  1. Create a new application or integration for Staffbase.
  2. Select SAML or OIDC as the SSO method.
  3. Configure the SSO settings according to the selected protocol.
  4. Collect the configuration details required to complete the setup in Staffbase Studio.

After preparing your IdP for integration, you can now add a new SSO configuration in Staffbase Studio.

  • You have the role of an administrator in the Staffbase Studio.
  • The SSO self-service feature is activated in your Staffbase platform. If not, contact Staffbase Support or your Customer Success Manager.
  • You have all the information required to add the configuration.
  1. In the Studio, navigate to Settings > SSO Configuration.
  2. Click Add SSO Configuration.

  1. In the Configuration Identifier field, provide a name to identify the configuration.

    The Configuration Identifier is used for internal reference only and is not displayed to users.

  2. In the Sign-In Label field, provide the text for the sign-in button.

  3. Under Select SSO method, select one of the following SSO protocols:

  • SAML
  • OIDC

Once you have entered the configuration identifier, you can retrieve the Service Provider (SP) data required for your IdP configuration.

You need to get the data from your IdP.

If your IdP requires importing Staffbase metadata first, you can access the SP Metadata URL after saving the configuration. Since the configuration requires both an Endpoint URL and a Metadata URL, you may initially enter placeholder values (e.g., https://to.be.replaced) to save the configuration. Once you have the correct values, replace the placeholders with the actual Endpoint and Metadata URLs.
  1. In the Endpoint URL field, enter the URL to which Staffbase sends authentication requests to your IdP.
  1. In the Metadata URL field, enter the URL to the IdP metadata file containing necessary SAML configuration information.
  2. Optionally, in the Issuer / Entity ID field, enter the unique identifier for your IdP.
  3. Optionally, configure the following settings as needed:
  4. Click Save.
  1. In the Endpoint URL field, enter the URL to which Staffbase sends authentication requests to your IdP.
  1. In the Client ID field, enter the client ID of the application you registered in your IdP.
  2. In the Secret field, enter the client secret of the application you registered in your IdP.
  3. In the External Attribute Name field, select one of the following attributes to be mapped to the external ID of a Staffbase user:
    • email: The user’s email address. It can serve as a unique identifier if email addresses are consistent and verified.
    • perferred_username: The username used for login. It’s typically more readable but may not be unique across systems.
    • sub: Stands for subject and is a unique, stable identifier assigned by the IdP. It is the most reliable way to identify a user across systems.
  4. Optionally, configure the following settings:
  5. Click Save.

These settings are optional and apply only to SAML configurations.

  1. In the Name ID Policy Format field, enter the NameID element format required by your IdP, as defined in the SAML 2.0 definition.

  2. In the AuthnContext Class Ref field, enter the AuthnContextClassRef required by your IdP, as defined in the SAML 2.0 definition.

  3. Enable the Add Domain Hint toggle if your IdP supports domain hints to streamline the login process for users from specific domains.

The domain hint in Staffbase adds an IDPEntry to the IDPList within the Scoping element, as defined in theSAML 2.0 definition.

For Entra ID, the domain hint is typically used to direct users to a specific configuration.

  • In the Domain Hint Provider ID field, enter the URL provided as the entityID in the SAML Metadata.
    Example for Entra ID: https://sts.windows.net/{tenant-guid}/
  • In the Domain Hint Name field, enter the domain used for the domain hint. Example: mydomain.com

Use this action for any of the following:

  • You uploaded incorrect metadata
  • The IdP returned invalid metadata
  • The IdP metadata has changed

Clearing the cache forces a fresh fetch before the default 7-day time-to-live (TTL) and helps prevent SSO issues caused by stale or invalid metadata. This does not change any other SAML settings.

  1. In the Studio, navigate to Settings > SSO Configuration.
  2. Click on the action menu and choose Clear Metadata.
This option is only available for SAML configurations.
  1. Click Clear Metadata to confirm the action.

Use the available toggles to turn on additional SSO settings:

  • Allow User Creation: Automatically create a Staffbase user account when someone logs in via SSO for the first time. This is also commonly known as Just-in-Time provisioning (JIT).
    Allow User Creation is only available when using Staffbase Email as a standalone product. In combined setups with the Intranet or Employee App, create users manually or use another user management method. Contact Staffbase Support or your Customer Success Manager for more information.
  • Disallow User Passwords: Enforce SSO sign-in only.

You can optionally configure user management settings to map custom attributes from your IdP to user profiles in the Staffbase platform based on profile field information. This is useful if you want to map additional user information based on your SSO configuration.

  1. Create or identify a profile field in the Staffbase Studio to store the data received from your IdP.
  2. Locate the unique profile field ID.
    In the profile field settings page in Staffbase Studio, find the unique Profile Field ID for the destination field. Staffbase uses this technical identifier (for example, employeeid) to establish the mapping.
  3. Identify the SSO claim name.
    In your IdP, find the attribute name that contains the data you want to sync. This attribute is the SSO Claim Name.

Learn more about profile fields in Staffbase Studio.

Verify the SSO setup by signing in through your configured method.

  1. In a web browser, enter your Staffbase platform domain URL. For example, https://mycompany.com.
    The Sign In page opens.
  2. Click the new SSO sign-in button with the label you configured.
    You are redirected to your IdP’s sign-in page.
    If you don’t have a valid session with your IdP already, enter your IdP credentials.
  3. If the SSO configuration is successful, you are redirected to your Staffbase account.

You have successfully configured SSO for your Staffbase platform.