Brightidea SAML SSO Complete Feature Guide


This feature allows 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:

1. Prerequisite

In order to implement Single Sign-on (SSO) using the Brightidea SAML SSO feature, the following conditions must be met:

SAML 2.0

Technical Resource

  • To setup SSO integration, you need the assistants of SSO Technical Engineer from your company.

2. Feature Overview

To get to the Brightidea SAML SSO feature in your Brightidea system, navigate to Enterprise Setup --> Authentication Tab.
There you will see two sub tabs: Auth Selection & SAML Profiles.

 

1.png

Auth Selection 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.

 

2.png

 

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 Setting

  • 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.
3.png

 

 

3. Getting Started – Configure a SSO method

It’s likely that a SSO Engineer from your company is needed for the configuration. Login as administrator, and then navigate to Enterprise Setup -> Authentication Tab -> 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.
4.png

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.
5.png

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.
  • Download and upload it into your company’s Identity Management setup.

4. 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”.

6.png

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.

Assertion Attribute Name Mapping

Brightidea Service Provider requires two assertion 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.

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

7.png

SAML Response example with email and screen name attributes:

      ...

      <saml:Attribute Name="givenName" 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="mail" 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>

      ...

 

On “Save Changes”, a new Identity Provider profile should be created.

8.png

 

5. Test it out – SSO Test Run

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

  • **You will need access to 2 different types of browser**,such as IE and Chrome, or Firefox and Safari. One browser is for enabling setup, the other is for testing. DO NOT attempt setup and test in the same browser. Once SSO is enabled for a system, you can no longer login using regular Brightidea login method. Before the setup is validated, you want to avoid being locked out because of failed SSO attempts.
  • **Inform existing system user on service interruption**. If your Brightidea system is already live with regular user accessing, it’s best to perform sso testing on an off hour. If your system has yet launched, be sure to notify pre-launch user on testing schedule.

Follow the steps below. It uses Chrome and Firefox in the instruction.

  • In Chrome, navigate to Enterprise Setup, then Authentication Tab à Auth Selection Sub Tab. You should see a SSO profile listed under the regular Brightidea login method.
  • Check the method and click “Save Changes”. This will disable the regular Brightidea login method, and allow user access through SSO only.

9.png

  • Keep the Chrome browser open, and open Firefox, then enter the Brightidea system URL in the address bar.

  • Browser will trigger SSO by sending SAML Authentication Request to the endpoint set in the “Single Sign-on” field of the Identity Provider Profile Setting.

10.png

 

  • The user experience at the Single Sign-on Service page is dependent on your company Identity Management system setup.
  • The screenshot below is an example of the authentication interface of a company’s Identity Management system. Your company’s authentication interface may not look like this.
11.png
  • In this example, we assume the user have yet authenticate with your company. The browser prompts for user login. If the user has already logged in, user may not see any browser content from your company.
  • 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.
12.png
  • If the SAML Response is valid, user will enter into the Brightidea system.
13.png
  • 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.
14.png

6. Customize SSO Settings

A SSO integration can be customized 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.

15.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

  • 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.
16.png

 

SAML Response example with user profile attributes:

      ...

      <saml:Attribute Name="Lastname" 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="Jobtitle" 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="Firstname" 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.

17.png

      ...

      <saml:Attribute Name="groupName" 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>   

      ...

  • 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.
18.png

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. 
19.png

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> ...

 On user access, the hex value will be converted to the appropriate image format, and uploaded as user profile image.

 

7. Support SSO Logins

Brightidea system provides tools to help admin support user SSO login.

Support Setting

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. 

20.png

 

21.png

 

Transaction Log

Every user access is recorded. Admin can review the records through the “SAML Transaction Log”. Click on the “Go to SAML Transaction Log” link, and the log list would display.

22.png
23.png
  • 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.
24.png

 

8. Troubleshoot an User Login Error

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.

 

25.png

Troubleshoot Steps

  • Open SAML Transaction Log from Enterprise Setup-->Authentication Tab-->SAML Selection Sub-tab
  • 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.
26.png
  • 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.
27.png

9. Error Message Reference

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.

9.1  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.

iPhone App: https://itunes.apple.com/us/app/brightidea/id411310693

Android App: https://play.google.com/store/apps/details?id=com.brightidea.brightidea&hl=en

9.2  SSO Logon in Mobile App

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”.

28.png

 

  • If SSO integration is setup correctly, the app will invoke browser within app, and redirect user to your company’s user authentication page.

29.png

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!
30.png
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk