Overview of Authenticators

Before reading this chapter, it’s recommended that the reader has a good understanding of the general concepts of Authentication.

Authenticator purpose

Authentication

The main purpose of all Authenticators is Authentication. To verify that the users credentials or by other means determining the validity of the users request. Authentication results in a Session being created for the user, which later can be used to let the user pass through without re-authentication.

In order to perform the Authentication some Authenticators use Data Sources while others use external Authentication Providers, such as Facebook or Google. This is up to the internals of the specific Authenticator to decide.

Registration

Some Authenticators support registration and self-service. This could be everything from creating a brand new account, updating a phone number to adding a new device for Multi-factor Authentication (MFA). Authenticators using external Authentication providers do typically not support registration. Refer to the documentation for each authenticator type to find its capabilities.

Activation

Activation is the step of verifying a newly created account. This is the last step of registration and simply put, set the account in an active mode. Before activation is complete, the user may not authenticate with its newly created credentials.

Authenticator Base Configuration

All authenticators share a number of common configuration options. These define multi-factor flows, registration requirements, user account domains and more. Only a few parameters are specific for each type of authenticator.

The common parameters define:

ACR

ACR defines a contractual name for the authentication method that can be referenced between services. This is used in the acr parameter on authentication requests to allow the client to request a certain authenticator or certain authenticators. If no configured all authenticators are given a system defined acr that follows the following format

urn:se:curity:authentication:${AUTHENTICATOR TYPE}:${AUTHENTICATOR ID}

Example

An authenticator of type html-form with the configuration id html1 would be assigned the following ACR by default:

urn:se:curity:authentication:html-form:html1

Note

Plug-ins cannot change the ACR via authentication attributes. Any ACR attribute returned in an AuthenticationResult will be ignored.

Template Area

Most Authenticators show screens to the users for interaction. This is done by using the built in templating system of the Curity Identity Server. Each Authenticator can have it’s own look and feel, i.e. a per instance template. This is useful when different application need the Authentication Service to look according to their brand or layout. By configuring two instances of the same type of authenticator, but with different template areas, this can be achieved.

The template area configuration is defined in the configuration reference.

Account Domain

Account Domains provide a way to bundle authenticators together that use the same identity source. It is not necessary to do, and it’s not necessary that the source is the same physically. This used when accounts should be linked. The Authenticator that will link, will look for the target domain to show up, and when it sees it, it will perform the link.

It is not recommended to re-use the same account domain on differnt types of accounts. I.e. the facebook and google authenticators should not share account domain. But Html1 and Html2 may if they use the same credential store.

Note

The Facebook authenticator is setup with the ‘facebook’ domain, and the Html authenticator with the ‘local’ domain and with linking. When the Html authenticator sees a session with the ‘facebook’ domain, it will create a link in the ‘local’ repository.

Multi-Factor Settings

Multi-Factor Authentication (MFA) is trivial with the Curity Authentication Server. Authenticators can be linked together to form an authentication chain by configuring each authenticator with a previous authenticator as precondition. This will assert the following:

  • Before this Authenticator runs, make sure the user is authenticated with the previous
  • Before the previous Authenticator runs, make sure the user is authenticated with the previous of the previous
  • And so on.

Thus there is no limitation on how many factors can be combined to create a multi-factor flow. For exact details on configuration see configuration reference.

Required Authenticator For Registration

In a similar fashion to Multi-factor for Authentication, it is possible to configure the registration part of an authenticator to be protected with an authenticated session. This means for instance that the system can be configured to require the user to be logged in with Facebook before being able to create a new account. Or that the user is logged in with a legacy account before registering a new global account.

Tip

A common problem organizations have is onboarding users from an old system onto a new platform. By configuring the registration of the new user account to require the user to be authenticated with the legacy account, and at the same time configuring account-linking on the new account with the legacy account, users will be forced into the flow which results in them to both being onboarded and linked.

Request Validation

While each authenticator has its own responsibility of validating each inbound request, it is possible to add custom request validation. This way, it is possible to enforce your own required fields, as well as assert that the fields conform to your own custom requirements.

You can configure request validation as part of an authenticator. To configure when a request validator must be fired, you must set the request’s Subpath, endpoint and HTTP method. The subpath of an authenticator can be found in its documentation. For example see the subpath documentation for HTML Forms Authenticator. Now when you want to fire a custom request validation procedure when a new user submits a form to register a new account with the HTML Forms authenticator, set the subpath to index, the endpoint to register and the HTTP method to post.

More information on how to write a request validation procedure is documented in the Developer’s Scripting Guide’s section Validation procedures.

Geolocation Authenticator Settings

The geolocation authenticator settings is an optional set of settings that allow or deny an authenticator to be used, depending on the location of the request. These settings are optional, and if not set, they are ignored and an authenticator can be used no matter where the request originates from. For example, imagine the following scenario: A user that is located in a country that has a country specific authenticator as the common way to authenticate in most of commercial sites. An admin may want to configure this authenticator to be used only in this country. If a user is travelling or relocating abroad, they might not be allowed to use this specific authenticator anymore. A very common example in Sweden is the BankID authenticator. It is a country specific authenticator, which someone might want to prohibit its usage outside of Sweden. To that direction, an admin can configure the authenticator to be blocked from being used outside of Sweden

For exact details on configuration see Geolocation Authenticator Settings.

Multi-factor configuration for Authentication

Each authenticator can be run on it’s own, or be configured to be part of a multi-factor authentication flow. When configured for multi-factor the authenticator will not run until all previous authenticators have executed.

The flow is setup in such manner that the execution always starts at the highest factor (the last in the chain), which will assert that the previous factor is satisfied. If it cannot find an SSO session for the previous factor, the Authentication Service will redirect the user to the previous factor. Once all previous factors are satisfied, the user is redirected back to the last factor for authentication.

The flow in a two factor authentication

Fig. 46 The flow in a two factor authentication

See multi-factor authentication for more details.

Back-channel Authenticators

These are authenticators used for Back-channel Authentication. They support initiation of authentication for the client asynchronously and enable polling for status of authentication by end user.

Email, SMS and BankID authenticators support back-channel authentication out of box. Any other authenticator can be created or extended to support back-channel authentication by implementing a plugin of type BackchannelAuthenticatorPluginDescriptor

Configuration

The back-channel authenticators, as all other plugins, specify their configuration by returning an interface that extends Configuration from its plugin descriptor’s getConfigurationType() method.

For more details, see the Plugins Guide.

Authentication Actions

Not all authentication actions available to front-channel authenticators are available to back-channel authenticators. Some of the actions, like attribute-prompt, cannot work without a user interface and hence cannot work on back-channel directly. Currently, the following actions are supported on back-channel authenticators:

The below authentication actions, which are based on user’s geographic location in front-channel context, work with back-channel authenticators as well. However, when used with back-channel authenticators, these will be based on client’s location as the back-channel authentication flow is initiated by clients. In deployments where client’s location is coupled with user’s location, these actions could help to identify change of locations.