Customers have the option to use Single-Sign-On (SSO) authentication for BriefBuilder.
For those unfamiliar with the term: SSO is an identification method that allows people to log into multiple applications with one set of credentials. You only have to sign in once.
This article explains how to use SSO in BriefBuilder, first explaining how to log in, and then how to set it up.
Please note: SSO is only available for customers with a Company Bundle or Enterprise subscription. See here for an overview of the different subscription types.
Logging in using SSO
If SSO has been enabled for your environment, a specific login page must be visited to log in using SSO. This URL looks like this:
https://app.briefbuilder.com/login/sso/<your-company-identification>.
The exact URL should be provided to you by your organisation.
After using this URL once, we will remember this associated SSO. On the regular login page, a second login button will appear (see below), allowing you to log in directly using SSO.
Assuming that your account does not yet exist in BriefBuilder, it will be created automatically when logging in. However, this newly created account will have minimal permissions and will not have access to any project models yet.
To get access to project models, you must contact the person in charge of your company’s BriefBuilder environment. If you don’t know who to contact, you can use the Request access button to contact your environments’ administrators.
In your request, specify the project model you wish to access and the role you are requesting. The administrators will then review your request.
SSO for your environment
When considering SSO for your BriefBuilder environment, you must take the following considerations into account:
Protocols
BriefBuilder supports SSO using the OpenID Connect on top of the OAuth2.0 protocol. The SAML(2) protocol is not supported. If your organisation is using a Microsoft Azure AD you can make use of the OpenID connect protocol.
SSO and password authentication
SSO may be used in conjunction with password authentication. For example, your organisation’s users may be required to log in using SSO, while a (sub)contractor may be able to log in using password authentication, as they do not have any accounts in your central user directory. You may also request to disable password authentication altogether.
SSO and 2FA
SSO and 2FA can be used together in the following manner. If you enable SSO, your authentication provider (like Microsoft Azure AD), may require 2FA for SSO users. If you also allow password authentication, we can enable 2FA for those users. Read more about 2FA in BriefBuilder here.
Requesting SSO
If you wish to enable SSO authentication for your environment, please email our support team or your account manager with this request. Please provide us with the information below and we will in turn provide the required redirect URI.
- Client ID
- Client Secret
- The .well-known URL or the following details:
- Client Authentication Method: client_secret_basic / client_secret_post / client_secret_jwt
- Requested scopes: (most likely: openid,profile,email)
- Authorization URI
- Token URI
- User Info URI
- JWK Set URI
- Keep password authentication enabled? yes/no
Migrating existing BriefBuilder users to SSO
If you already have a number of users in your environment and later on decide to switch to SSO, it is important to understand what will happen with the existing BriefBuilder user accounts.
After SSO is configured and enabled, and users start logging in through SSO, we will initially try to match those users to existing users in your environment. This matching is done based on the preferred username OIDC token claim against the BriefBuilder username (which may be different from the user’s email address). In order to have a smooth migration, it is therefore required to align these usernames beforehand. The BriefBuilder usernames can be managed by administrators as described here.
Provisioning users
When using SSO it is not required to provision users in the BriefBuilder environment. You can however predefine all users in BriefBuilder. One reason to do this is to be able to provide the right environment and project roles before users initially login.
When manually adding users, or importing them through Excel as described here. It is imported to note that users from SSO will be matched based on the username in BriefBuilder. It will be matched against the preferred username OIDC token claim.
Troubleshooting
If you can no longer log in with your old (‘pre- SSO’) account credentials, your organisation has probably disabled the traditional password authentication. If this is the case, you can only log in using SSO, and no longer use your old BriefBuilder username and password.
The same happens when you have successfully logged in using your organisation’s SSO solution. Once you have used SSO, you will not be able to log in to BriefBuilder using your old BriefBuilder credentials (even if other non-SSO users can still do that).