Single-Sign-On (SSO) Setup Guide

This is a step-by-step guide for administrators to setup Single Sign-on (SSO) integration between Brightidea and a company’s identity management system.  It also provides tools for administrators to help support user SSO login experience.

Table of Contents

• Before You Get Started: Prerequisites for SSO on Brightidea
• Before You Get Started: Feature Overview
• Step 1: Exchange Metadata Between Brightidea and Your IDP
• Step 2: Configure Required SSO Attributes
• Step 3: Test SSO
• Step 4: Configure Advanced SSO Settings
• Step 5: Enable SSO
• How to Troubleshoot SSO Errors
• SSO Logon for Brightidea Mobile App

 

Before You Get Started: Prerequisites for SSO

To implement SSO using the Brightidea SAML SSO feature, the following conditions must be met:

Identity Management System

An Identity Provider (IDP) service or equivalent identity management system will be required to implement SSO with Brightidea. Several of the most common IDP services and their corresponding support links can be found below. Please note that Brightidea is not able to provide technical support when it comes to issues with your IDP. For any problems with your IDP service, please contact the IDP service provider.

• OKTA 
• PING Identity
• Microsoft Azure
• OneLogin

SAML 2.0

• Your company’s identity management system must have SAML 2.0 capability. SAML is an industry-standard protocol. Click here to learn more about SAML. 
• If you do not use SAML 2.0, Brightidea can offer custom SSO implementation as a paid service, If you're interested in custom SSO, please contact your Customer Success Manager.

Technical Resource

• To set up SSO integration, you will require the assistance of an SSO Technical Engineer from your company. If you do not have an SSO Technical Engineer, Brightidea offers paid SSO support service. However, you will still require someone with authorization to modify your company's IDP. If you're interested in learning more about our paid SSO support services, please inquire with your Customer Success Manager.

 

Before You Get Started: Feature Overview

To get to the Brightidea SAML SSO feature in your Brightidea system, navigate to System Setup > Access.

Authentication Tab

This sub-tab displays a list of authentication options available for the system. By default, it only shows two standard methods: Brightidea Login & Registration. Once an SSO method is added, it will show up in the list. Once SSO implementation is complete, you can choose whether to keep the Brightidea login or only enable your SAML profile. If you choose only to enable your SAML profile, users will be directed to your SSO whenever they attempt to access Brightidea.

SAML Profiles Tab

This sub-tab is where a SAML SSO method is set up. The tab contains four sections:

• Service Provider Info: This section presents information on the given Brightidea system as a Service Provider. The information is used for SAML configuration within your company.
• Identity Provider Settings: This section allows administrators to input information about your company as the Identity Provider.
• Support Settings: This section allows administrators to enter contact information for SSO user access support.
• SAML Transaction Log: This section contains navigation to SSO user access logs.

 

Step 1: Exchange Metadata Between Brightidea and Your IDP

Please ensure you read the prerequisites for SSO implementation before beginning your SSO implementation. An SSO Engineer from your company is likely needed for the configuration.

Log in as an administrator, and then navigate to System Setup > Authentication > SAML Profiles

The first step of the setup is to exchange SAML information between Brightidea and your company’s Identity Management system.

Service Provider Information

In SAML SSO integration, Brightidea is the Service Provider. You can find the Server Provider information in the Service Provider Info Section. 

• Assertion Consumer Service: An endpoint URL for receiving SAML Responses, copy and paste it into your company’s Identity Management setup. If the given Brightidea system has multiple domains set up, you can choose the desired endpoint URL used for the configuration.
• Entity ID of this System: A string that uniquely identifies the given Brightidea system as a SAML service provider, copy and paste it into your company’s Identity Management setup
• Download Metadata: Metadata is the information used in the SAML protocol to identify Brightidea as a service. It defines attributes like service addresses and certificates.

Click the "Download Metadata" link and upload it into your company’s Identity Management setup. 

Identity Provider Information

In SAML SSO integration, your company’s Identity Management system is the Identity Provider. At the Identity Provider Setting section, click on the “Add New” button to enter applicable information. We call the setting a “profile”.

• SAML Profile Name: Give a name to the profile.
• Upload Metadata: This field expects valid Identity Provider metadata. Very often, you can export this metadata from your company’s Identity Management system. Once uploaded, it can auto-populate some other fields in this profile if applicable.
• Single Sign-on Service: An endpoint URL of your company’s Single Sign-on service page. It receives Authentication Requests from Brightidea. It can be auto-populated through Metadata upload.
• Identity Provider Issuer: This field expects a string that uniquely identifies the Identity Provider. It can be auto-populated through Metadata upload.
• Upload Public Key: This field expects a certificate used for signature verification in a SAML Response. It can be auto-populated through Metadata upload.

Download the metadata from your IDP and upload it back into Brightidea. 

Step 2: Configure Required SSO Attributes

Implementing SSO requires you to pass "attributes" from your IDP to Brightidea. Attributes will include information about the user authenticating through SSO.

Configure Minimum Required Attributes

Brightidea Service Provider requires a minimum of two attributes from the Identity Provider when receiving SAML Response.

• Email – Email address of the accessing user
• Screen Name – Display name of the accessing user. Normally, it’s the user’s full name.

*NOTE: For any configurable attributes, you must configure the exact attribute name being passed in the SAML assertion. For example, attribute name is "email", configure "email" into the input box. If the attribute name is "emailAddress", configure "emailAddress" (with camelCase) into the input box. If the attribute name is "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailAddress", configure "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailAddress" into the input box. 

In the corresponding Brightidea input field, enter the name of those attributes that come through the SAML Response.

SAML Response example with email and screen name attributes:

... <saml:Attribute Name="displayName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">                   John Doe     </saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">                   johndoe@example.com      </saml:AttributeValue> </saml:Attribute> ...

Once “Save Changes” is selected, a new Identity Provider profile should be created.

• "NameID" Attribute: The "NameID" attribute is required in the SAML assertion, and is intended to be the "unique identifier" for each user. While you can configure the NameID as an email address, we recommend using a unique Employee ID where possible. As email addresses can be subject to change (for instance, if an employee gets married, changes their name, or if the company changes the email domain of all email addresses), utilizing an email address as the NameID can cause problems such as duplicate accounts and notification issues.
• WARNING: Using email address as the NameID value may cause duplication of accounts because email addresses are subject to change. To avoid duplication of accounts, we strongly recommend using a unique, unchangeable value such as Employee ID.

Step 3: Test SSO

Now that an SSO profile is set up, you can give it a test. But before testing begins, make the following preparations:

• We recommend using two types of browsers, such as IE and Chrome, or Firefox and Safari. One browser is for enabling setup, the other is for testing SSO. If you disable the Brightidea login page at any point, using multiple browsers will help avoid being locked out of Brightidea because of failed SSO attempts.

• If your Brightidea system is already live with active users, we recommend informing existing users of possible service interruption. It’s best to perform SSO testing during "off hours". If your system has not yet launched, be sure to notify pre-launch users of your testing schedule.

The following steps below use Chrome and Firefox for example, but you can use any two browser types.

• In Chrome, navigate to System Setup > Access > Authentication. You should see an SSO profile listed under the regular Brightidea login method.
• Check the SSO profile you wish to test and click “Save Changes”. If you leave "Brightidea login" enabled, this will allow you to test SSO while maintaining the Brightidea login page. Doing so will help avoid being locked out of your Brightidea site if the SSO test is unsuccessful. 
• Keep the Chrome browser open, and open Firefox, then enter the Brightidea system URL in the address bar.
• If you've kept "Brightidea login" enabled in the Authentication (Sub Tab), you will encounter the Brightidea login page. Beneath the email/password authentication, use the new SSO button to initiate your SSO. If you disabled "Brightidea login", your SSO will be initiated immediately upon entering the URL in your browser's address bar.
  • Please note that the user experience after initiating SSO will be dependent on your company's IDP setup.
• After successful authentication with the company, your company’s Identity Management system should send a request to the Brightidea Assertion Consumer Service URL, passing SAML Response. This is the URL presented in the “Service Provider Info” section.
• If the SAML Response is valid, the user will enter into the Brightidea system.
• After login, verify user account accuracy by visiting your profile page. The key is to check whether the screenname and email are populated correctly- if the data looks good, that means SSO integration is a success. You can then open it up for other users to test.
  • Once SSO is successfully tested, you can disable the "Brightidea login" option and Brightidea will begin to initiate SSO when a user types in the URL of your Brightidea site.

 

Step 4: Configure Advanced SSO Settings

SSO can be further configured to fit your company's needs. Go to an existing profile in the “Identity Provider Info” section, click on the “Configure Advanced Settings” link, and the profile will expose more configuration options. 

• Entity ID of this Profile: The value of this field defaults to the “Entity ID of this System” under the “Service Provider Info” section. However, you can choose to set one of your own.
• Logout URL: Enter the URL of the page that your users should land on after logging out of the Brightidea system.
• Authentication Binding: Choose to send the method of how the Authentication Request is sent: POST or REDIRECT.
• Signed Authentication: Choose the signature algorithm for the Authentication Request. By default, the request XML is not signed.
• Create member on initial access: If enabled, the user account is created in the Brightidea system automatically on first-time access. If disabled, new users will not be able to access the system. Only users who have existing accounts in the system (possibly from manual user import) can access it. The system uses either an email address or the value from the “NameID” attribute (recommended) in the SAML Response to verify whether a user has an account in Brightidea. If a match is found on either, that means an account already exists. 
• Update member on subsequent access: If enabled, the Brightidea profile is updated from SAML Response attributes automatically for returning users. If disabled, user attributes from SAML Responses will not overwrite existing user profile data in Brightidea. The system uses either an email address or value from the “NameID” attribute (recommended) in SAML Response to verify whether a user has an account in Brightidea. If a match is found on either, that means an account already exists.
• Profile Attribute Name Mappings: In addition to the required attributes mentioned above, companies often pass additional attributes that can benefit administrators and users of Brightidea. If you are an SSO engineer reading this guide, please inquire with your business owner/administrator of Brightidea to determine which additional attributes should be passed. Common attributes include location, department, job title, etc. You can choose to send the profile attributes of the user in the SAML Response. Map the names of those attributes to the Brightidea profile fields.

SAML Response example with user profile attributes:

... <saml:Attribute Name="userLastname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">                   Doe </saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="userJobtitle" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">                   Sales </saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="userFirstname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">                   John </saml:AttributeValue> </saml:Attribute> ...

 

• Combine first and last name to create screen name: A screen name is required for user access and is typically the user’s full name. If your company’s Identity Management system cannot pass a screen name attribute on the user SSO login, enable this option to combine values from first and last name fields to create the user’s screen name.
• Group Attribute: Map a single attribute from the SAML Response that contains user group value. Users will be assigned to the group on access. If passing multiple group values in the same field, use a semicolon as a delimiter between each new value. On user access, new groups will be created automatically. The system prepends “AUTO_” in group names to differentiate these from manually created groups. The accessing user is then assigned to those groups.

SAML Response example with user group attribute:

... <saml:Attribute Name="group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">                   Group A;Group B;Group C </saml:AttributeValue> </saml:Attribute>    ...

 

• Photo Attribute: Map an attribute name from the SAML Response that contains a user's profile photo. The attribute must contain a hex value of an image file. Images must be in .png, .jpg, or .gif format. On user access, the hex value will be converted to the appropriate image format and uploaded as the user's profile image.

SAML Response example with profile image attributes:

... <saml:Attribute Name="profile_image" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">ffd8ffe 000104a46494600010200000100010000ffdb004300080606070605080707070909080a 0c140d0c0b0b0c1912130f141d1a1f1e1 d1a1c1c20242e2720222c231c1c2837292c30313434341f27393d38323c2 e333432ffdb0043010909090c0b0c180d0d18322 11c213232323232323232323232323232323232323232323232323232323232323232323232323232323232323232323232323 232ffc0001108009b009b030122 00021101031101ffc4001f000001050101010101010000000000000000010203040506070809 0a0bffc400b5100002010303020403050504... </saml:AttributeValue> </saml:Attribute> ...

 

• SSO Support Settings: The Brightidea system provides tools to help admins support user SSO logins. Admins can configure contact information for accessing users in the “Support Settings” section. Users would only be exposed to the information when an SSO login error is encountered.
  • • Name: Contact name of SSO error support.
    • Email: Contact email of SSO error support.
    • Telephone: Contact phone number of SSO error support.
    • Send alert to email: Enable to receive an email alert when a user encounters an SSO login error.
    • Expose support info: Enable to display support contact info at the SSO login error screen. 

• Logic of SSO Authentication: The SSO in Brightidea uses specific logic to authenticate users, and create or update accounts (note, the below logic assumes that you are using Employee ID as NameID, which is strongly recommended).
  • If a user logs in and Employee ID (NameID) is passed to Brightidea through SSO:
    • Check if Employee ID (NameID) matches to an existing account:
      • If an account is matched based on Employee ID (NameID), log in and update the existing account with all additional info provided in the SAML assertion.
      • If an account is not matched based on Employee ID (NameID), check if one (1) user account exists with the same email address and without Employee ID
        • If the account is matched based on an email address, log in and update the existing account with all additional info provided in the SAML assertion.
        • If the account is not matched based on the email address, create the account
          • Note: This scenario may create a duplicate account if Brightidea receives completely new data for an individual that already exists in the software but uses alternate data.
        • If there are conflicts between emails/employee IDs, a user may fail to log in and an error may be generated.

Step 5: Enable SSO

Once the configuration is complete, you can enable SSO by navigating to System Setup > Access > Authentication. Check the box next to your configured SAML profile to activate SSO. 

• Enable Brightidea Login: Enable/disable the standard Brightidea login page. If this is disabled while SSO is enabled, SSO automatically initiates when visiting your Brightidea site.
• Enable Registration: Register to create a standard Brightidea account using a standard Brightidea password. Please note that keeping self-registration and SSO enabled at the same time can result in duplicate account creation if your SSO users also register with their information. Disable this option if you want all new accounts to be created through SSO.

How to Troubleshoot SSO Errors

Every user access is recorded. When a user encounters an SSO login error, a Reference ID will be generated. Depending on the Support Setting, system admins would receive that ID either through a system-generated email or direct contact by the user. Using the ID, you can troubleshoot the cause of the issue. 

Follow these steps to troubleshoot an SSO error:

• Access the SAML Transaction Log by navigating to System Setup > Access > Authentication > SAML Profiles. Scroll to the bottom of the page and select Go to SAML Transaction List.
• The list provides access to all SAML activities from the last 30 days. Admins can sort and filter each column in the list. Clicking on a Transaction ID opens the Transaction Detail page.
• Locate the “Reference ID” column, copy the ID received from the user access error, paste it under the column to filter records, then hit the “Enter” key. The list will be filtered based on the ID.
• Once the targeted record is found, click on the Transaction ID to view details.
• Check the “Error Message” field to get information on the cause of the error.
• Check “Request/Response XML” for data exchanged at the time of the transaction between Brightidea and your company.

Below is a list of possible error messages and what they mean.

• SAML 2.0 Artifact Binding is not supported: The Identity Provider is set to use SAML 2.0 Artifact Binding. Brightidea SSO feature does not support this method. Please configure the Identity Provider to use POST binding.
• Invalid message received to AssertionConsumerService endpoint: The Identity Provider sent an invalid SAML Response value to Brightidea. Check the transaction log detail page to see the SAML Response XML value sent.
• Missing <saml:Issuer> in message delivered to AssertionConsumerService: The SAML Response sent by Identity Provider is missing the Issuer element. The issuer is required in the XML. Check the transaction log detail page to see the SAML Response XML value sent.
• The <saml:Issuer> of the response does not match the identity provider we sent the request to: The SAML Response sent by the Identity Provider contains an invalid Issuer value. The value must belong to the Identity Provider who had received an authentication request from Brightidea.
• The required response parameter RelayState was missing: An Identity Provider-initiated SSO request is sent to Brightidea. The request is missing the RelayState parameter. Make sure both RelayState and SAMLResponse parameters are sent in the Identity Provider-initiated SSO request.
• No Identity Provider Profile Exists for this Issuer: The SAML Response sent by the Identity Provider contains an invalid Issuer value. Check the value configured in the “Identity Provider Issuer” field in the Identity Provider profile. The Issuer value in the XML must match the value configured in that field.
• More than one assertion in the received response: The SAML Response sent by the Identity Provider contains multiple Assertion elements. A valid SAML Response contains only one Assertion element. Check the transaction log detail page to see the SAML Response XML value sent.
• Received duplicate assertion: The SAML Response sent by the Identity Provider contains a used Assertion. This happens when the assertion was already used for a previous user access.
• Process Assertion: SAML Profile Not Found: No SAML Profile contains the identity provider issuer found within the SAML Response.  Check the value configured in the "Identity Provider Issuer" field in the SAML Profile settings.  The issuer value in the XML must match the value configured in that field.
• Process Assertion: Requester: Signature required: The SAML request sent by Brightidea is unsigned while the Identity Provider Service requires a signature. Check the "Sign Authentication" setting and toggle the signature method required by the Identity Provider.
• Process Assertion: The destination in response doesn't match the current URL: The SAML Response sent by the Identity Provider contains an invalid Destination attribute value. The value should be the same as the Brightidea Assertion Consumer Service URL. Check the transaction log detail page to see the SAML Response XML value sent.
• Process Assertion: No assertions found in response from IdP: The SAML Response sent by the Identity Provider is missing the Assertion element. A valid SAML Response contains an Assertion element. Check the transaction log detail page to see the SAML Response XML value sent.
• Process Assertion: Missing certificate in metadata: This error occurs when the certificate uploaded in the Identity Provider profile setting is invalid.
• Process Assertion: Identity Provider Data Error: Could not find encoded certificate in file: The error occurs when the SAML Profile’s uploaded public key is unable to be read.  The “Upload Public Key” field requires a certificate in plain text format.
• Process Assertion: Neither the assertion nor the response was signed: The SAML Response sent by the Identity Provider is not signed. A valid signature is required in the XML.
• Process Assertion: Neither the assertion nor the response was signed: The SAML Response sent by the Identity Provider is not signed. A valid signature is required in the XML.
• Process Assertion: Received an assertion that is valid in the future. Check clock synchronization on IdP and SP: The error occurs when Identity Provider and Service Provider are not using the same time.
• Process Assertion: Received an assertion that has expired. Check clock synchronization on IdP and SP: The error occurs when Identity Provider and Service Provider is not using the same time.
• Process Assertion: Received an assertion with a session that has expired. Check clock synchronization on IdP and SP: The error occurs when Identity Provider and Service Provider are not using the same time.
• Process Assertion: Missing required <saml:AuthnContext> in <saml:AuthnStatement>: The error occurs when the Identity Provider sends a SAML Response with a missing AuthnContext element.
• Process Assertion: Error decrypting assertion: No private key found in metadata: Enable 'Sign Authentication' under advanced configuration to correct. Select the correct algorithm based on your requirements.
• This SP […] is not a valid audience for the assertion. Candidates were: […]: The error occurs when the entity ID does not match the value found in the Audience XML attribute.
• Create Session: Unknown error creating user: An unexpected error occurred on user login.
• Create Session:
  • User does not have access to this campaign or affiliate: You may need to add the user to a group or assign this user's group to the campaign. 
  • User's domain may be restricted: The user cannot access the campaign because of group assignment or domain restriction settings in your Brightidea system.
• Create Session: (Screen Name/Email) cannot be blank: The error occurs when Brightidea Service Provider fails to receive a valid Screen Name or Email value of the user from the Identity provider. This could be caused by one of the reasons below:
  • Incorrect attribute mapping: Verify attribute mappings are correct at the Identity Provider Profile setting. Attribute name mappings are case-sensitive.
  • “Create member on initial access” is disabled: The user has been identified as a new user and cannot be created because of the disabled option.
  • Failed to save member
• Unable to Retrieve Metadata: The metadata uploaded in the Identity Provider setting is invalid.
• System Configuration Settings Not Found: The error occurs when an Identity Provider makes an IDP-initiated request to a Brightidea system with no Identity Provider Profile setting configured.
• Unable to load certificate/public key: The certificate/public key uploaded in the Identity provider setting is invalid.

 

SSO Login for Brightidea Mobile App

To use Single Sign-on (SSO) for mobile access, you must obtain a subscription to the Brightidea Mobile app. To find out more about app subscription, please contact your Brightidea Account manager for more information.

You can download the Brightidea Mobile app for your preferred OS from the links below:

• iOS App Store
• Google Play Store

Follow the steps below to access the mobile app through SSO:

• Download and install the Brightidea Mobile app
• Launch the app from your device, type in your email address in the input box, then tap “Next”.
• If SSO integration is set up correctly, the app will invoke a web browser within the app and redirect the user to your company’s user authentication page.
• Depending on the setup of your company’s authentication service, users may or may not be prompted to enter company credentials.
• After successful authentication, the user will be logged into the mobile application!

At this time, Brightidea does not support multiple methods of login on the mobile application. Once SSO has been configured in the web application, this will be the only method of login on the mobile application.