Single Sign On
Some organisations need to access Smartabase using single sign on (SSO). This can be implemented so that Smartabase pushes security considerations such as password policy enforcement and multi-factor authentication (MFA) to the SSO provider. This includes the likes of using Microsoft Azure AD as a SSO provider whereby Smartabase interacts with the Azure Portal. The user would go into their SSO hub and then launch Smartabase which would automatically load. See below for more on this:
It is important that an organisation understands that as soon as the SSO credentials are set up on the Administration site anyone in the organisation can use SSO to log in. However, to enforce the login through the SSO provider ONLY, we can effectively disable logins through the Smartabase application either for all users in the organisation OR for some users. Specifically:
To enforce log in through the SSO provider for the entire organisation this is done by setting the "Requires SSO for Login" on the Builder site in the Edit Application Details.
To enforce log in through the SSO provider for select users in the organisation, this can done in the Administration Site on a Role by Role basis by setting a Role to "Requires SSO for Login"
See below workflows and for how to enable this depending on your use case.
Once the credential are set up, it is enabled for ANY user who has the matching email.
Administration Site: Set up the SAML credentials
A new module called SAML (short for Security Assertion Markup Language), which is an open standard for exchanging authentication and authorization data between parties such as between an identity provider and a service provider (such as Smartabase) is now available for use on the Administration site. Note, we ALSO have the Lti Standard which can be used via the Lti Module on the Admin Site.
Click to open.
Enter in the special SAML configuration information.
Fusion Sport will work with your system administrators to provide the information needed to add into the SAML credentials information, including the:
- SAML Provider Name (this is the name that appears on the login SAML selection screen, so it MUST be entered and it MUST make sense to the organisation). It is called Azure in this instance.
- Provider Login: This is the login url for the portal (e.g. Microsoft Azure Hub)
- Configuration CSV: which includes important codes and other information.
See the information below:
##Configuring your SAML Identity Provider to work with your Smartabase site##
In order to configure Smartabase to work with your SAML Identity Provider (IDP) you will need to provide some information about your Smartabase site to the IDP.
The first thing you need to provide is the Identifier (sometimes called Entity Id) of your Smartabase site. This is just the url to the site followed by the "App Type". App type is used to distinguish between the mobile (which loads up the site via the m.html extension) and main version of the site. You use "mobile" if you want the mobile site or "main" for the non-mobile site. So if we had a site at https://abcd.smartbase.com/somesite/ then the two possible Identifiers are:
Note that I refer to the "somesite" application on the abcd.smartabase.com server specifically, as every Application on a Smartabase server has its own relationships with identity providers.
Next you need to provide the Reply URL (sometimes called Assertion Consumer Service URL). This URL is simply the Identifier+/SAMLsso/acs, so for our somesite application on the abcd server, the reply url looks like:
Your IDP will need a RelayState setting to initiate the SMAL login process from it's own app portal. The RelayState value is the App type. Either "mobile" or "main" (no quotation marks). This needs to match the app type used in the identifier.
Finally you will need to set the IDP to use the user's email address as their User Identitier (sometimes called NameId).
We perform a look up based on the provided email to authenticate the user, so all users will need to use the email their IDP reports as the email address for their Smartabase account. Note that if your IDP reports an email with specific capitalization, we will search for that specific capitalization.
##Configuring your Smartabase Application to work with your SAML Identity Provider##
There is a few settings site administrators need to provide in a Configuration CSV in order to enable SAML SSO. You can find the SAML Configuration CSV in the SAML Credentials page in the Administration site for your application.
The CSV field is a simple comma-separated text value where you list lines formatted like this:
You can't have more than one key-value pair per line, but a setting's value can be split over multiple lines if you like.
Listed below are the necessary fields.
#Certificate and Key#
You must provide a self-signed certificate and key to secure the SAML SSO process.You can read about generating these via openssl here:https://www.ibm.com/support/knowledgecenter/en/SSWHYP_4.0.0/com.ibm.apimgmt.cmc.doc/task_apionprem_gernerate_self_signed_openSSL.htmlOr you could try this webtool for generating them:https://www.samltool.com/self_signed_certs.php
As always, it is important that you keep your private key a secret.
Once generated, these values can be set via:
#Identity Provider Information#
Your IDP will provide you with the following information:
saml2.idp.entityid,<entity id provided by your identity provider>saml2.idp.x509cert,<certifcate provided by your identity provider>saml2.idp.single_sign_on_service.url,<single sign on url provided by your identity provider>saml2.idp.single_logout_service.url,<single logout url provided by your identity provider>
(< and > not included)
Different IDPs wil require the use of either HTTP-Post or HTTP-Redirect in their SSO or SLO process, if uncertain, use the following:
Some IDPs will provide a SLO response URL separate to the already mentioned SLO URL, you can optionally list that as:
saml2.idp.single_logout_service.response.url,<optional single logout response url provided by your identity provider>
(< and > not included)
You can prefix any given setting key with an app type (ie "main" or "mobile") and that setting will only be used depending on the RelayState (and therefore, whether you're using mobile or non-mobile). Settings without a app type prefix are overriden by app-type specific settings. So if the RelayState of the incoming SAML login was "mobile" and the CSV contained the three lines:
Then foo2 would be used as entityid. If the RelayState was "main". It'd default to foo1.
This allows you to specify unique configuration between mobile. This might seem a little unusual but the main motivation was so that you can list both a mobile and non-mobile site launcher in your app portal, but your app portal will often use unique certificates per launcher meaning that you will need a unique certificate setting between main and mobile.
Once you save the information, you will return to the home page on the Administration site and a confirmation that the configuration set is Saved will appear.
WARNING: as soon as SAML is enabled, user will be able to login using their SSO credentials. If you are enforcing SSO for all or some users, make sure user's have sufficient notification to prepare for this as the specified users will ONLY be able to log in from their SSO.
To enforce SSO for the entire organisation (e.g., each user on Smartabase to login using their SSO provider), this is enabled on the Builder site in the Edit Application Details.
Once enabled, this means that ALL user on your Smartabase site MUST go through the SSO provider to login. Note, it can also be enforced on a Role by Role basis, which means only the user in that Role are required to use SSO to launch Smartabase. Ensure you understand your organisation's needs when setting this restriction up.
To enforce SSO for user assigned to a Role, go to the Administration Site and open the Role that requires SSO
The capability called "Require SSO for Login" has been added to the Role structure. Tick to enable it. Then save the changes (this is ONLY designed to be used when it is NOT enabled on the Application Details as enabling it in the Builder Site automatically enforces it for every user on Smartabase).
By default it is unticked, which means user follow the normal login process whereby they launch Smartabase and use their username and password.
When it is ticked, this means the Users who are in this Role will be required to login to their SSO provider (e.g. organisation hub) to launch Smartabase.
When SSO is required, this means the user will need login to their SSO provide (e.g., their organisation hub) and from within that the Smartabase app can be launched.
Note, the mobile and android Apps and the installed offline app CANNOT be launched using SSO. The SSO will be used to launch the link to Smartabase from a URL.
An example of the Azure Hub and launching the Smartabase (main) app in the browser window.
It auto logs in based on matches in the email between the Azure Hub and Smartabase
The image above shows that the Smartabase site was launched from the Azure provider without having to enter a username and password. This is supported across multiple browsers.
Not, because we match on email, it is important to know that NO two users in Smartabase can have the same email address.
An example of the Azure Hub and launching the Smartabase m.html (mobile) app in the browser window.
The Azure platform does NOT support Logout, so IF you logout of the azure platform, this will NOT log the user out of the Smartabase App. They will need to manually do that.
Users SHOULD always follow best practice and log out of Smartabase when they finish their session.
WARNING: If SSO has been enforced and the user tries to login online via an internet browser, they will not be able to successfully login.
Normal login is not supported when SSO is enforced.
Hence, if a user tries to login, the user will be prompted to login using their SSO provider set up in the SAML Configuration. The provider/s appear for selection and can be launched (this the link added to the "Provider Login Url" when setting up SAML on the Administration Site).
NOTE: The Smartabase password is no longer relevant as login is through SSO. So users MUST be aware that if they change a password on the Smartabase account it will not flow through to the user's SSO login procedure.
Administrators MUST be aware of the issues that IF a user is given access to change their email, if the email is changed in their Smartabase account and not in the SSO provider, then the user will NOT be authenticated to login to Smartabase as the emails do not match.
The example here shows that the email of the user was changed in Smartabase. However, if was not updated in microsoft azure. When Smartabase was launched from Azure, the login failed as the email did not match.
If there is a difference between authenticated passwords on Azure AND Smartabase the following error occurs:
" No active user was found matching your SAML identity. Please contact your site administrator."
The administrator of the organisation wil need to check the emails are ALWAYS the same.