1-888-257-2278 Go to YuJa
  1. YuJa Help Center
  2. EqualGround
  3. Integrations

Integrating EqualGround with ADFS (SAML)

Avatar
YuJa Product Support
  • Updated

Admins can set up a secure connection between EqualGround and ADFS to authenticate users logging into EqualGround. To securely authenticate and log in users, please ensure EqualGround and ADFS have been configured by following the steps below.  

What Is Required for the ADFS Configuration

The ADFS configuration requires three steps, as listed below.

  1. Creating a Relying Party Trust (RPT) with EqualGround.
  2. Adding claim rules for the RPT so that SAML responses contain the correct information about the user.
  3. Adjusting the hash algorithm of the RPT. This ensures that all 3 parts are completed so that the configuration is done properly. 

Creating 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 (RPT). 
  3. In the Actions tab, click on Add Relying Party Trust. 
    The Relying Party Trust folder is shown within ADFS with the option to Add relying party trust highlighted.
  4. In the Add RPT Wizard window, click Start.
    The Add Relying Party Trust Wizard asking the user to start the process by completing several steps.
  5. Select Enter data about the relying party manually, and click Next.
    In the Select Data Source step, the option to Enter data about the relying party is selected, and the next button is shown highlighted.
  6. Enter a display name for the RPT (e.g. “EqualGround), and click Next.
    In the Specify Display Name step, a display name is entered and the Next button is shown highlighted.
  7. Select ADFS Profile and click Next.
    In the Choose Profile step, AD FS profile is selected and the Next button is shown highlighted.
  8. On you are on the Configure Certificate step, click Next. Do not encrypt claims sent to YuJa.
    The next button is shown highlighted in the Configure Certificate step.
  9. Select Enable support for the SAML 2.0 WebSSO protocol.
  10. Enter the Relying party SAML 2.0 SSO Service URL based on your zone. Important: If you have a custom EqualGround Platform URL, please enter that instead of the zone URL. 
    • US Zone: https://EqualGround.yuja.com/api/sso/samlReceiveResponse 
    • Canadian Zone: https://EqualGround-cz.yuja.com/api/sso/samlReceiveResponse 
    • European Zone: https://EqualGround-ez.yuja.com/api/sso/samlReceiveResponse
    • Australian Zone: https://EqualGround-az.yuja.com/api/sso/samlReceiveResponse
    • Custom URL: https://YOUR_CUSTOM_EqualGround_URL/api/sso/samlReceiveResponse
      • Example: https://hudsonu.EqualGround.yuja.com/api/sso/samlReceiveResponse
  11. Click Next.
    The configure URL step, has Enabled Support for SAML 2.0 Web SSO protocol selected and the next button is shown highlighted.
  12. For the Relying party trust identifier, enter the URL based on your zone. Important: If you have a custom EqualGround Platform URL, please enter that instead of the zone URL. 
    • US Zone: https://EqualGround.yuja.com 
    • Canadian Zone: https://EqualGround-cz.yuja.com
    • European Zone: https://EqualGround-ez.yuja.com 
    • Australian Zone: https://EqualGround-az.yuja.com 
    • Custom URL:  YOUR_CUSTOM_EqualGround_URL
      • Example: https://hudsonu.EqualGround.yuja.com
  13. Click Add, then click Next.
    In the configure identifiers step, a relying party trust identifier is shown added and the Next but is highlighted.
  14. Select I do not want to configure multi-factor authentication settings for this relying party trust at this time. Then click Next.
    In the Configure multi-factor authentication now step, the I do not want to configure multi-factor option is selected and the Next button is shown highlighted.
  15. Select Permit all users to access this relying party. Click Next.
    In the choose insurance authorization rules step, Permit all users to access the relying party is selected and the next button is highlighted.
  16. Review the settings to make sure everything is correct, then click Next.
    In the Ready to add trust step, the Next button is shown highlighted.
  17. Make sure to have Open the Edit Claim Rules dialog for this relying party trust when the wizard closes selected, then click Close.
    In the finish step, Open the edit claim rules option is checked and the next button is shown highlighted.

Adding Claim Rules

  1. To create/edit claim rules, first, click on the RPT. On the right-side panel, click Edit Claim Rules.
    In the AD FS application, the EqualGround Relying party is selected.
  2. Click Add Rule.
  3. Select Send LDAP Attributes as Claims and click Next.
    The edit claim rules window is shown with the Add rule button highlighted.
  4. Enter a Claim rule name (e.g. EqualGround).
  5. Select Active Directory as the Attribute Store.
  6. Create four claim mappings as shown in the table below, and then click Finish.
    Mapping of LDAP attributes to outgoing claim types:
    LDAP Attribute Outgoing Claim Type
    Email-Addresses E-mail Address
    Given-Name Given Name
    Surname Surname
    <An attribute relating to the role of a user(e.g. Admin)> Role

    The LDAP attributes are shown within a table for the LDAP attributes and their outgoing claim type.

  7. Now, create a second claim rule. Click Add Rule.
     The Edit claim rule window shown the Add rule button highlighted.
  8. Select Transform an Incoming Claim. Click Next.
    Transform an incoming claim is selected for the claim rule template and the next button is shown highlighted.
  9. Enter a Claim rule name. For Incoming claim type, select E-Mail Address. Important: 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.
  10. For Outgoing claim type, select Name ID. For Outgoing name ID format, select Email. 
  11. Click Finish.
    The claim rule information is filled out and the Finish button is highlighted.
  12. Click OK in the Edit Claim Rules window.
    The OK button is shown highlighted for the Edit claim rule window.

Adjusting the Hash Algorithm 

  1. Double-click on your RPT.
    The Engage relying party trust is selected from the AD FS application.
  2. Select the Advanced tab.
  3. From the Secure hash algorithm drop-down list, select SHA-1.
  4. Click OK.
    Advanced tab is selected for the EqualGround properties and SHA-! is selected for Secure hash algorithm.

EqualGround Configuration

After you've adjusted all settings in ADFS, you will be able to configure settings within EqualGround.

  1. Log in to EqualGround.
  2. Select Configurations and then select Integration Settings.
  3. From the Select Integrations drop-down menu, select SSO-SAML and enable Allow authentication via SSO.
    The EqualGround SSO SAML integrations page.
  4. You will need to fill out the information for each of the panels for the integration—General SSO Details, User Provisioning, Role Mapping, and Cross Integration with LTI 1.3. Follow the table below to fill out the information.
    Attribute Required? Description
    General SSO Details 
    SSO URL  Yes

    The URL used for the SSO. This is where EqualGround will send AuthnRequest tokens. Found in the IDP metadata as the “Location” attribute. Note: For EqualGround, an HTTP-Redirect binding is used.

    Example: “https:///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 as the value of that tag. Note: If available, email addresses should be prioritized and used.

    Example: urn:oasis:names:tc:SAML:1.1:nameid- format:emailAddress
    ADFS Signing Certificate Fingerprint Yes

    The unique fingerprint of the IDP’s certificate is used when signing SAML responses. The thumbprint is not explicitly located in the metadata, but the certificate is used to sign either the SAMLResponse or the Assertion. See How to derive the fingerprint of a certificate in the Additional Tools section of this document for more details.

    Example: 7j2mka9cfe2d09j23eefe11142f6a49d1222391
    User Provisioning 
    Given Name Attribute Yes

    The name of the attribute in the SAML response describes the user's given name (i.e. first name). Found in the IDP metadata. There is a section in the .XML file that should contain a list of tags. Enter the value for the “Name” key, under the appropriate given name.

    The value should be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    Family Name Attribute Yes

    The name of the attribute in the SAML response describes the user's family name (i.e. last name, surname). Found in the IDP metadata. There is a section in the .XML file that should contain a list of tags. Enter the value for the “Name” key, under the appropriate family name.

    The value should be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    Email Attribute Yes

    The name of the attribute in the SAML response describes the user's email address. Found in the IDP metadata. There is a section in the .XML file that should contain a list of tags. Enter the value for the “Name” key, under the appropriate email address. 

    The value should be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    Role Attribute Yes

    The name of the attribute in the SAML response describes the user's role. Found in the IDP metadata. There is a section in the .XML file that should contain a list of tags. Enter the value for the “Name” key, under the appropriate role.  

    The value should be: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
    Role Mapping
    Admin Mapping Yes

    A comma-separated list of values can be used. If the value received in the Role Attribute matches any of these values, the user will be provisioned as an IT manager.

    Example: IT Manager
    Instructor Mapping Yes

    A comma-separated list of values can be used. If the value received in the Role Attribute matches any of these values, the user will be provisioned as an instructor.

    Example: Instructor, Teacher, or TA
    Cross Integration with LTI
    SSO Linkage Attribute No A unique attribute that links the SSO with the LMS. This allows a user to be recognized as a single user regardless of whether they log in with their SSO or LMS. You will need to enter the name of the linkage attribute provided by your SSO.
    LTI 1.3 Linkage Custom Field No A unique attribute that links the SSO with the LMS. This allows a user to be recognized as a single user regardless of whether they log in with their SSO or LMS. You will need to enter the name of the custom field used to configure the LTI launch. 
  5. Once you have adjusted all required settings, click Save Changes to complete the integration. Note: You can test your SSO integration by selecting Launch SSO Login Page and logging in with your integration.
    The Save button is shown highlighted in The EqualGround SSO SAML integrations page.

Related articles