Configuring AD FS SAML 2.0 Integration is a back-and-forth process between setting up the AD FS machine and the YArooms Integrations.
Please note that AD FS SAML can be integrated with YArooms only if all LDAP accounts meant to use the integration have valid email addresses attached.
Step 1. Generating the Token Signing Certificate and obtaining the URL of the AD FS machine
On the AD FS machine, navigate to Administrative Tools -> AD FS Management. Expand the Services directory tree in the left pane and click the Certificates node. Double click the Token Signing certificate to view it. Click the Details tab and then select Copy to File. Save the certificate in DER format.
Use a convenient tool to convert the saved file into PEM format, required by the YArooms SAML Integration mechanism. Examples are OpenSLL or online conversion tools, like SSLShopper, RapidSSLOnline etc.
Store the resulting hashed string for later use.
With the Certificate still open, click the General tab. Under Issued to and Issued by there is the external (server) URL of the AD FS machine. In this example the value is https://yarooms.westeurope.cloudapp.azure.com. Store this value for later use.
Step 2. Get the Issuer URL for the AD FS server
Close the certificate window and click on Services -> Endpoints. Scroll to Metadata section and look for the item Type: Federation Metadata.
Get the URL Path and add it to the server URL stored above. For this example, the resulting value is:
Access the link and open the target xml file.
Look for the value of the entityID property and copy it - this is the Issuer URL. For this example, the value is
Step 3. Get the SAML Endpoint for the AD FS machine
Get back to the Endpoints list and scroll to Token Issuance section. Look for the item Type: SAML 2.0/WS-Federation and copy the value. Add this to the server URL obtained in step 1 to get the SAML Endpoint of the AD FS server.
For this example, the value is:
Note: The slash at the end of the URL is mandatory.
Step 4. Set up the Trust Relationship on the AD FS machine
Click on Trust Relationships -> Relying Party Trusts in the left panel, then Add Relying Party Trust in the right panel. This will start the Wizard for adding a new Trust Rule. The steps for this process are:
- Select Data Source: Enter data about the relying party manually
- Specify Display Name: A display name, such as YArooms SAML
- Choose Profile: AD FS Profile
- Configure Certificate: Leave data in this step blank.
- Configure URL: Check Enable support for the SAML 2.0 Web SSO Protocol. In the input box that activates type a placeholder URL (like your YArooms domain URL). This value will be edited later.
- Configure Identifiers: Type a placeholder URL and click Add. This value will be edited later.
- Configure Multi-factor Authentication Now: Check I do not want to configure multi-factor...
- Choose Issuance Authorization Rules: Permit all users to access this relying party.
Complete the Wizard and open the Edit Claim Rules Dialog. In the Issuance Transform Rules tab click Add Rule.
- Choose Rule Type: Send LDAP Attributes as Claims
- Config Claim Rule:
- Claim rule name: type a name for the rule
- Attribute Store: Active Directory
- Mapping of LDAP attributes: create the next pairs of [LDAP Attribute : Outgoing Claim Type] values:
- User-Principal-Name : Name ID
- Given-Name: Given Name
- E-Mail-Addresses : E-Mail Address
- Surname : Surname
Step 5. Configure the SAML 2.0 Connection in YArooms
Login as an administrator to your YArooms domain. Navigate to Integrations -> SAML 2.0 Authentication and start the integration process. In the Connection tab, fill in the form as follows:
- Identity Provider: type AD FS (this is a label, any value is accepted, it will appear on the login page as "Authenticate with AD FS")
- Issuer URL: the Issuer URL link obtained and copied at step 2.
- SAML Endpoint: the SAML Endpoint URL obtained and copied at step 3.
- X.509 Certificate: the hashed string in PEM format obtained at step 1 (the ‘Begin Certificate’ and ‘End Certificate’ comments at the beginning and end of the hash are optional)
- Name ID Format: choose unspecified as value.
- Attributes Mapping:
- Map First Name to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- Map Last Name to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- Map Email Address to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Save options and navigate to User options tab. Set default group and location for the new users, created with data from the Identity Provider.
Save User options and navigate to Application details tab. Activate SAML Integration. The values present in this tab will be used in next step. Please note these are placeholders and actual URLs will be dependent on your YArooms account.
Step 6. Complete settings for the Trust Relationship on the AD FS machine
Return to the AD FS machine and edit the Relying Party Trust.
- In the Advanced tab, set Secure hash algorithm to SHA1
- In the Identifiers tab add a Relying party identifier with the URL listed as Entity ID in the YArooms Application details.
- In the Endpoints tab click Add SAML.
- Set Endpoint type to SAML Assertion Consumer
- Set Binding to POST
- Set Trusted URL to the ACS (Consumer) URL value from YArooms’ Application details.
Note: Proper user provisioning and assignment in AD FS are not topics covered by this tutorial which assumes you already know how to configure AD FS options that are specific to how your organisation sets up its users. The assignment of access for users to the newly configured YArooms app is one of these topics.