Setting up single sign-on (SSO) for Azure Active Directory

This article explains how to set up SAML-based single sign-on (SSO) for BlueConic users via Azure Active Directory (AAD). There are two dimensions to enabling SSO for BlueConic through Azure: First you enable the SAML authorization inside Azure and gather information for the second step, configuring SSO in your BlueConic tenant.

Note: In order to activate single sign-on for Azure AD (or for ADFS Active Directory Federation Service) for your BlueConic tenant, please contact your BlueConic Customer Success Manager or our support department first with the request to prepare your tenant. Wait until after confirmation before executing the setup procedures on this page.

Before you begin

Make sure you have appropriate authority and technical knowledge to complete this process. Once you set up SSO for BlueConic, all users at your site will have to log in to BlueConic via your SSO identity provider. They will no longer be able to access BlueConic using the BlueConic login screen.

Important: Open BlueConic twice

Before you begin, log in to your BlueConic account twice: once in a regular browser window and once in a different browser or incognito window. This way, you will still be logged in to BlueConic if you get locked out of your account in the other browser window.

Important: Once you turn on SSO in BlueConic and save your settings, you will no longer be able to use the standard BlueConic login process. So if you set up SSO in BlueConic, before closing the current session, make sure to test your set up to verify that users can log in using your identity provider. See Testing your SSO setup for BlueConic logins below.

What is single sign-on?

Single sign-on offers your BlueConic users the convenience of logging in to BlueConic via the identity provider that controls access to other apps at your site. SSO identity providers such as Azure, OKTA, OneLogin, or Google's G Suite let end users log in once and gain access to multiple applications.

Once you enable SSO for BlueConic, BlueConic users at your site will no longer use the native BlueConic login page but will use your SSO provider to log in directly to BlueConic. When you add BlueConic to your SSO service, all BlueConic users for your tenant must log in via your SSO identity provider. You cannot enable SSO for only some BlueConic users. 

Important definitions

Identity provider: The SSO platform you use to manage identity and authentication at your site in this case Azure AD.

Service provider: BlueConic

SAML: Security Assertion Markup Language for exchanging authentication and authorization credentials between identity providers and service providers. BlueConic's SSO implementation uses the authentication feature of SAML 2.0. Authorization for roles within BlueConic has not been changed and is still set up and managed inside BlueConic.

Setting up SSO in Azure Active Directory for BlueConic

  1. In Azure Active Directory admin center, open this page to add an application: https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/AppGalleryApplicationsBlade/category/
    Azure-SSO-BlueConic-Admin-Center.png
  2. Under "Add your own app" select Non-gallery application, enter a name for the app, and choose SAML-based single sign-on. Click Add.
    Azure-BlueConic-SSO.png
  3. On the Overview page, go to step 1 under Getting Started: “Assign users and groups,” and add the users who need access to this application.
    Azure-BlueConic-Add-Users.png
  4. Return to the Overview page, to step 2: “Set up single sign on."
    Azure-BlueConic-Set-Up-Users.png
  5. Choose SAML.
    Azure-BlueConic-SAML-SSO.png
  6. Under Basic SAML Configuration, enter the following information for your environment:
    Identifier (Entity ID): https://<tenantname>/saml/metadata
    Reply URL (ACS URL for Assertion Consumer Service): https://<tenantname>/saml/acs
    Sign on URL: <leave empty>
    Relay State: <leave empty>

  7. Under User Attributes & Claims, click in the field Unique User Identifier (Name ID).
    Azure-BlueConic-SSO-User-Attributes.png
  8. In the Manage claim window, change Source attribute to "user.mail" and click Save.
    Azure-BlueConic-Manage-Claim-SSO.png
  9. Under SAML Signing Certificate window, click the pencil icon and change Signing Option to "Sign SAML response and assertion".
    SAML-Signing-Certificate-9.jpg
  10. Next to the Thumbprint entry for the Active certificate, click the ... option and select the Base64 certificate download option to download a certificate to use inside BlueConic.
    Base64-Certificate-Download.png
    The information in the download files needs to go into the "Identity provider: X.509 Certificate" on your BlueConic tenant.
  11. Under "Set up <name you entered in Step 2 above>" make note of the following items, which you will need to provide to BlueConic in the next procedure:
    Login URL, to be used as " Identity provider: SSO Endpoint URL" on your BlueConic tenant
    Azure AD Identifier, to be used as " Identity provider: Issuer URL / Entity ID" on your BlueConic tenant
    How-to-find-your-Azure-Login-URL-Azure-ID-Identifier.png

Complete the Azure SSO setup in BlueConic

Make sure you've read the background information in the Before you begin section before completing the SSO setup process in BlueConic.

The information you enter here was gathered in the procedure above, Setting up SSO in Azure Active Directory for BlueConic

  1. In BlueConic, open the Settings > General page.
  2. Turn the Single Sign-On (SSO) feature On.
    SSO-SAML-BlueConic.png
  3. Enter the Issuer URL / Entity ID provided by Azure AD 
  4. Enter the SSO Endpoint URL provided by Azure AD
  5. Enter the X.509 Certificate by opening the certificate in a text editor and copying/pasting it into the field. Make sure you do not add trailing spaces or an empty line at the end.
    BlueConic-SSO-Complete-Example.png
  6. Save your settings and close the confirmation lightbox. Do not close the current browser session before testing your SSO setup.

Create new BlueConic user logins

Next you add user logins for all BlueConic users. Make sure you have logged in to BlueConic twice, in two browser sessions, to make sure you always stay logged in.

  1. Open the BlueConic Users window. 
  2. For each BlueConic user who needs to log in to BlueConic via your identity provider, create a user in BlueConic with the email from the identity provider as username. 
    This is to ensure your users are provisioned in the identity provider.
  3. Save your settings but do not close the current browser session before testing your SSO setup.

Test SSO access in your identity provider for BlueConic logins

Make sure users can log in correctly via your SSO provider. If you encounter errors, you can turn the Single Sign-On setting Off in the BlueConic General Settings page and troubleshoot the setup without locking users out. Once you've turned on SSO, saved your settings, and closed the browser, all BlueConic users for your tenant must log in via your SSO identity provider.

BlueConic SAML-based SSO implementation details

SAML details BlueConic implementation
SAML version supported SAML2.0
SAML profile supported Web Browser SSO Profile
Learn more about SAML metadata.
NameID field NameID must hold the username as email address.
HTTP standard Must be HTTPS

Turning off the SSO feature

To turn off SSO and have BlueConic users at your site return to the BlueConic login instead of logging in via your SSO identity provider, open General Settings in BlueConic and turn the SSO feature Off.

Troubleshooting your SSO setup

Contact your BlueConic Customer Success Manager at support@blueconic.com if you need assistance with the BlueConic portion of this procedure.