This article takes you through the steps for setting up Single Sign-on (SSO) in Uptrends. Before you consider setting up Single Sign-on, please review these starting points:
- You need to have access to a third party Identity Provider product that lets your organization use Single Sign-on. This IdP will be the central hub for your users to get access to Uptrends and other apps. Uptrends uses the SAML 2.0 protocol for Single Sign-on, so any IdP that supports SAML 2.0 should work. Please review the documentation of your IdP that describes the procedure for adding a new app (or Service Provider, SP) to your setup.
- In Uptrends, you need to be on the Enterprise pricing plan in order to use SSO. If you are currently on a different pricing plan, or if you’re not sure, ask our Support team to help evaluate your options.
Enabling Single Sign-on in Uptrends
In Uptrends, go to your Account settings (Account > Account settings) and check the Enable Single Sign-on (SSO) option. If you don’t see that option, you may need to upgrade to Uptrends Enterprise.
When you enable SSO in your account options, you’ll notice a new section for default login options for operators (see below) and the section containing your SSO settings.
In the Single Sign-on settings, notice the Single Sign-on URL field. It’s a predefined URL you’ll need to copy into your IdP configuration in one of the next steps.
Log into your Identity Provider using administrative privileges. Start the setup for a new SAML-based app, give it an appropriate name (e.g. Uptrends) and optionally add the Uptrends logo.
If your IdP requires it, make sure to specify an IdP-initiated setup, rather than an SP-initiated one. Additionally, if you need to specify the Service Provider’s web platform, choose Microsoft IIS.
Your IdP will ask about the Service Provider’s Single Sign-on URL, or SAML endpoint. Please use the Single Sign-on URL mentioned in step 2.
Some IdPs ask about an Audience URI or Entity ID: please specify the same URL you used in the previous step. Some IdPs actually specify their own Audience URI or Entity ID. In that case, copy that value and paste it into the Audience URI/Entity ID field in your Uptrends SSO settings.
Your IdP probably lets you specify what field should be used by the Identity Provider so the Service Provider can recognize which user is trying to log in. This option is often called the Name ID Format. Uptrends uses the user’s e-mail address, so please choose Email or EmailAddress for that value.
Finish the setup procedure in your IdP. At the end of the procedure, your IdP gives you the configuration data that Uptrends needs in order to finalize the SSO setup. Depending on your IdP, it will give you the Identity Provider Single Sign-on URL and the certificate data (which is an X.509 public key), or it will let you download a separate XML file that contains that same information.
Only if your IdP gives you an XML metadata file: you can open the file as a regular text file and locate the appropriate information. If you’re not sure, please ask our Support team to help you out.
Locate an XML node that looks similar to ` <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://your-idp.your-organization/your-app" /> ` The URL in the **Location** attribute is the value you need in the next step. Also locate an XML node named `<ds:X509Certificate>` The Base64-encoded data inside that node is the certificate data you'll need shortly.
Back into your Uptrends account settings, copy the Identity Provider’s Single Sign-on URL into the Login URL field.
The next step is to store the certificate data generated by your IdP into your Uptrends vault.
Click the Add item link next to the Certificate field. A new browser tab opens that lets you create a new item in the vault for storing your public key data. Give it a recognizable name (e.g. SSO certificate), and make sure the type is set to Certificate public key.
In the Public key field, copy the Base64-encoded data you located earlier.
Save the new vault item.
Navigate back to the Account settings in the previous browser tab. Click Refresh to reload the list of available items, which should now contain the vault item you just created. Finally, select the SSO certificate. In cases where you need certificate rollover (for example if a previously uploaded certificate is due to expire, and you need seamless transition to the next), you can choose to use all vault items inside a vault section. To do so, select the option ‘Scan this entire section to find the appropriate certificate’ from the Certificate drop-down menu. Clickto finish your SSO setup.
Your Single Sign-on setup is now ready for use.
Managing login options
When you’ve successfully configured Single Sign-on in your account, you can decide whether to enable SSO-based logins for all operators at once.
In the account settings, you can set the default behavior for all operators. You can enable/disable both the classic username/password based logins, and SSO-based logins. Obviously you should not disable both, as that locks out all operators.
The typical scenario is to keep username/password based logins enabled at first, then test the SSO-based logins with a few users, and finally disable username/password based logins for all operators to ensure everyone starts using Single Sign-on to access Uptrends.
Aside from this default behavior, you can create exceptions for individual operators. When you review the settings of an operator, you’ll notice that both the username/password login settings and the SSO login settings are set to “Account default” at first. This means that the default behavior you specified in the account settings will apply to this operator.
For each operator, you can select a different setting to allow or disallow those login options. For example, this is useful if you require all of your regular operators to use Single Sign-on, except one or more special operators you created to allow people outside your company to get access to certain reports. They may not have access to your Identity Provider, but you can still allow them to access Uptrends using a normal username/password login.