Shibboleth interconnection

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

Please note that, depending on your installation and the version of Shibboleth used, the options shown 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 metadata URL or 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 metadata

Once your IDP metadata file is uploaded to LockSelf, you can retrieve the application metadata that will be used to create the connector at the following URL:

https://FQDN/saml2/metadata

(where FQDN stands for 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 LockSelf application metadata can be retrieved (retrieved in step 2)
• "MetadataURL" must correspond to the access URL for the LockSelf metadata. FQDN is to be replaced with 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 will 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 base it on 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 from your IDP. You will need to adapt this value depending on the configuration of that IDP

Step 6: Check the connection

Once these steps are done, you can test the connector:

• Step 1: In order to test correctly, open a private browsing window and go to your infrastructure's URL (https://FQDN/?sso). If you use the browser extension, click on the gear wheel, then on "Clear cache".
  
• Step 2: On the SSO tab, enter your email in the displayed field or click directly on the "Log in" button.
  • If it does not work, on the login page, click on the gear wheels at the top right and check that the API URL field does indeed have /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: At this stage 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 sometimes needs to 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, in the SSO module. To do this, see this documentation: Configuring the SSO interconnection.