This article explains how to set up SAML-based single sign-on (SSO) for users of your BlueConic tenant. Depending on which SSO identity provider you use, the steps may vary, but the basic process remains the same.
- What is single sign-on?
- Set up SAML-based SSO for BlueConic users
- Information you need to provide
- Turn on SSO in BlueConic
- Configure your SSO identity provider for BlueConic
- Complete the SSO setup in BlueConic
What is single sign-on?
Single sign-on offers your BlueConic users the convenience of logging into BlueConic via the identity provider that controls access to other apps at your site. SSO identity providers such as 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.
Identity provider: The SSO platform you use to manage identity and authentication at your site, for example OKTA, OneLogin, or Google G Suite. Steps below use G Suite to illustrate the setup procedure, but you can substitute your identity provider's details.
Service provider: BlueConic
Supported identity providers: Setting up SSO for BlueConic has been tested for OKTA, OneLogin, and Google G Suite. Setting up SSO with other SAML-based SSO identity providers is not tested or guaranteed; it depends on how the other system has implemented SAML.
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.
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 into 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.
Set up SAML-based SSO for BlueConic users
BlueConic users who have access to the General Settings window, and the privileges to manage users in BlueConic, are able to update the SSO settings in BlueConic using the steps described below.
Setting up SSO for BlueConic users involves these procedures:
- Turn on SSO in BlueConic settings and retrieve information needed in the next step.
- In your identity provider, add BlueConic as an SSO app.
- Gather information in your identity provider that BlueConic requires.
- In BlueConic, create new BlueConic users with the identity provider email as username.
- Enter the required identity provider information in BlueConic.
- Test your setup.
Information you need to provide
Setting up SAML-based SSO for BlueConic essentially involves a handshake between BlueConic and your SSO identity provider.
Here is a list of the BlueConic information that you'll need to provide to your identity provider (#1 and 2), as well as information from your identity provider you will need to set up SSO for BlueConic (#3, 4, and 5).
|BlueConic field||Identity providers|
|Audience URL (Service provider entity ID)||Audience||Entity ID|
|2.||ACS/ SSO URL
|Single sign-on URL||ACS (Consumer) URL||ACS URL|
|3.||Issuer URL / Entity ID||Identity provider issuer||Issuer URL||Entity ID|
|4.||SSO Endpoint URL||Identity provider single sign-on URL||SAML 2.0 endpoint (HTTP)||SSO URL|
|5.||X.509 certificate||X.509 certificate||X.508 certificate||Certificate|
Turn on SSO in BlueConic General Settings
- In BlueConic, choose Settings > General to open the General Settings page.
- Turn on Single Sign-On.
- A set of fields and values appear. This is where you receive two pieces of information from BlueConic to provide to your identity provider (#1 and #2, in blue). Copy values 1 and 2. You will need to provide these URLs to your Single Sign-On provider.
- Next, you gather the URLs and certificate from your identity provider to enter in fields 3, 4, and 5.
Once you have configured your identity provider for SSO with BlueConic, you complete the set up in BlueConic, described below in Completing the SSO setup in BlueConic.
Configure your SSO identity provider for BlueConic
Each identity provider platform has a procedure for adding an application such as BlueConic to its list of application service providers.
Setting up your identity provider for SSO with BlueConic
The example below uses Google G Suite as the identity provider, but you can use any SSO provider that supports SAML 2.0 (for example, OKTA or OneLogin).
- Open https://gsuite.google.com and click Sign in.
- Log in using your admin credentials.
- Select Apps in the G Suite Admin console.
- Select SAML apps.
- Select Add a service/App to your domain or click the Plus icon "+" in the lower right-hand corner.
- Click Setup my own custom app at the bottom of Step 1.
- Copy the values for SSO URL and Entity ID to a text file, and download the Certificate -- you will need this information to configure the BlueConic SSO settings.
- Add information about the BlueConic app, including Application Name, an optional Description, and a logo.
- In the Service Provider Details screen, enter the details for your BlueConic tenant.
ACS URL: https://yourserver.blueconic.net/saml/acs
Entity ID: https://yourserver.blueconic.net/saml/metadata
Activate the Signed Response checkbox.
Choose Email for the Name ID Format.
- Click Finish in the Attribute Mapping step.
- Click OK in the Setting up SSO for BlueConic window.
- Click Edit Service in the Settings for BlueConic page.
- In the Service Status settings, select On for everyone and then Save.
View, change, or update SSO service provider settings
After you set up SSO for BlueConic, you can review or update the service provider settings in Google G Suite in the Google Admin window.
- Click Home, then Apps, then SAML apps, and then BlueConic.
- Click Service Provider Details to view or update your BlueConic service provider details.
Gather your identity provider settings
In the previous procedures, you added BlueConic service provider information to your identity provider. Next you collect several pieces of information from your identity provider to add to the BlueConic setup screen. The example shown below uses Google G Suite as identity provider. Steps for other identity providers are similar.
- To find information from the identity provider G Suite, which are needed in BlueConic, go to the identity provider homepage (Google Admin, in this case).
- Click Home, then Security in the Google Admin Console.
- Select Set up single sign-on (SSO), and you will see the SSO URL, Entity ID, and Certificate you need to enter in BlueConic.
Here's an example showing the identity provider details you would need to set up SSO with BlueConic.
- Copy the SSO URL and Entity ID to a text file, and download the Certificate. (Alternatively, you can download the IDP metadata, which contains all the information you need to provide in BlueConic.)
Complete the SSO setup in BlueConic
The information you enter here was gathered in Step 4 above and in Step 7 of Setting up your identity provider for SSO with BlueConic.
- In BlueConic, open the Settings > General page.
- Turn the Single Sign-On (SSO) feature On.
- Enter the Issuer URL / Entity ID from your identity provider (for example, G Suite, OKTA, or OneLogin).
- Enter the SSO Endpoint URL from your identity provider.
- 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.
- 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 into BlueConic twice, in two browser sessions, to make sure you always stay logged in.
- Open the BlueConic Users window.
- 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.
- 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
In your SSO provider, open the app window. In G Suite, for example, you open Apps and click Launch in the upper right-hand corner.
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 firstname.lastname@example.org if you need assistance with the BlueConic portion of this procedure.
Learn more about SSO identity providers: