SAML Single-Sign-On (SSO)

Transcription

1 C O L A B O R A T I V E I N N O V A T I O N M A N A G E M E N T Complete Feature Guide SAML Single-Sign-On (SSO)

2 1. Features 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. 2. Prerequisite In order to implement Single Sign-on (SSO) integration using the SAML SSO feature, the following conditions must be met: SAML 2.0 Your company s identity management system must have SAML 2.0 capability. SAML is a SSO industry standard protocol. To know more, visit: Technical Resource To setup SSO integration, you most likely need the assistants of SSO Technical Engineer from your company. 3. Feature Overview To get to the SSO feature in your Brightidea system, navigate to Enterprise Setup Authentication Tab. There you will see two sub tabs: Auth Selection & SAML Profiles. SAML SSO BRIGHTIDEA Page 2

3 3.1 Auth Selection Tab This sub-tab displays a list of authentication option available for the system. By default, it only shows two standard methods: Brightidea Login & Registration. When a SSO method added, it will show up in the list. 3.2 SAML Profiles Tab This sub-tab is where a SAML SSO method is setup. SAML 2.0 is the standard Brightidea uses for SSO integration. Tab contains four sections: Service Provider Info This section presents information of your Brightidea system as a SAML 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 a SAML 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 transaction log. SAML SSO BRIGHTIDEA Page 3

4 4. 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. 4.1 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. SAML SSO BRIGHTIDEA Page 4

5 Assertion Consumer Service An endpoint URL for receiving SAML Response, copy and paste it into your company s Identity Management SAML setup. If your 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 your Brightidea system as SAML service provider, copy and paste it into your company s Identity Management SAML 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 from this link and upload it into your company s Identity Management setup. 4.2 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 these settings a profile. SAML SSO BRIGHTIDEA Page 5

6 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. Single Sign-on Service An endpoint URL of your company s Single Sign-on service page. It will receive 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 autopopulated through Metadata upload. Assertion Attribute Name Mapping Brightidea Service Provider requires two assertion attributes from the Identity Provider when receiving SAML Response. SAML SSO BRIGHTIDEA Page 6

7 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 used in SAML Response. SAML Response example with and screen name attributes:... <saml:attribute Name="givenName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:attributevalue xmlns:xs=" xmlns:xsi=" 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=" xmlns:xsi=" xsi:type="xs:string"> johndoe@example.com </saml:attributevalue> </saml:attribute>... On Save Changes, a new Identity Provider profile will be created. SAML SSO BRIGHTIDEA Page 7

8 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. SAML SSO BRIGHTIDEA Page 8

9 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. The user experience at this step is dependent on your company Identity Management system setup. The screenshot below is an example of the login interface at a company s Identity Management system. Your company s interface may not look like this. SAML SSO BRIGHTIDEA Page 9

10 In this example, we assume the user have yet authenticate with your company. The browser prompts for user login. If already logged in, user may not see any browser content from your company. After authentication verified, your company s Identity Management system will send request to the Brightidea Assertion Consumer Service endpoint, passing SAML Response. This is the endpoint presented in the Service Provider Info section. If the SAML Response is valid, user will enter into the Brightidea system. SAML SSO BRIGHTIDEA Page 10

11 After login, verify user account accuracy by visiting your profile page. The key is to check whether screen name and 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. SAML SSO BRIGHTIDEA Page 11

12 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. 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. SAML SSO BRIGHTIDEA Page 12

13 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 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 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. SAML Response example with user profile attributes: SAML SSO BRIGHTIDEA Page 13

14 ... <saml:attribute Name="Lastname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:attributevalue xmlns:xs=" xmlns:xsi=" 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=" xmlns:xsi=" 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=" xmlns:xsi=" 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. SAML Response example with group attributes: SAML SSO BRIGHTIDEA Page 14

15 ... <saml:attribute Name="groupName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:attributevalue xmlns:xs=" xmlns:xsi=" 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. 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. SAML Response example with profile image attributes: SAML SSO BRIGHTIDEA Page 15

16 ... <saml:attribute Name="profile_image" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:attributevalue xmlns:xs=" xmlns:xsi=" xsi:type="xs:string">ffd8ffe000104a ffdb a0c140d0c0b0b0c f141d1a1f1e1d1a1c1c20242e c2 31c1c c f27393d38323c2e333432ffdb c0b0c180d0d c ffc b009b ffc4001f a0bffc400b </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. 7.1 Support Setting Admin can configure contact information for accessing user in the Support Setting section. User would only be exposed to the information when a SSO login error is encountered. Name Contact name of SSO error support. Contact of SSO error support. Telephone Contact phone number of SSO error support. Send alert to Enable to receive alert when a user encounters SSO login error. Expose support info Enable to display support contact info at the SSO login error screen. SAML SSO BRIGHTIDEA Page 16

17 7.2 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. SAML SSO BRIGHTIDEA Page 17

18 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. SAML SSO BRIGHTIDEA Page 18

19 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 , or direct contact by the user. Using the ID, you can troubleshoot for the cause of the issue. SAML SSO BRIGHTIDEA Page 19

20 8.1 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. 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. SAML SSO BRIGHTIDEA Page 20

21 8.2 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. SAML SSO BRIGHTIDEA Page 21

22 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: 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. 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. SAML SSO BRIGHTIDEA Page 22

23 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/ ) cannot be blank The error occurs when Brightidea Service Provider fails to receive valid Screen Name or 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. Process Assertion: Missing <saml:nameid> or <saml:encryptedid> in <saml:subject> The error occurs when the NameID element is missing from SAML Response. Below is an example of the NameID element in a proper assertion. SAML SSO BRIGHTIDEA Page 23

24 9. Brightidea Mobile Access through Single Sign-On Once Single Sign-On is setup for your system, user can use it to access Brightidea mobile app. 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: Android App: 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 address in input box and tab Next. SAML SSO BRIGHTIDEA Page 24

25 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! SAML SSO BRIGHTIDEA Page 25