SAML single sign-on

4 minute readSecurity

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.

Users are able to sign in to multiple software applications using the same login details with SAML.

CloudBees Feature Management uses the SAML 2.0 protocol to implement single sign-on.

CloudBees Feature Management IdP support

CloudBees Feature Management SAML supports the following IdP’s:

  • Onelogin

  • Okta

  • Active Directory Federation Services (ADFS)

Configuring SAML for teams

  • To enable SAML for teams, you need to be an application Admin (to see your team admins go to Account > Team Managment and look at the permissions column). At the top of the Account > Team Managment screen, there is a SAML action button and once activated, you will be prompt to enter:

    • Team Login Prefix

    • IdP metadata

    • SAML Strict Mode

Team Login Prefix

This is the team entry point using SAML.

  • When SAML is on, in order to login to the CloudBees Feature Management dashboard, the link is:<team-login-prefix>

  • This will also be part of the callback from the used IdP (ACS URL, which should be set on the IdP side):<team-login-prefix>/callback.

CloudBees Feature Management URL is case sensitive

The team-login-prefix is part of the url, and as such should be set on the Idp side exactly the way it is written on the Saml Configuration screen.

For example, if your Team Login Prefix is 'teamName', the URL will be:

IdP metadata

Metadata obtained from the IdP.

SAML Strict Mode

All non-admin users must use SAML to log in to CloudBees Feature Management. Any existing CloudBees Feature Management username/password, or alternatives such as Google OAuth, will not be valid. Note that Admins retain access to alternatives in case you need to fix issues with SAML.

Inviting new team members using SAML

If you have SAML Strict Mode enabled, invited users will receive a new invitation email that bypasses the CloudBees login page and sets up the SAML connection.

SAML email invitation

Once users complete the invitation procedure, they can verify their SAML connection is working by going to their Account page and checking the SAML Status section has a Connected state.

SAML status connected

If the invited user did not receive their invitation, or the SAML IdP metadata has changed, administrative users can re-invite users with the Resend SAML Invite button next to the user’s email under Team Management. This is useful especially if you have SAML Strict Mode enabled.

SAML invitation

If SAML Strict Mode is not enabled, users must create a username and password and will not be directed to login via SAML. Users can then enable SAML support at any time by going to their Account page and clicking Connect SAML.

Enable SAML for existing users

To configure SAML for individual users within a team that has it enabled, the user must perform the following steps:

  1. Under User > Account, they will see a SAML Status box.

  2. Instruct the user to click on Connect SAML to establish the SAML link. When they click Connect SAML, Connect to your IdP appears.

    Connect to your IdP modal
  3. When the user clicks OK they will receive an email confirmation to reset their password.

  4. The user then proceeds to their email inbox and follows the password reset instructions to complete the SAML connection.

  5. After the user clicks Reset password in their email and completes the password reset, the SAML Status should now show Connected.

    SAML status connected

If the user has changed IdP or some other aspect of their account, they can click on Reconnect SAML to set up a new SAML connection which repeats the same password renewal process.

Disable SAML

To disable SAML for the application, go to Account > Team Managment as an admin user and click on the SAML button.

SAML and CloudBees Feature Management Permissions

Even when using SAML, a user must be first invited to the CloudBees Feature Management platform. In the case where SAML is disabled, users would still be able to log in to CloudBees Feature Management using their email and password.

How SAML with CloudBees Feature Management works

CloudBees Feature Management SAML authentication is SP initiated. CloudBees Feature Management integrates with an IDP provider by linking a CloudBees Feature Management user with an IDP user. The link is done using the SAML’s NameIdFormat which is required. The Active Directory default setting usually does not include NameIdFormat and has to be added manually.

This link between a CloudBees Feature Management user and the IDP user is created using the following methods:

  • CloudBees Feature Management user invitation email

  • From the User > Account page, click Connect SAML (or Reconnect SAML) from SAML Status

Users that were invited after SAML configurations were set (by an admin), will need to click the link in the invitation email.

Additional examples that require resetting SAML include:

  • NameIdFormat value was changed (value for a specific user, only this user will have to reset the link)

  • NameIdFormat field was switched on the IDP side (each user will have to reset the link).

  • Switching IDPs (each user).

  • Clicking the Connect SAML (or Reconnect SAML) from SAML Status on the User > Account page.