Authenticator Base Configuration#

The Authenticators Home Page provides an overview of the main authenticator behaviors. All authenticators have a number of base configuration settings. In the Admin UI you can view these settings by navigating to Profiles → Authentication Service → Authenticators, editing the properties of an authenticator and selecting the More page.

These settings control aspects like 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 (the reference to the authenticator)
• Template Area for the authenticator
• Account Domain
• Required Authenticator For Registration
• Request Validation
• Geolocation Authenticator Settings

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

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 applications 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 different 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.

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.

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 .

Authenticator Plugin Interface#

Authenticators are implemented with a plugin interface from the Curity Identity Server’s Java SDK. The ability to write plugins means you are never blocked when you face deeper custom requirements.

If you develop a custom authenticator plugin it also has access to the base configuration settings. To understand how a plugin can use configuration settings it can be useful to browse some example plugin implementations. The Curity Website contains a number of example authenticator plugins for particular use cases. You can read the learning resources to understand the development approach:

• Getting Started Plugin Resources
• Example Authenticators

The example plugins link to GitHub repositories whose code you can study. Browse plugin code to understand how frontend HTML is generated from velocity templates that can use template-related configuration settings.

Authenticator Swim Lanes#

Under the General tab, all authenticators have locations or swim lanes, where they can be extended with prerequisite authenticators or login and single sign-on (SSO) authentication actions. This capability enables you to compose a number of additional common behaviors.

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.

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.

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.

Front-channel link#

Back-channel authenticators can optionally link to a (front-channel) authenticator in the same plugin group by specifying it in getFrontchannelPluginDescriptorReference() method in its plugin descriptor.

This is useful because it enables the back-channel plugin to share both configuration and logic with an existing front-channel plugin.

By linking to a front-channel authenticator, the back-channel authenticator gains access to its configuration and managed objects.

Prerequisites of the front-channel authenticator, like previous-authenticator or required-authenticator-for-registration, don’t apply on the linking back-channel authenticator flow because these are only applicable when the front-channel authentication flow is used (which can happen out-of-band in the case of back-channel initiated authentication).

In order to share information via sessions, the authenticator plugins may use the SessionManager service. For this to work, both of the plugin’s manifests should include the Shared-Session-Sandbox: true entry, which enables plugins in the same group to share session data. Without this, all session data remains sandboxed to each plugin and different plugins cannot see any data from each other, even when linked.

The linked front-channel configuration, Plugin Managed Object , along with the back-channel’s own equivalents, may be injected via the constructor in implementations of BackchannelAuthenticationHandler.

For an example implementation, please refer to the Freja authenticator.

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:

• Data Source Transformer Action
• Script Transformer Action
• Sequence Action
• Switch Action
• Time-based Deny Action
• Date/Time Deny Action
• Remove Attribute Transformer Action
• Regulat Expression Transformer Action
• Auto Create Account
• Lookup Links Action
• Resolve Account Link

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.

• Geolocation New Country Action
• Geolocation Changed Country Action
• Geolocation Allow or Deny Country Action
• Geolocation Impossible Journey Action