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:

Fig. 59 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.

Fig. 60 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.

Fig. 61 No Encap device associated with a user

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

Fig. 62 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:

Fig. 63 Encap - Information page

Encap¶

Basic Configuration¶

Registration During Login¶

Additional Information Before Registration¶

Automatic Login¶