SAML2.0: How to connect to AD FS

Jump to:

STEP 1: Generating the Token Signing Certificate and obtaining the URL of the AD FS machine

STEP 2: Get the Issuer URL for the AD FS server

STEP 3: Get the SAML Endpoint for the AD FS machine

STEP 4: Set up the Trust Relationship on the AD FS machine

STEP 5: Configure the SAML 2.0 Connection in YAROOMS

STEP 6: Complete settings for the Trust Relationship on the AD FS machine

🔄 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 panel and click the "Certificates" node.
Double click the "Token Signing" certificate to view it.
Click the "Details" tab and then click on the "Copy to File" button.
Save the certificate in DER format (see photo below)

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:
https://yarooms.westeurope.cloudapp.azure.com/FederationMetadata/2007-06/FederationMetadata.xml
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: https://yarooms.westeurope.cloudapp.azure.com/adfs/services/trust

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:

https://yarooms.westeurope.cloudapp.azure.com/adfs/ls/

‼️ 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 DirectoryMapping 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 Settings → 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 Email to: Ahttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  - 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

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 (photo below).
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" tab.

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 the YAROOMS "Application details" page.

⚠️ This tutorial does not cover user provisioning and assignment in AD FS. It assumes you are already familiar with configuring AD FS settings specific to your organization’s user setup. Assigning user access to the newly configured YAROOMS app is one of these settings.