ADFS interconnection

Interconnecting the LockSelf application with an identity federation is done through the SAMLv2 protocol. It is therefore possible to interconnect it with your ADFS enterprise account.

Before establishing this interconnection, you will need to verify that the IdP can negotiate HTTPS requests in TLS 1.2 minimum in order to configure the connector automatically. Versions lower than TLS 1.2 and SSL versions are disabled on the LockSelf web server for security reasons.

If your IdP configuration does not allow this, you will need to set up a manual configuration.

Please note that, depending on the Windows Server versions used, the screenshots and the options offered may vary slightly.

Step 1: Upload the IdP metadata to LockSelf

This first step consists of retrieving the metadata file from your IdP.

Generally, the metadata file (XML format) can be retrieved via the following URL: https://FQDN/FederationMetadata/2007-06/FederationMetadata.xml

(where FQDN replaces the domain name of your IdP)

Retrieve this URL and enter it in the LockSelf application. To do this, see this documentation: Configuring the SSO interconnection (private cloud only).

Step 2: Retrieve the application's metadata

Once your IdP metadata file has been uploaded to LockSelf, you can retrieve the application's metadata, which you will use to create the connector, at the following URL:

https://FQDN/saml2/metadata

(where FQDN replaces the domain name of your LockSelf installation)

Step 3: Create the connector on the IdP

To carry out these operations, you will need to log in to your Windows server and go to the ADFS module.

• Step 1: Once on the module, click "Add Relying Party Trust"

• Step 2: Then click "Start" to begin the configuration

As indicated in the preamble, you have two options for configuring the connector.

If your ADFS allows connections in TLS 1.2 minimum, you will be able to choose the first option, which loads the configuration from a URL. In this case, select the first checkbox and enter the metadata URL of the LockSelf application:

If you get an error at this step, you have two solutions:

• Either enable TLS 1.2 support on the ADFS module: https://docs.microsoft.com/fr-fr/windows-server/identity/ad-fs/operations/manage-ssl-protocols-in-ad-fs#enable-and-disable-tls-12 ;
• Or use the second option "Import data about the relying party from a file".

To do this, you will need to retrieve the application's XML file (available by going directly to the URL from step 2) and place this file on the ADFS server. Once done, you can click "Browse" and look for your file.

Once this is done, click "Next".

• Step 3: Choose a name for the connector. This name is for reference only; you can choose whichever you want. You can also add a note about the connector.

• Step 4: Choose your connection policies. We recommend not configuring MFA at this step, so that you can run the first tests without restriction. Once the tests have been carried out and validated, you can come back to this connector and change this configuration point.

• Step 5: Now choose the access policy to this connector per user. For connection tests, we recommend allowing all users to connect. You can apply a restriction later, once the installation has been verified and validated.

• Step 6: Once you have clicked "Next", you will check several tabs of the final summary.
  • In the Identifiers tab, check that the application's metadata URL is present:

• • In the Encryption and Signature tabs, check that the certificate corresponds to the certificate of your LockSelf installation.
    
  • In the Endpoints tab, check that you have the two URLs as shown in the screenshot below:

• • Once finished, click "Next" and then "Close". A new window then appears for creating the claim rules.

Step 4: Create the first claim

The first claim will allow several pieces of information about the user to be sent to LockSelf. In particular their last name, first name and email so that they can be authenticated in the LockSelf application.

• Step 1: Click "Add Rule"

• Step 2: Select "Send LDAP Attributes as Claims" from the list, then click "Next"

• Step 3:
  • Type a claim name in the first field. This name is for reference only.
  • In the "Start" select menu, select "Active Directory". Then map the attributes as shown in the screenshot below:

The items in the first column must be selected from the list. Please note that if your directory is in French, Surname is shown as Nom.

The items in the second column must be typed in manually. These are the attribute names that must be retrieved by LockSelf. Be careful to respect them.

Step 5: Create the second claim

The second claim will allow the user's name id to be sent to the LockSelf application.

• Step 1: Click "Add Rule" again and choose "Transform an Incoming Claim" from the drop-down menu.

• Step 2: The attribute name is once again for reference only.
  • In the first drop-down menu Incoming Claim Type, choose "UPN"
  • In the second drop-down menu Outgoing Claim Type, choose "Name ID" (please note that for French ADFS, the field is ID de nom)
  • Finally, in the last drop-down menu Outgoing name ID format, choose "Email".

Click "Finish".

Step 6: Check the connection

Once these steps are completed, you will be able to test the connector:

• Step 1: To test properly, open a private browsing window and go to the URL of your infrastructure (https://FQDN/?sso). If you use the browser extension, click the gear wheel, then "Clear cache".
  
• Step 2: On the SSO tab, enter your email in the displayed field or click the "Log in" button directly.
  • If this does not work, on the login page, click the gear wheels at the top right and check that the API URL field correctly ends with /api/ after the dedicated domain name. For example: https://votreentreprise.lockself-cloud.com/api/, https://lockself.votreentreprise.com/api/, etc.
    
• Step 3: At this step, you will be redirected to your organization's ADFS SSO portal where you can authenticate.
  
• Step 4: Once authenticated, you will be redirected to LockSelf, which will ask you to create the PIN code associated with your account.

See this documentation if needed: SSO login (Single Sign-On).

Step 7: Update the connector

Two cases require an update of the connector.

• Case 1: An update of the token signing/encryption certificates must sometimes be performed on the ADFS connector. In this case, you will need to update the new IdP metadata file, in the Settings tab of the Administrator account, on the SSO module. To do this, see this documentation: Configuring the SSO interconnection (private cloud only).
  
• Case 2: When an update of the SSL certificates is made on your LockSelf installation, you will need to update the connector on the ADFS module.
  • If you created the connector via the URL: you can right-click the connector and click "Update from Federation Metadata":
    
  • If you created the connector via the application's metadata file, you will need to perform the update via PowerShell. To do this:
    • Open a PowerShell session as administrator

    • Run the command

      Update-AdfsRelyingPartyTrust -TargetName "[CONNECTOR_NAME]" -Metadatafile [FederationMetadata.xml]

      • Where [CONNECTOR_NAME] equals the name of the connector and [FederationMetadata.xml] equals the path of the application's metadata file.
        • Before running this command, we recommend reading Microsoft's official documentation on this topic: https://docs.microsoft.com/en-us/powershell/module/adfs/update-adfsrelyingpartytrust?view=windowsserver2022-ps