Integrating YuJa Active Learning into ADFS via SAML

Integrating YuJa Active Learning into ADFS via SAML

1. Overview This document is intended to guide users on how to setup a secure connection between YuJa (the Service Provider, or SP) and ADFS (the Identity Provider, or IDP) using the SAML 2.0 protocol. Once properly configured, the SP and IDP will communicate using SAML 2.0 requests/responses in order to authenticate and login users. 2. Setup Setup involves configuration of both the IDP and the SP. 2.1 ADFS (IDP) Configuration Configuration of the IDP involves A) creating a Relying Party Trust (RPT) with YuJa, B) adding Claim Rules to the RPT so that SAML responses contain the correct information about the user, and C) adjusting the hash algorithm of the RPT. Ensure that all 3 parts are completed so that configuration is done properly. NOTE: For some steps, <institution> is to be replaced by the wildcard DNS of the institution associated with YuJa. As an example, for https://hudson.yuja.com, <institution> would be replaced by hudson. A) To Create a Relying Party Trust: 1. On the ADFS server, open the application ADFS Management 2. In the left panel, under Trust Relationships, click on Relying Party Trusts. 3. In the Actions tab, click on Add Relying Party Trust. 4. In the Add Relying Party Trust Wizard window, click Start 5. If you have the YuJa SP metadata, enter it using the appropriate option (either the address or file), and press Next. Follow the steps below, then skip Step 6. If not, proceed to step 6. a. Enter a display name for the RPT (e.g. YuJa ). Click Next. b. Select I do not want to configure multi-factor authentication settings for this relying party trust at this time. Click Next. c. Select Permit all users to access this relying party. Click Next. d. Review the settings to make sure everything is correct, then click Next. e. Make sure to have Open the Edit Claim Rules dialog for this relying party trust when the wizard closes selected, then click Close. Proceed to Step 2 of part B). 6. Select Enter data about the relying party manually, press Next and follow the steps below: a. Enter a display name for the RPT (e.g. YuJa ). Click Next. b. Select ADFS Profile and click Next. c. On the Configure Certificate step, click Next. Do not encrypt claims sent to YuJa. d. Select Enable support for the SAML 2.0 WebSSO protocol. For the Relying party SAML 2.0 SSO service URL enter: https://<institution>.yuja.com/d/samlreceiveresponse, without the quotations. Click Next. e. For the Relying party trust identifier, enter: https://<institution>.yuja.com, without the quotations. Click Add, then click Next.

f. Select I do not want to configure multi-factor authentication settings for this relying party trust at this time. Click Next. g. Select Permit all users to access this relying party. Click Next. h. Review the settings to make sure everything is correct, then click Next. i. Make sure to have Open the Edit Claim Rules dialog for this relying party trust when the wizard closes selected, then click Close. Proceed to Step 2 of part B). B) To Add Claim Rules: 1. To create/edit claim rules, first click on the RPT. On the right panel, click Edit Claim Rules. 2. In the Edit Claim Rules window, click Add Rule... 3. Select Send LDAP Attributes as Claims and click Next. 4. Enter a Claim rule name. 5. Select Active Directory as the Attribute Store. 6. Create four claim mappings: LDAP Attribute E-Mail-Addresses Given-Name Surname <An attribute relating to the role of a user> Outgoing Claim Type E-Mail Address Given Name Surname Role NOTE: There are 3 roles that a YuJa user can be: Student, Instructor, and IT Manager. If the possible values for the Role attribute differ from these 3 options, provide all possible Role values to YuJa and they will map the values to one of the three options. 7. Click Finish. 8. Now, create a second claim rule. Click Add Rule. 9. Select Transform an Incoming Claim. Click Next. 10. Enter a Claim rule name. a. For Incoming claim type, select E-Mail Address. b. Note: This is assuming that each user in the ADFS system has an e-mail address associated with them. If this is not the case, select Given Name instead. 11. For Outgoing claim type, select Name ID. 12. For Outgoing name ID format, select Email. 13. Click Finish. 14. Click OK in the Edit Claim Rules window. C) To Adjust the Hash Algorithm: 1. Double-click on your RPT. 2. Go to the Advanced tab.

3. In the dropdown, select SHA-1. 4. Click OK. 2.2 YuJa Platform (SP) Side SAML Configuration Configuration of the SP involves integrating the ADFS server as an IDP, with YuJa as an SP. The only resource needed to help configure YuJa is the IDP metadata of the ADFS server. This can be downloaded by navigating to: https://<adfs domain>/federationmetadata/2007-06/federationmetadata.xml The.xml metadata file contains all the necessary information for configuration on the YuJa side. Once downloaded, follow the steps below on how to extract the parameters from the metadata to integrate ADFS with YuJa. 1. Navigate to your institution s YuJa domain (i.e. https://<institution>.yuja.com). 2. Login as an IT Manager. 3. In the Main Menu located in the top right corner, go to the Institution Management tab. 4. In the left sidebar, go to Integrations. 5. Under Select an API to configure, select SSO - ADFS (SAML).

6. Enter the following information: Attribute Required? Description ADFS SSO URL Yes - The URL used for SSO. This is where YuJa will send AuthnRequest tokens. - Found in the IDP metadata under: <IDPSSODescriptor> <SingleSignOnService> as the Location attribute. Note that for YuJa, an HTTP-Redirect binding is used. - For example: https://<adfs domain>/adfs/ls/ Name ID Format Yes - The format to be used by the SP and IDP when communicating about a subject. - Found in the IDP metadata under: <IDPSSODescriptor> <NameIDFormat> as the value of that tag. Note that, if available, emailaddress should be prioritized and used. - For example: urn:oasis:names:tc:saml:1.1:nameidformat:emailaddress

Remote Logout URL Currently not supported - Leave this value blank. ADFS Signing Certificate Fingerprint No, but strongly recommended - The unique fingerprint of the IDP s certificate used when signing SAML responses. - The thumbprint is not explicitly located in the metadata, but the certificate used to sign either the SAMLResponse or the Assertion is - See How to derive the fingerprint of a certificate in the Additional Tools section of this document for more details. - For example: 7j2mka9cfe2d09j23eefe01442f6a49d1222391f 7. Click Create. 8. Click OK in the confirmation dialog popup. 9. If required, you can update the configuration settings if you made a mistake. Simply click Save to keep the changes. 10. To test if the configuration is correct, click Test SAML Login. This should open a new tab and navigate to your ADFS server, prompting a login.

11. Enter valid login credentials and Login. 12. You should be redirected back to YuJa, signed in as a new user. NOTE: logging in as a new user may log the original account out. If so, log out of the newly created account and log back in as an IT Manager. Then navigate back to Institution Management Integrations SSO ADFS (SAML). 13. Once you have verified that the SAML SSO works, you can choose to activate the new authentication scheme for your institution. To do so, click Activate, then click OK in the confirmation dialog. IMPORTANT: Only activate the new authentication scheme after successfully performing a test login and are ready to make it available for all users in your institution. 2.3 (Optional) Dual Integration with LTI If your institution has enabled both LTI and SAML SSO access, then you have the choice to link the two integrations. By default, a user logging in via both LTI and SAML receives a separate YuJa account for each login. If your LTI provider is configured to authenticate users via their SAML credentials, it is possible to link the two accounts as the LTI provider will give YuJa a unique identifier for the user in the SAML system. 1. Configure your LMS to pass a custom LTI parameter called lis_person_sourcedid which contains the cross-matching SSO value. This can be an email, employee ID, or other field. YuJa will make use of this feature to link the two login techniques to the same account. 2. Obtain the specific attribute name used in the SAML Response token whose value corresponds to the unique identifier used by the LTI provider. a. For example, if the unique identifier is the user's email address, then the linkage attribute might be http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

b. A complete list of the possible attribute names can be found in the ADFS metadata file, in the Attribute tags. 2. Enter this value into the Linkage Attribute field. Note: This textbox will only appear if your institution has enabled LTI access. 3. Click Save. 4. Now, when logging in for the first time via ADFS (SAML), the YuJa system will search for a link with an LTI account using the value of the linkage attribute. If found, the SAML account will be linked to the existing account. Otherwise, a new account will be provisioned as normal. a. All logins past the first one will continue to link to the YuJa account created or found on the first login. 3. Usage Once both sides have been configured and the SAML SSO has been activated, it is easy to test and see if everything was done properly. 1. Go to the institution s YuJa domain (i.e. https://<institution>.yuja.com) and press Login. This should redirect the user to the ADFS server s login page. 2. Enter valid credentials and sign in. 3. Once authenticated, the user should be redirected back to YuJa and the login was a success. 4. Additional Tools 4.1 How to Derive the Fingerprint of a Certificate The fingerprint of the IDP s certificate is used for additional security purposes when the SP is verifying a SAML response from the IDP. To derive the certificate s fingerprint, follow the instructions below: 1. In the ADFS IDP metadata, extract the X509 certificate. This should be located under: <IDPSSODescriptor> <KeyDescriptor use= signing > <KeyInfo> <X509Data> <X509Certificate> 2. Once you have the certificate, go to the following website: https://www.samltool.com/fingerprint.php 3. Paste the certificate in the X509 cert textbox. 4. Make sure sha1 is selected as the Algorithm. 5. Click Calculate Fingerprint. 6. Copy the FingerPrint value generated. This is the value used in the database. Note: The fingerprint should be an array of 20 bytes for sha1.