Shibboleth interconnection

Interconnecting the LockSelf application with an identity federation is done through the SAMLv2 protocol. It is therefore possible to interconnect the application with your Shibboleth IdP.

Please note that, depending on the installation and the Shibboleth version used, the elements offered may vary slightly.

Step 1: Upload the IdP metadata to LockSelf

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

Retrieve the URL or the metadata file 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: Adapt the metadata-providers.xml file

This third step adds LockSelf to your list of service providers.

You will therefore need to add the following element to this file:

<MetadataProvider id="LockSelf"
  xsi:type="FileBackedHTTPMetadataProvider"
  backingFile="%{idp.home}/metadata/lockself-metadata.xml"
  disregardTLSCertificate="true"
  metadataURL="https://FQDN/saml2/metadata">
</MetadataProvider>

• "BackingFile" must correspond to the path where the metadata of the LockSelf application can be retrieved (retrieved in step 2)
• "MetadataURL" must correspond to the access URL for the LockSelf metadata. FQDN must be replaced by the domain name chosen for your installation

Step 4: Prepare the attributes

You must now prepare the attributes that will be sent by the IdP to the application. As a reminder, the three attributes to send are:

• firstname (containing the user's first name)
• lastname (containing the user's last name)
• mail (containing the user's email)

In the attribute-filter.xml file, you will need to create these attributes if they are not defined. For example:

<AttributeFilterPolicy>
  <AttributeRule attributeID="firstname">
    <PermitValueRule xsi:type="ANY" />
  </AttributeRule>
  <AttributeRule attributeID="lastname">
    <PermitValueRule xsi:type="ANY" />
  </AttributeRule>
  <AttributeRule attributeID="mail">
    <PermitValueRule xsi:type="ANY" />
  </AttributeRule>
</AttributeFilterPolicy>

Step 5: Bind the attributes

Once the attributes are created and usable, you will need to create the rules that bind a user's attributes to the name expected by the LockSelf application.

To do this, you will need to edit the attribute-resolver-ldap.xml file and use the example below:

<!-- LockSelf -->
<resolver:AttributeDefinition xsi:type="ad:Simple" id="firstname" sourceAttributeID="givenName">
  <resolver:Dependency ref="myLDAP" />
  <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="firstname" />
</resolver:AttributeDefinition>

<resolver:AttributeDefinition xsi:type="ad:Simple" id="lastname" sourceAttributeID="sn">
  <resolver:Dependency ref="myLDAP" />
  <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="lastname" />
</resolver:AttributeDefinition>

<resolver:AttributeDefinition xsi:type="ad:Simple" id="mail" sourceAttributeID="mail">
  <resolver:Dependency ref="myLDAP" />
  <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="mail" />
</resolver:AttributeDefinition>

• "sourceAttributeID" corresponds to the values coming from your IdP. You will need to adapt this value according to the configuration of that IdP

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 Shibboleth 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

An update of the token signing/encryption certificates must sometimes be performed on the Shibboleth 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.