Single Sign On (SSO) Implementation Manual. For Connect 5 & MyConnect Sites

Transcription

1 Single Sign On (SSO) Implementation Manual For Connect 5 & MyConnect Sites Version 6 Release 5.7 September

2 What is Blackboard Connect Single Sign On?... 3 How it Works... 3 Drawbacks to Using Single Sign On... 4 Pre- Setup Requirements... 4 Configuring SSO for Connect 5 Senders... 5 Implementation Workflow... 5 SAML Attributes for Sender SSO... 5 Configuring SSO for MyConnect Recipients... 6 Implementation Workflow... 6 Attributes for SAML Assertion for MyConnect Web Portal... 6 About Certificates... 7 Uploading an SSO Certificate for Connect 5 Senders... 7 Uploading an SSO Certificate for MyConnect Users... 8 Generating a Self- Signed Certificate with Adobe Reader... 9 Version Version Version Contacting Client Care

3 What is Blackboard Connect Single Sign On? Blackboard Connect Single Sign On (SSO) allows users to access Blackboard Connect by authenticating into your website or community portal. Blackboard Connect offers two SSO capabilities: Message Sender SSO: Authenticates message senders (typically your employees) into their Connect 5 accounts. We refer to this as Sender or Connect SSO. Message Recipient SSO: Authenticates message recipients (typically your students, students parents, or community members) into your MyConnect Portal. We refer to this as Recipient or Portal SSO. How it Works Blackboard Connect s SSO uses Security Assertion Markup Language 2.0 (SAML 2.0) 1 and supports Identity Provider (IdP) Initiated SSO. 2 In this scenario, your organization is the identity provider (IdP) and Blackboard Connect is the service provider (SP). This approach makes the fewest assumptions about the customer s identity management infrastructure, requiring that you only need to be able to generate the SAML and post it to Blackboard Connect. Here is the authentication sequence: 1. A user authenticates into your website or community portal. 2. Your site presents the user with a UI element (a button, link, etc.) for Blackboard Connect. 3. The user clicks on the UI element in step Your site generates some SAML and redirects the user s browser to a URL at Blackboard Connect, posting the SAML to that URL. 5. Blackboard Connect s site processes the SAML. Assuming that the SAML is correct, the site will authenticate and redirect the user s browser into Blackboard Connect. 6. The user logs out from Blackboard Connect. If you provided a logout URL in the SAML in step 4, then Blackboard Connect will redirect the user s browser to that URL. This sequence is the same for both recipient and sender SSO, with the exception that the attributes you include in the SAML and whether the user authenticates into Connect 5 or the MyConnect Recipient portal. 1 SAML is an OASIS standard for the exchange of authentication data. If you are not familiar with SAML, we suggest that you look at the SAML page at Wikipedia, which is informative in its own right, and also contains links to more information about SAML: You should also look at the OASIS SAML 2.0 Technical Overview, which can be found here: In particular, you should read section 5.1.4, IdP-Initiated SSO: POST Binding, which describes the workflow that we use for Blackboard Connect s SSO. 2 For the standard description of this workflow, please see the OASIS document mentioned in the previous footnote. 3

4 Drawbacks to Using Single Sign On Blackboard Connects SSO is a powerful tool that can increase efficiency and convenience with your staff and community. However, there are four points that should be considered before committing to the SSO implementation. Please contact your Client Care Representative for if you have any questions on these points Ø If the part of your website that initiates SSO fails, your users will not be able to log into the Connect system. We do offer users the ability to create backup Connect 5 login credentials so that you can simply visit our web site to log into the Connect 5 message sender system. This option is not available for MyConnect portal web site. Ø SSO for MyConnect is not supported with the MyConnect for Mobile apps. The SSO will require the Recipients in your Community to log into the portal using the website and will prevent them from using the MyConnect mobile app for iphone or Android. Ø There will be high level of programming that will need to be provided by your Institution s tech team. This document and sample code is provided to assist you and your team in properly implementing SSO. Ø Proper implementation may take several days to set up, test, and launch. Pre-Setup Requirements Setting up SSO for your Connect 5 or MyConnect users is an advanced process that requires extensive knowledge of programming (SSO authentication, XML, SAML). MyConnect Access Portals: If you are setting up SSO to allow members of your community (parents, students, residents, etc.) to access their contact information message history, and subscription preferences in your Connect 5 account, you will need to have an active MyConnect portal site. Using SSO, community users and recipients can log into the MyConnect site using the same username and password they use to log into your website, without creating a separate user account. Users will be authenticated by clicking a link within your web site or by entering their credentials (assigned by your identity management system) to log into your custom login page before being directed to your MyConnect Site. Programming Resources: The SSO setup process requires knowledge of SSO authentication, SAML, and XML programming to be provided by your Institution in order to be properly implemented. If you are familiar or have access to a team of programmers that can do this, then you are a good candidate to proceed with SSO integration. NOTE: Blackboard Connect cannot provide programming services for this feature. 4

5 Configuring SSO for Connect 5 Senders This section explains how to configure SSO for Connect 5 senders. If you are looking for recipient SSO, refer to the next section. Implementation Workflow To configure Single Sign-On capabilities for Connect message senders: 1. SSO Setup: Upload an X.509 certificate (.cer) file into Blackboard Connect. After a successful upload, you will be given a Connect 5 SSO URL. This URL is the address you will use to post SAML when you initiate an SSO session. 2. User Setup: If the contacts for your users have already been entered into your Connect 5 account, your Client Care Representative can provide you with a spreadsheet of these users. Once you receive the spreadsheet, you will need to provide the Federation ID for each user and return the spreadsheet to your Client Care Representative. To add additional users who are not already in your Connect 5 account, you can create a.csv file and include the the following data for each user new user: Institution First Name Last Name Title Primary Phone Address Federation ID Once you ve completed your.csv file, send it to your Client Care Representiive who will perform the import into Connect User Login Page: Program an SSO login page for your website. SAML Attributes for Sender SSO Blackboard Connect recognizes the following two SAML attributes for sender SSO: FederationID: This required attribute is the ID provided in step 2 of the previous section. LogoutURL: (Optional, but strongly recommended). This attribute allows the user to be redirected to a web site of your choice once the user logs out of Connect 5. If you do not provide this attribute, then when the user will see a Connect 5 login page when they log out instead of being redirected to your website. 5

6 Configuring SSO for MyConnect Recipients Implementation Workflow 1. MyConnect portal setup: This is done by Client Care to prepare and configure MyConnect. 2. SSO Setup: Upload an X.509 certificate (.cer) file into Blackboard Connect. After a successful upload, you will be given a MyConnect SSO URL. This URL is the address to which you will post SAML when you initiate an SSO session. 3. User Setup: Upload contacts into Connect 5. For MyConnect portal SSO to work, your contacts must have addresses and reference codes. The address will serve as the SSO federation ID. Attributes for SAML Assertion for MyConnect Web Portal Blackboard Connect recognizes the following SAML attributes for portal SSO: FederationID: (Required). The Federation ID for the MyConnect portal must be an address for the user, unlike the FederationID attribute for Connect 5 sender SSO. ContactRefCode: Required. The user s Connect 5 reference code. FirstName: Required. First name of the user. LastName: Required. Last name of the user. LogoutURL: Optional, but strongly suggested. This attribute allows the user to be redirected to a web site of your choice once the user logs out of the MyConnect portal. If you do not provide this attribute, then when the user logs out they will see a portal login page, instead of being brought back to your website. MyConnect portal users will be associated with existing contacts previously uploaded into Connect 5. This association allows users to provide additional contact information and subscribe to notifications without changing the contact data that was previously uploaded. Contacts associated with a portal user will display a blue, person icon next to their name under the Recipients tab in Connect 5. 6

7 About Certificates A self-signed certificate (.CER file) is a public key that is required and will be uploaded in the Connect 5 Admin interface. Once uploaded, Connect 5 will present a URL for you to post your SAML. You can use the same selfsigned certificate for both the Sender and the Recipient SSO. Note that the certificate upload pages for Sender and the Recipient SSO are located on different sections within the Connect 5 Admin tab and each upload presents a different URL. Instructions for each SSO are outlined in the following sections. Uploading an SSO Certificate for Connect 5 Senders 1. Create your.cer certificate and log into your Connect 5 account. 2. Open the Admin Tab located at the top of the screen. 3. Select Settings from the left side navigation bar and select the Single Sign On Configuration Setup option on the screen. 4. Enable SSO using SAML by checking the box, and upload your.cer file here. Click SAVE when done. 7

8 Uploading an SSO Certificate for MyConnect Users 1. Log into your Blackboard Connect 5 account and open the Admin tab located at the top of your screen. 2. Select MyConnect Portals on the left side navigation bar. 3. Locate the MyConnect Site you want to create an SSO for and click on the SSO link located next to the portal under the SETTINGS column. If you do not have a MyConnect portal listed, please contact your Client Care representative to have one created. 4. Click the Enable Single Sign On using SAML checkbox and upload your.cer file using the Select button. 5. Click SAVE. This will enable your SSO and upload your certificate. Connect 5 will display the URL you will need to apply to your SAML assertion code. 8

9 Generating a Self-Signed Certificate with Adobe Reader The following instructions will produce a.pfx file (the private key with which you will sign the SAML that you post to us) and a.cer file (the public key that you will upload to us). The instructions vary slightly depending on what version of Adobe Reader you are running. We include instructions for versions 9, 10, and 11. Version 9 In the menu bar at the top of the main window, click on Document and then click on Security Settings. Version 10 In the menu bar at the top of the main window, click on Edit, then click on Protection, and then click on Security Settings. Version 11 First, in the menu bar at the top of the main window, click on Edit, then click on Preferences, and then click on Security (Enhanced). Uncheck Enable Enhanced Security and uncheck Enable Protected Mode at Startup. Then exit and restart Adobe Reader. Then, in the menu bar at the top of the main window, click on Edit,, then click on Preferences, then click on Signatures, and then under Identities & Trusted Certificates click on More... From this point on, the instructions are the same for versions 9, 10, and 11. In the pane on the left, select Digital IDs. Then, just to the right, click on Add ID. Then select the radio button for A new digital ID I want to create now and click Next. On the next screen, where it asks you where you would like to store the new certificate, select the radio button for New PCKS#12 digital ID file, and then click Next. On the next page, the one that says Enter your identity information to be used..., you must enter at least a name and address. Then click Next. On the next screen, you will be prompted for a password, and for where to store the.pfx file. Enter whatever you like and click Finish. You should be brought back to the window where you first clicked on Add ID. In this window, select the ID you just created, and then click on Export. On the next screen, select the radio button for Save the data to a file and click on Next. On the next screen, change Save as type to Certificate File (*.cer), and click on Save. 9

10 Contacting Client Care Please contact Blackboard Connect Client Care if you have any questions regarding the information in this manual. Also check out our new support website Behind the Blackboard, where you can find more information about Connect s special features as well as share ideas with other schools and institutions. Phone Support: Support: [email protected] 10