ADFS Interconnection

Connecting the LockSelf application to an identity federation is done via the SAMLv2 protocol. It is therefore possible to connect it with your ADFS company account.

Before establishing this connection, you will need to verify that the IDP can negotiate HTTPS requests in TLS 1.2 minimum to configure the connector automatically. Versions below TLS 1.2 or SSL versions are disabled on the LockSelf web server for security reasons.

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

Note: depending on the Windows Server versions used, screenshots and available options 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. For this, refer to this documentation: SSO Interconnection Configuration (private cloud only).

Step 2: Retrieve the application metadata

Once you have uploaded your IDP metadata file to LockSelf, you will be able to retrieve the application metadata that 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 perform these operations, you will need to connect to your Windows server and go to the ADFS module.

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

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

As mentioned in the preamble, two options are available for configuring the connector.

If your ADFS supports TLS 1.2 minimum connections, you will have the option to choose the first option, which allows loading the configuration from a URL. In that case, select the first checkbox and enter the LockSelf application metadata URL:

If you encounter 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 XML file (available by going directly to the Step 2 URL) and place this file on the ADFS server. Once done, you can click "Browse" and find your file.

Once done, click "Next".

• Step 3: Choose a name for the connector. This name is indicative — you can choose whichever you wish. You can also add a note about the connector.

• Step 4: Choose your connection policies. We recommend not configuring MFA at this step, in order to be able to run the first tests without restrictions. Once the tests have been carried out and validated, you can return to this connector and change this configuration point.

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

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

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

•  
  • Once finished, click "Next" then "Close". A new window will appear for the creation of claims rules.

Step 4: Create the first claim

The first claim will allow sending several pieces of information about the user to LockSelf — specifically their last name, first name, and email address to authenticate them 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:
  • Enter a claim name in the first field. This name is for reference only.
  • In the "Start" dropdown menu, select "Active Directory". Then map the attributes as shown in the screenshot below:

The items in the first column are to be selected from the list. Note: if your directory is in French, Surname is listed as Nom.

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

Step 5: Create the second claim

The second claim will allow sending the user's name ID to the LockSelf application.

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

• Step 2: The attribute name is again for reference only.
  • In the first dropdown Incoming Claim Type, choose "UPN".
  • In the second dropdown Outgoing Claim Type, choose "Name ID" (note: on French ADFS instances, the field is called ID de nom).
  • Finally, in the last dropdown Outgoing name ID format, choose "Email".

Click "Finish".

Step 6: Verify the connection

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

• Step 1: To test correctly, open a private browsing window and go to your infrastructure URL (https://FQDN/?sso). If you are using the browser extension, click on the gear icon, then on "Clear cache".
   
• Step 2: On the SSO tab, enter your email in the displayed field or click directly on the "Sign in" button.
  • If this does not work, on the login page, click on the gear icons in the top right corner, and verify that in the API URL field there is /api/ at the end of the dedicated domain name. For example: https://votreentreprise.lockself-cloud.com/api/, https://lockself.votreentreprise.com/api/, etc...
     
• Step 3: 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.

Refer to this documentation if needed: SSO (Single Sign-On) connection.

Step 7: Update the connector

Two cases require updating the connector.

• Case 1: A signing certificate / token encryption update sometimes needs to 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, in the SSO module. For this, refer to this documentation: SSO Interconnection Configuration (private cloud only).
   
• Case 2: When an SSL certificate update is made to your LockSelf installation, you will need to update the connector in the ADFS module.
  • If you created the connector via URL: you can right-click on the connector and click "Update from Federation Metadata":
    
  • If you created the connector via the application metadata file, you will need to update it 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] is the name of the connector and [FederationMetadata.xml] is the path to the application metadata file.
        • Before running this command, we recommend reading the official Microsoft documentation on the subject: https://docs.microsoft.com/en-us/powershell/module/adfs/update-adfsrelyingpartytrust?view=windowsserver2022-ps