Encap

The Authentication Service can be configured to allow users to authenticate against an Encap server from Encap A/S. The Encap authenticator supports both authentication and registration. The registration can be configured to be allowed during login or not, on a per authenticator basis.

When a user is prompted to login using Encap, the first screen they will see is one where they will enter their username:

../../_images/enter-username.png

Fig. 73 Entering a username to find the devices associated with a user

Note

The username will be saved and automatically filled in on subsequent logins and will also be used in other authenticators that require a username (e.g., SMS and HTML forms).

After the user enters their username, they will be presented with a list of devices that are associated with their account.

../../_images/multiple-devices.png

Fig. 74 Multiple Encap devices associated with a user

If registration is allowed during login, they will also be given the opportunity to add a new device.

../../_images/no-device-add-new.png

Fig. 75 No Encap device associated with a user

If not, they will be presented with information about how to add a new device.

../../_images/no-devices.png

Fig. 76 No Encap device associated with a user without the possibility to add one

Basic Configuration

To configure an Encap authenticator, an authenticator element needs to be created in an authentication service profile like all other authenticators. This configuration will look something like this:

<config xmlns="http://tail-f.com/ns/config/1.0">
  <profiles xmlns="https://curity.se/ns/conf/base">
    <profile>
      <id>...</id>
      <type xmlns:auth="https://curity.se/ns/conf/profile/authentication">auth:authentication-service</type>
      <settings>
        <authentication-service xmlns="https://curity.se/ns/conf/profile/authentication">
          <authenticators>
            <authenticator>
              <id>${ID}</id>
              <required-authenticator-for-registration>
                ${REGISTRATION_ACCOUNT_MANAGER}
              </required-authenticator-for-registration>
              <encap>
                <account-manager>${ACCOUNT_MANAGER}</account-manager>
                <encap-server-url>${ENCAP_SERVER_URL}</encap-server-url>
                <client-key-id>${ENCAP_SERVER_CERT}</client-key-id>
                <client-id>${ENCAP_CLIENT_ID}</client-id>
                <application-id>${ENCAP_APP_ID}</application-id>
                <api-key>${ENCAP_API_KEY}</api-key>
                <authentication-app-download-uri>${DOWNLOAD_URL}</authentication-app-download-uri>
              </encap>
            </authenticator>
          </authenticators>
        </authentication-service>
      </settings>
    </profile>
  </profiles>
</config>

The meaning of these configuration elements is described in the following table:

Configuration Element Default Value Mandatory Meaning
id N/A true The identifier of the Encap authenticator
required-authenticator-for-registration N/A true The authenticator to run when registration is performed
encap/account-manager N/A true The account manager that will provide and store device data for users
encap/encap-server-url N/A true The URL of the Encap server (including scheme, hostname, port, and path)
encap/client-key-id   true The signing key used to sign requests send to the Encap server
encap/client-id N/A true The Encap client identifier
encap/application-id encap false The Encap application identifier (as set or compiled into the mobile app)
encap/api-key N/A false The API key used to authenticate to the Encap test server
encap/authentication-app-download-uri \# false The URL where users can download the Encap application from
encap/allow-registration-during-login true false Whether or not users should be able to register a new device during login
encap/show-info-before-registration true false Whether an informational page should be shown to users before registration

Registration During Login

Depending on the circumstances, you may or may not want to allow a user to add a new device during login. In general, users should not be allowed to add a new device when the service provide they are accessing is a mobile app. This is the case because it can be very cumbersome to register a new device when on the same mobile. This is especially true if the Encap authentication app isn’t yet installed on the user’s device. In this case, it is better to direct them to a place where they can provision a new device using a laptop or desktop computer. To easily implement this best practice, set the encap/allow-registration-during-login setting to false.

Additional Information Before Registration

When registration is allowed during the login flow, a user will be given the option to add a new device after entering their username. Because required-authenticator-for-registration must be set to a valid authenticator, the user will be prompted to login as soon as they see this button. This can be jarring if the user isn’t aware of why they are being asked to login. To give them this context, the encap/show-info-before-registration setting can be set to true (the default). If true, the user will be shown an anonymous page after electing to add a new device. This page can contain information about what Encap is and the download URL will be available, so the templatized view can render a link to allow the user to install it on their device.

The default view for this page is shown in the following figure:

../../_images/extra-info-page.png

Fig. 77 Encap - Information page

Automatic Login

When enabled, automatic login is available after successfully registering a new device.