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
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 system, navigate to Enterprise Setup > Access tab.
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 to keep Brightidea login or only enable your SAML profile. If you choose to only 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 setup. The 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 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. It’s likely that an SSO Engineer from your company is needed for the configuration.
Login as an administrator, and then navigate to Enterprise Setup > Authentication > SAML Profiles (sub-tab)
The first step of the 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 Responses, copy and paste it into your company’s Identity Management setup. If the given Brightidea system has multiple domains 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 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> ... |
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.
- 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 setup, you can give it a test. But before testing 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 "off hours". If your system has not yet launched, be sure to notify pre-launch users on 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 Enterprise Setup, then Access (Tab) > Authentication (Sub Tab). 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 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 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 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 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: 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 the 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 the system. Only users who have existing accounts in system (possibly from manual user import) can access. The system uses either email address or the value from the “NameID” attribute 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 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 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 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 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 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 avuser 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 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: The Brightidea system provides tools to help admins support user SSO logins. Admins can configure contact information for accessing users in the “Support Setting” 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 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 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 existing account with all additional info provided in SAML assertion.
- If an account is not matched based on Employee ID (NameID), check if one (1) user account exists with same email address and without Employee ID
- If account is matched based on email address, log in and update existing account with all additional info provided in SAML assertion.
- If account is not matched based on email address, create the account
- Note: This scenario may create 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 email/employee ID, user may fail to log in and an error may be generated.
- Check if Employee ID (NameID) matches to an existing account:
- If user logs in and Employee ID (NameID) is passed to Brightidea through SSO:
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.
- 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, 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 an SSO login error, a Reference ID would 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:
- 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. Admins 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. The list will filter based on the ID.
- Once the targeted record is found, click on the Transaction ID to view details.
- 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 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 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 an 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: Requester: Signature required: The SAML request sent by Brightidea is unsigned while the Identity Provider Service requires signature. Check the "Sign Authentication" setting and toggle the signature method required by the Identity Provider.
- 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.
- 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
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.
Comments