Introduction to Single-Sign-On (SSO)
To stay on top of their game, modern companies use a variety of software tools (like Businessmap!) to help them work better and more efficiently. However, as the number of tools increases, so do the passwords every user has to remember as well as the load on system administrators and IT have to support.
A remedy for this is Single Sign-On (SSO) – a technology that allows a company to maintain a centralized Identity Provider server that all other tools communicate with in order to authenticate and authorize users. SAML (Security Assertion Markup Language) is the most widespread SSO standard in the enterprise world. This is why Businessmap provides you with the ability to integrate with your company’s SAML 2.0 Identity Provider and eliminate the need to remember all those passwords!
*The rest of this article assumes that you are a user with Account Owner privileges in Businessmap, so you have the proper permissions to modify settings in your Identity Provider and are familiar with the SAML 2.0 protocol.
How to Configure SAML Single Sign-On in Businessmap
Here are the steps required to connect Businessmap with your Identity Provider (IdP):
- In Businessmap, open the Administration panel and go to Integrations.
- There, you will find a section called Single Sign-On.
*Open the image in a new tab to get a closer view.
- In the first field, you need to enter the Entity Id of your Identity Provider. Consult the documentation and/or metadata of your IdP if you don’t know it.
- The second field is IdP Login Endpoint. Here, you should enter the URL to which Businessmap should redirect login requests.
- (optional) Similarly, IdP Logout Endpoint is the URL to which Businessmap should redirect logout requests. This is an optional field which means that you need to fill it in only if you want to enable Single Log-Out, too. What this means is that when users log out from Businessmap they will be logged out of your IdP (and all other tools connected with it). Vice-versa – when users log out from your IdP, they will be logged out of Businessmap, too.
- In the last field, paste (without the start and end markers) the X.509 certificate that your IdP uses to sign data.
- (optional) The first from the fields on the right is Attribute name for Email. If the NameID attribute in the authentication statement holds the user's email, you don't need to fill in this field. However, if NameID contains something else, we need an extra attribute in the authentication statement to obtain the email which is associated with the user's account. If you don’t know that, consult your IdP’s documentation and/or settings.
Note: The Attribute Name could be as simple as "user.email" or a more complex URI like this: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" - (optional) The next two fields are also optional. They represent the names of the attributes that hold the user’s first and last name. This information is utilized when a user logs in for the first time in Businessmap. An account is automatically provisioned for that user (if you have turned on the respective setting) and, if the above-mentioned attributes are present, the user’s name will be filled in the account.
-
Below the fields, you will find a dropdown from which you can select among a variety of options that cover different log in use cases:
- Disable Businessmap login, only SSO login is applied for all users
- Allow Businessmap login for users with Account Owner privileges
- Allow Businessmap login for users with Manage Integrations privileges
- Allow Businessmap and SSO login for all users
Note: This option is used for allowing access of external users to your Businessmap Account. See for more information at the bottom of this article.
- There is a checkbox on the left "Automatically create a Businessmap user for the unregistered emails upon login" that secures controlled access. If the setting is checked, it automatically creates a Businessmap user for the unregistered emails upon login. When the setting is unchecked, you need to first send an email invitation to the user in order to be able to log in to the system using the SSO flow.
-
There is also a switch button called 'Enable User De-provisioning' - this enables/disables the automatic de-provisioning of users using the SCIM. When enabled, the system will populate the SCIM Base URL (should be something like https://{subdomain}.kanbanize.com/scim), and there should be a unique SCIM bearer token that can be re-generated when needed and is used when configuring SSO. If the token is regenerated, the old one becomes invalid, so this needs to be updated in all systems where this token is used. Detailed instructions on how to configure this can be found in the dedicated articles for the supported IDPs.
- There is another checkbox called "Sign outgoing messages". Turning it on will result in Businessmap signing authentication and log-out requests, logout responses, and the metadata. You will find the public certificate in the metadata (link below)
- Click Save Settings, with which the configuration of SAML in Businessmap is complete.
- After you have configured your IdP (info provided below) come back to this screen and toggle the button next to "Single Sign-On" to enable it.
Now you need to set up the Identity Provider. The steps will differ for every particular IdP so, once more, you will need to consult its documentation.
If your IdP supports automatic configuration with metadata you can find it at https://{subdomain}.kanbanize.com/saml/metadata
If not - here is the information that you will need (concrete values can be extracted from the metadata):
- The Entity ID of Businessmap is https://{subdomain}.kanbanize.com/ — replace {subdomain} with your company’s custom Businessmap subdomain, e.g. https://yourcompany.kanbanize.com/ and make sure to include the / at the end.
- Assertion Consumer Service (ACS) endpoint (or the URL where the IdP will redirect after successfully authenticating and authorizing the user) is https://{subdomain}.kanbanize.com/saml/acs
- Single Logout Service (SLS) endpoint is https://<subdomain>.kanbanize.com/saml/sls
- RelayState is /ctrl_login/finish_saml_login
When the configuration has been completed, the users that you have provisioned to use Businessmap will be redirected to your IdP’s login page when they try to log in. Upon successful authentication and authorization, they will be redirected back to Businessmap and live happily with one less password in their lives!
How to provide access to external users (that are not part of your IdP)
When you have third-party consultants or contractors that are not part of your IdP, one possible solution is to allow both access via SSO and without SSO.
That way, external users will need to go through the central login page located at:
https://businessmap.io/user-login
Internal users (members of the IdP) will be able to utilize the SSO flow by going through your account's dedicated login page, i.e.:
https://subdomain.kanbanize.com
The Account Owners of the account will need to send invitations to the external users via the Administration Panel. They will receive an invite link to register and set up their Businessmap credentials.
Note: If the option for login from both systems is not enabled, the invited external users will be able to access the system only the first time they are invited, and after logging out, they will be forced to use the SSO only. This could be used as temporary one-time access only for consultants or 3rd party users that do not need to re-enter the system.
If you have any trouble don’t hesitate to contact us at support@businessmap.io.
These were the general steps for configuring SAML with any Identity Provider. In the related articles below, you can find the specific step-by-step tutorials for enabling SSO with Azure Active Directory, OneLogin, and Okta as your IdP and for managing user provisioning with SAML Integration: