This guide shows administrators how to set up single sign-on (SSO) between Brightidea and your company's identity provider (IdP) with SAML 2.0. It also covers the support settings and the log you use to troubleshoot sign-in errors.
Before you start
| You need | Details |
|---|---|
| An identity provider | An IdP service or a similar identity management system, such as Okta, Ping Identity, Microsoft Azure, or OneLogin. Brightidea cannot provide technical support for your IdP. For IdP problems, contact the IdP provider. |
| SAML 2.0 | Your identity management system must support SAML 2.0. If it does not, Brightidea offers custom SSO as a paid service. Ask your Customer Success Manager. |
| A technical contact | An SSO engineer at your company who is allowed to change your IdP. If you do not have an SSO engineer, Brightidea offers a paid SSO support service, but someone at your company must still be able to change the IdP. |
Also read Things You Should Know Before Making Changes to Your SSO Configuration, which explains how to keep Brightidea Login on so you are not locked out.
Where the SSO settings are
The Access page has two tabs you use for SSO.
| Tab | What it has |
|---|---|
| Authentication | The sign-in methods for the system. It starts with two: Brightidea Login and Registration. Each SAML profile you add appears in this list. |
| SAML Profiles | The SAML setup, in four sections: Service Provider Info (details about your Brightidea system, for your IdP), Identity Provider Setting (details about your IdP), Support Settings (who users contact about SSO errors), and SAML Transaction Log (a record of SSO sign-ins). |
The Authentication tab.
The SAML Profiles tab.
Step 1: Exchange metadata with your identity provider
In this integration, Brightidea is the service provider and your identity management system is the identity provider. Each side needs the other's details.
Give your IdP the Brightidea details
- Sign in as an administrator and go to System Setup > Access > SAML Profiles.
- In Service Provider Info, select Download Metadata.
- Upload the metadata file to your IdP.
If your IdP needs the values one at a time, copy them from the same section:
| Field | What it is |
|---|---|
| Assertion Consumer Service | The address that receives SAML responses. If your Brightidea system has more than one domain, choose the address you want to use. |
| Entity ID of this System | The text that identifies your Brightidea system as a SAML service provider. |
| Download Metadata | A file with the service addresses and certificates that identify Brightidea as a service. |
Give Brightidea your IdP details
- In Identity Provider Setting, select Add New.
- Enter a SAML Profile Name.
- Under Upload Metadata, upload the metadata file you exported from your IdP.
- Check the fields that the upload filled in.
| Field | What it is |
|---|---|
| Upload Metadata | Your IdP metadata. The upload can fill in the other fields for you. |
| Single Sign-on Service | The address of your company sign-in service, which receives authentication requests from Brightidea. |
| Identity Provider Issuer | The text that identifies your IdP. |
| Upload Public Key | The certificate used to check the signature in a SAML response. SHA1, SHA256, and unsigned are all accepted. |
Step 2: Set the required attributes
Your IdP sends attributes about each user in the SAML response. Brightidea needs at least two:
| Attribute | What it holds |
|---|---|
| The email address of the user. | |
| Screen Name | The display name of the user, usually the full name. |
- In the profile, type the name of each attribute exactly as it appears in the SAML response.
- Select Save Changes.
Attribute names are case-sensitive. If the attribute is named "email", type "email". If it is named "emailAddress", type "emailAddress". If it is named "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailAddress", type that whole address.
Example of a SAML response with screen name and email attributes:
<saml:Attribute Name="displayName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue 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 xsi:type="xs:string">johndoe@example.com</saml:AttributeValue> </saml:Attribute>
Step 3: Test SSO
Before you test:
- Use two different browsers, for example, Chrome and Firefox. Change settings in one and test SSO in the other, so a failed test does not lock you out.
- If your system is live, tell users that sign-in may be interrupted, and test outside working hours. If it has not launched, tell your pre-launch users when you will test.
- In the first browser, go to System Setup > Access > Authentication.
- Select the SAML profile you want to test, keep Enable Brightidea Login selected, and select Save Changes.
- In the second browser, open the address of your Brightidea system.
- On the Brightidea login page, select the SSO button below the email and password fields.
- Sign in with your company credentials.
- Open your profile page and check that the screen name and email address are correct.
What you see after you select the SSO button depends on how your IdP is set up. After you sign in, your IdP sends a SAML response to the Assertion Consumer Service address shown in Service Provider Info. If the response is valid, you are signed in to Brightidea.
If the profile details are correct, SSO works, and you can invite other users to test it.
Step 4: Set the advanced options
Open an existing profile in Identity Provider Setting and select Configure Advanced Settings.
The advanced settings of a SAML profile.
| Option | What it does |
|---|---|
| Entity ID of this Profile | Starts as the Entity ID of this System value. You can set your own. |
| Logout URL | The page users land on after they sign out of Brightidea. |
| Authentication Binding | How Brightidea sends the authentication request: POST or REDIRECT. |
| Sign Authentication | The signature algorithm for the authentication request. By default, the request is not signed. |
| Create member on initial access | When on, Brightidea creates an account the first time a user signs in. When off, only users who already have an account (for example, from a user import) can sign in. |
| Update member on subsequent access | When on, Brightidea updates the profile of a returning user from the attributes in the SAML response. When off, the attributes do not overwrite the profile. |
| Combine first and last name to create screen name | Use this when your IdP cannot send a screen name. Brightidea builds the screen name from the first name and last name. |
| Profile attribute mapping | Map other attributes in the SAML response, such as location, department, or job title, to Brightidea profile fields. Ask the business owner of your Brightidea system which attributes to send. |
| Group Attribute | Map one attribute that holds group names. Separate several groups with semicolons. When the user signs in, Brightidea creates any group that does not exist, adds "AUTO_" to the start of its name, and adds the user to it. |
| Photo Attribute | Map an attribute that holds the profile photo of the user as the hex value of a .png, .jpg, or .gif file. When the user signs in, Brightidea converts it to an image and sets it as the profile photo. |
Example with profile attributes:
<saml:Attribute Name="userFirstname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">John</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="userLastname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue 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 xsi:type="xs:string">Sales</saml:AttributeValue> </saml:Attribute>
Example with a group attribute:
<saml:Attribute Name="group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">Group A;Group B;Group C</saml:AttributeValue> </saml:Attribute>
Example with a photo attribute (the value is shortened here):
<saml:Attribute Name="profile_image" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">ffd8ffe000104a46494600010200000100010000ffdb0043...</saml:AttributeValue> </saml:Attribute>
Support settings
In Support Settings, enter who users should contact when SSO fails. Users see this information only when they hit an SSO sign-in error.
| Setting | What it does |
|---|---|
| Name, Email, Telephone | The contact for SSO errors. |
| SSO Message | A message of up to 250 characters. Shows on the error screen. |
| Send alert to email address above | Sends an email to the contact when a user hits an SSO sign-in error. |
| Expose support info above to user | Shows the contact details on the SSO error screen. |
Select Save Support Settings when you finish.
Step 5: Turn on SSO
- Go to System Setup > Access > Authentication.
- Select the checkbox next to your SAML profile.
- Choose whether to keep Enable Brightidea Login and Enable Registration selected.
- Select Save Changes.
A SAML profile selected on the Authentication tab.
| Setting | What it does |
|---|---|
| Enable Brightidea Login | Shows the standard Brightidea login page. If you clear it while SSO is on, SSO starts as soon as someone opens your Brightidea site. |
| Enable Registration | Lets people create a standard Brightidea account with a password. If registration and SSO are both on, SSO users who also register can end up with duplicate accounts. Clear it if every new account should come through SSO. |
How Brightidea matches users
When a user signs in through SSO, Brightidea decides whether to use an existing account or create one. These steps assume you send an employee ID as the NameID, as recommended.
- Brightidea looks for an account with the same employee ID (NameID). If it finds one, it signs the user in and updates the account from the SAML response.
- If there is no match, Brightidea looks for exactly one account with the same email address and no employee ID. If it finds one, it signs the user in and updates that account.
- If there is still no match, Brightidea creates an account.
Step 3 can create a duplicate if the person already has an account under a different email address and employee ID. If email addresses and employee IDs conflict, the sign-in can fail with an error.
Troubleshoot SSO errors
Brightidea records every SSO sign-in. When a user hits an SSO error, Brightidea creates a Reference ID. You get the ID from the alert email or from the user, depending on your support settings.
- Go to System Setup > Access > SAML Profiles.
- At the bottom of the page, select Go to SAML Transaction Log.
- In the Reference ID column, paste the ID and press Enter to filter the list.
- Select the Transaction ID of the record to open its details.
- Read the Error Message field for the cause of the error.
- Read the Request/Response XML for the data that Brightidea and your IdP exchanged.
The log covers the last 30 days, and you can sort and filter every column.
| Error message | What it means |
|---|---|
| SAML 2.0 Artifact Binding is not supported | Your IdP is set to use Artifact Binding, which Brightidea does not support. Set your IdP to use POST binding. |
| Invalid message received to AssertionConsumerService endpoint | Your IdP sent an invalid SAML response. Check the transaction details to see the SAML response that was sent. |
| Missing <saml:Issuer> in message delivered to AssertionConsumerService | The SAML response has no Issuer element, which is required. Check the transaction details to see the SAML response that was sent. |
| The <saml:Issuer> of the response does not match the identity provider we sent the request to | The Issuer value in the SAML response is not the IdP that received the authentication request from Brightidea. |
| The required response parameter RelayState was missing | An IdP-initiated request arrived without the RelayState parameter. Send both RelayState and SAMLResponse in IdP-initiated requests. |
| No Identity Provider Profile Exists for this Issuer | The Issuer value in the SAML response does not match the Identity Provider Issuer field of any profile. |
| More than one assertion in the received response | The SAML response has several Assertion elements. A valid response has one. Check the transaction details to see the SAML response that was sent. |
| Received duplicate assertion | The assertion was already used for an earlier sign-in. |
| Process Assertion: SAML Profile Not Found | No SAML profile has the issuer found in the SAML response. Check the Identity Provider Issuer field of the profile. |
| Process Assertion: Requester: Signature required | Brightidea sent an unsigned request, and your IdP requires a signature. Set Sign Authentication to the method your IdP requires. |
| Process Assertion: The destination in response doesn't match the current URL | The Destination value in the SAML response is not the Brightidea Assertion Consumer Service address. Check the transaction details to see the SAML response that was sent. |
| Process Assertion: No assertions found in response from IdP | The SAML response has no Assertion element. Check the transaction details to see the SAML response that was sent. |
| Process Assertion: Missing certificate in metadata | The certificate uploaded in the profile is invalid. |
| Process Assertion: Identity Provider Data Error: Could not find encoded certificate in file | Brightidea cannot read the uploaded public key. Upload Public Key needs a certificate in plain text. |
| Process Assertion: Neither the assertion nor the response was signed | The SAML response is not signed. A valid signature is required. |
| Process Assertion: Received an assertion that is valid in the future, that has expired, or with a session that has expired. Check clock synchronization on IdP and SP | The clocks of your IdP and of Brightidea do not match. |
| Process Assertion: Missing required <saml:AuthnContext> in <saml:AuthnStatement> | The SAML response has no AuthnContext element. |
| Process Assertion: Error decrypting assertion: No private key found in metadata | Turn on Sign Authentication in the advanced settings and choose the algorithm you need. |
| This SP [...] is not a valid audience for the assertion. Candidates were: [...] | The entity ID does not match the Audience value in the SAML response. |
| Create Session: Unknown error creating user | An unexpected error happened when the user signed in. |
| Create Session: User does not have access to this campaign or affiliate | Add the user to a group, or assign the group of the user to the Initiative. |
| Create Session: User's domain may be restricted | Group assignment or domain restriction settings block the user from the Initiative. |
| Create Session: (Screen Name/Email) cannot be blank | Brightidea did not get a valid screen name or email address. Check that the attribute mappings in the profile are correct (they are case-sensitive). The user may also be new while Create member on initial access is off, or the account could not be saved. |
| Unable to Retrieve Metadata | The metadata uploaded in the profile is invalid. |
| System Configuration Settings Not Found | An IdP-initiated request reached a Brightidea system that has no identity provider profile. |
| Unable to load certificate/public key | The certificate or public key uploaded in the profile is invalid. |
SSO in the Brightidea Mobile app
To use SSO in the mobile app, your company needs a Brightidea Mobile subscription. Contact your Brightidea Account Manager to find out more.
For the download links and the sign-in steps, see Getting Started with Brightidea Mobile and Brightidea Mobile Single-Sign-On (SSO).
Comments