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

In order 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, 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.

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 setup 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, navigate to Enterprise Setup > Access tab.

Screen_Shot_2020-08-25_at_12.34.08_PM.png

Authentication Tab

This sub-tab displays a list of authentication option for available for the system. By default, it only shows two standard methods: Brightidea Login & Registration. Once a SSO method added, it will show up in the list. Once SSO implementation is complete, you can choose to keep Brightidea login or only enable your SAML profile. If you choose to only enable your SAML profile, then 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 setup. Tab contains four sections:

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

 

Step 1: Exchange Metadata Between Brightidea and Your IDP

Please ensure you read the prerequisites for SSO implementation before beginning your SSO implementation. It’s likely that an SSO Engineer from your company is needed for the configuration.

Login as administrator, and then navigate to Enterprise Setup > Authentication > SAML Profiles (sub-tab)

The first step of setup is to exchange SAML information between the 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 Response, copy and paste it into your company’s Identity Management setup. If the given Brightidea system has multiple domain setup, 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 SAML service provider, copy and paste it into your company’s Identity Management setup
  • Download Metadata: Metadata is information used in the SAML protocol to identify Brightidea as a service. It defines attributes like service addresses and certificates.

Click "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 “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 a 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 Request 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 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 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>

...

Click “Save Changes”, 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. You're able to specify Email Address as the NameID, but we recommend using a unique Employee ID where possible. Email Addresses can change if an employee gets married, changes their name, or if the company changes the email domain of all email addresses. Resultantly, using Email Address as the NameID can cause problems such as duplicate accounts.

Step 3: Test SSO

Now that an SSO profile setup, you can give it a test. But before test begins, make the following preparation:

  • We recommend using two types of browser, 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 the 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 in an "off hours". If your system has not yet launched, be sure to notify pre-launch user on your testing schedule.

Follow the steps below. It uses Chrome and Firefox for example, but you can use any two browser types.

  • In Chrome, navigate to Enterprise Setup, then Access (Tab) > Authentication (Sub Tab). You should see a 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 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 immediate upon entering the URL in your browser's address bar.
    • Please note, 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 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, user will enter into the Brightidea system.
  • After login, verify user account accuracy by visiting your profile page. The key is to check whether screen name 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 "Brightidea login" option and then 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 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. 

Screen_Shot_2020-08-25_at_12.35.06_PM.png

  • Entity ID of this Profile: 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 logout of the Brightidea system.
  • Authentication Binding: Choose to send the method of how the Authentication Request is sent: POST or REDIRECT.
  • Signed Authentication: Choose signature algorithm for the Authentication Request. By default, the request XML is not signed.
  • Create member on initial access: If enabled, user account is created in Brightidea system automatically on first time access. If disabled, new users will not be able to access. Only users who have existing accounts in system (possibly from manual user import) can access. The system uses either email address or value from the “NameID” attribute 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. 
  • Update member on subsequent access: If enabled, Brightidea profile is updated from SAML Response attributes automatically for returning users. If disabled, user attributes are from SAML Response will not over-write existing user profile data in Brightidea. The system uses either email address or value from the “NameID” attribute 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 profile attributes of the login 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: Screen name is required for user access. It’s normally the user’s full name. If your company’s Identity Management system cannot pass a screen name attribute on user SSO login, enable this option to combine value from first and last name field to create user’s screen name.
  • Group Attribute: Map an attribute name from the SAML Response that contains user group value. User will be assigned to group on access. Use semicolon as delimiter if passing multiple group values in the same field. On user access, new groups will be created automatically. System prepends “AUTO_” in group name 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 SAML Response that contains user profile photo. Attribute must contain hex value of an image file. Image 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 user 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: Brightidea system provides tools to help admin support user SSO login. Admin can configure contact information for accessing user in the “Support Setting” section. User 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 email alert when a user encounters SSO login error.
      • Expose support info: Enable to display support contact info at the SSO login error screen. 

 

Step 5: Enable SSO

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

Screen_Shot_2020-09-17_at_9.10.27_PM.png

  • 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 standard Brightidea password. Please note, keeping self registration and SSO enabled at the same time can result in duplicate account creation if your SSO users register with their own 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 SSO login error, a Reference ID would be generated. Depending on the Support Setting, system admin would receive that ID either through system generated email, or direct contact by the user. Using the ID, you can troubleshoot for the cause of the issue. 

Follow these steps to troubleshoot an SSO error:

  • Open SAML Transaction Log from Enterprise Setup-->Authentication Tab-->SAML Selection Sub-tab. The list provides access to all SAML activities from last 30 days. Admin can sort and filter on 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 user access error, paste it under the column to filter records, then hit the “Enter” key. List will filter base on the ID.
  • Once the targeted record is found, click on the Transaction ID to view detail.
  • Check “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 had sent an invalid SAML Response value to the 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. Issuer is a 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 Identity Provider contains invalid Issuer value. The value must belong to the Identity Provider who had received 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 parameter are sent in Identity Provider initiated SSO request.
  • No Identity Provider Profile Exists for this Issuer: The SAML Response sent by Identity Provider contains 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 received response: The SAML Response sent by 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 Identity Provider contains an 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: Destination in response doesn't match the current URL: The SAML Response sent by Identity Provider contains an invalid Destination attribute value. 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 Identity Provider is missing 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.  “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 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 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 is 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 is not using the same time.
  • Process Assertion: Missing required <saml:AuthnContext> in <saml:AuthnStatement>: The error occurs when Identity Provider sent a SAML Response with 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 this user to a group or assign this user's group to the campaign.  User's domain may be restricted: User cannot access because of group assignment or domain restriction setting of your Brightidea system.
  • Create Session: (Screen Name/Email) cannot be blank: The error occurs when Brightidea Service Provider fails to receive valid Screen Name or Email value of the user from Identity provider. This could be caused by one of the reason 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: 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 Identity provider setting is invalid.
  • System Configuration Settings Not Found: The error occurs when 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 Identity provider setting is invalid.

 

SSO Login for Brightidea Mobile App

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

You can visit Brightidea mobile apps from links below.

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

  • Download and install Brightidea Mobile app
  • Launch the app from your device, and type in your email address in input box and tab “Next”.
  • If SSO integration is setup correctly, the app will invoke browser within app, and redirect user to your company’s user authentication page.
  • Depending on the setup of your company’s authentication service, user may or may not be prompted to enter company credential.
  • 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.

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments