DynamicAuthenticator
Note
A highly configurable authenticator that relies on a pipe being run successfully. Can request any number of inputs, with customizable names, types and options. Can also be used for certificate based authentication by rerouting through a different host or url suffix.
Properties
| Name | Description | Default value | Mandatory |
|---|---|---|---|
| pipeID | Id of the pipe used to verify the username and password | N/A | Yes |
| inputElements | Which input parameters are required to run the pipe | No | |
| actionButtons | List of which action buttons should exist in the input form | No | |
| shouldReroute | Whether or not to reroute the request using rerouteUrlBase or rerouteUrlSuffix. Used for certificate based authentication. | false | No |
| rerouteUrlBase | Base URL for reroute. Example: https://mtls.mydomain.com Important!: Make sure your cookie is set to the right domain for this. | No | |
| rerouteUrlSuffix | URL Suffix for reroute. Will remove the '/login' part of the url path and replace it with '/urls/mysuffix'. Normally not needed if rerouteUrlBase is used. | No | |
| userIdentifierAttribute | Which attribute on the resulting item should be used as the user identifier. | userName | Yes |
| localizationKey | Which base localization object in the frontend translation file should be used to find the texts to be displayed | N/A | No |
| localizationArguments | Which localization arguments should be sent alongside the localizationKey, in case translatable strings contain parameters. Expandable. | {} | No |
| informationDisplay | Whether or not the authenticator should present an information display. Used for optionally displaying information to the user when no inputs are present. | false | No |
| useRecaptcha | Whether or not reCAPTCHA v3 should be used. Read more about reCAPTCHA v3 here. | false | No |
| recaptchaSiteKey | Your reCAPTCHA site key. | N/A | Yes, if useRecaptcha is true |
| recaptchaSecret | Your reCAPTCHA secret. Only used when auto verification is enabled. | N/A | Yes, if useRecaptcha and autoVerifyRecaptcha is true |
| recaptchaSuccessThreshold | Your reCAPTCHA v3 success threshold when using auto verification. Values between 0 and 1 are accepted. A value of 0.5 or above is recommended, and higher threshold means less likely that a bot would get through. | 0.5 | No |
| autoVerifyRecaptcha | Whether the recaptcha should be automatically verified with the given success threshold. If set to false, you need to manually verify the reCAPTCHA token with a valve. | true | No |
| recaptchaScoreAttribute | The request attribute that the recaptcha score should be added to, if auto verification is enabled. If this has a value, it will be saved in the request as a parameter so you may use it further in the pipe flow. Note that it has already been verified against the score threshold at this point. | N/A | No |
The inputElements property
You can configure inputElements to contain any number of inputs, with different types, localization keys, and selectable options. Each input element has the following possible configuration properties:
{
"name": "The name of the input attribute. If name is 'xyz' then the attribute's value will be {{request.xyz}} in the pipe.",
"isUserIdentifier": "If this attribute should be used as user identifier when authenticator has been executed successfully. If set, it will override the 'userIdentifierAttribute' configuration parameter.",
"type": "The type of input. Possible values are 'text', 'email', 'password', 'date', 'select' and 'radio'. If left blank, will try to deduce type from name (name: password will result in type: password, same with email), otherwise defaults to 'text'.",
"localizationKey": "Localization key for the input element. Will look for a translation in the frontend translation file. If both this and 'label' are blank, this field will default to 'name'",
"regex": "Regular expression for input validation (frontend validation only, for backend validation use valves)",
"optional": "true or false, boolean value if the input is optional or not. Default is false.",
"label": "Hard-coded user-facing label describing the input element. Redundant if localizationKey is set.",
"readonly": "Whether an input should be a read-only attribute or not, default 'false'. Values 'true' or 'false'. If true, should be used together with 'value', to provide visual feedback.",
"value": "The start value of an input. Optional and expandable.",
"localizationArguments": {
"exampleArgument": "Example value to send if localization object contains parameters. Expandable.",
"otherExampleArgument": "{{item.email}}"
},
"columnNames": [{"label": "Label for column 1 when using type: radio. Redundant if localizationKey is set in this object.", "localizationKey": "localizationKey for column 1"}],
"options": [{"value": "Value for option 1 when using type: select or type: radio", "columns": [{"label": "Label for option 1 column 1 when using input type select or radio, redundant if localizationKey is set."}]}],
"itemOptionMapping": {
"valueProperty": "Which property in the serialized items should be used to determine the input's value",
"columns": [{"labelProperty": "Which property in the serialized items should be used to determine the label of the corresponding option in the first column. Redundant if localizationKeyProperty is set", "localizationKeyProperty": "Which property in the serialized items should be used to determine the localizationKey of the corresponding option in the first column."}]
}
}
This provides high flexibility in what type of inputs to present to the user, while having a simple configuration like username & password requires very little configuration as can be seen in the example below.
The actionButtons property
You can configure actionButtons to contain buttons which can be used to control pre-authenticator pipe execution for example. These extra action buttons will not submit the form. An action button can be configured in the following way:
{
"action": "The name of the action. For example: 'resendOTP'.",
"localizationKey": "Localization key for the button text. Will look for a translation in the frontend translation file.",
"label": "Hard-coded user-facing button text. Redundant if localizationKey is set.",
"localizationArguments": {
"exampleArgument": "Example value to send if localization object contains parameters. Expandable.",
"otherExampleArgument": "{{item.email}}"
},
"type": "Button type. Possible values are 'outlined' and 'contained'. Default is 'outlined'",
"color": "Button color. Possible values are 'primary', 'secondary' and 'accent'. Default is 'primary'."
}
Deprecated properties
| Name | Description |
|---|---|
| textEntryParameters | Old way of configuring inputElements. Syntax is same as above. Will still work but may be removed in future releases. |
Information display
If you merely want to display some information to the user without prompting any input, use the configuration property informationDisplay and set it to "true".
This will show the text configured within the object of your configured localizationKey, and the user may approve or decline depending on your configuration.
The result of whether or not the information was approved is sent in the request parameter informationApproved. This may be used to remind users to plug in their smartcards for certificate based authentication, or simply as an informational step in a sequence authentication.
Information display configuration example
The configurable texts on the information display page are body, instruction, ok and cancel. instruction and cancel are optional
and will not show if not configured. Whether the cancel or ok button was used is displayed in the request parameter informationApproved, but will still send
the request to the authenticator. The example below are the information displays pre configured in the default translations.
The SignMessage information display is automatically used if a SAML message contains a signMessage and the authenticator is not
sign-enabled (uses an authenticator capable of showing the signMessage natively, like BankID or OneTouch).
The mtls example information display is not enabled by default, but if you set up an mTLS according to the guide and set
informationDisplay to true, it will appear before performing the authentication.
"signMessage": {
"page": {
"htmlTitle": "Sign",
"instruction": "Your signature has been requested on the text below:",
"body": "{{signMessage}}",
"ok": "Approve",
"cancel": "Decline"
}
},
"mtls": {
"selectorItem": {
"icon": "certificate",
"label": "Log in via certificate"
},
"page": {
"htmlTitle": "Certificate authentication",
"body": "Authenticating via certificate. Make sure your smartcard is inserted before proceeding.",
"ok": "OK"
}
}
Example Configuration
Dynamic inputs
The first example configuration is for a Username & Password authenticator. It has two input elements. The pipe then typically consists of a combination of LockoutCheckValve, LdapSearchValve and LdapBindValve.
{
"id" : "2487e92b-9a76-478a-8337-ae93d5af4588",
"alias" : "uidpwd",
"name" : "DynamicAuthenticator",
"displayName" : "Username & Password",
"configuration" : {
"pipeID" : "defd8cce-d3db-4ad4-a9aa-041998a549dd",
"inputElements" : [ {
"name" : "username"
}, {
"name" : "password"
} ],
"userIdentifierAttribute": "uid"
}
}
The second example provides dynamic selection of roles in the process of a sequence authentication that had returned several possible user roles in a previous step.
{
"id" : "2487e92b-9a76-478a-8337-ae93d5af4588",
"alias" : "userroleselect",
"name" : "DynamicAuthenticator",
"displayName" : "User role select",
"configuration" : {
"pipeID" : "defd8cce-d3db-4ad4-a9aa-041998a549dd",
"localizationKey": "roleselection",
"inputElements" : [ {
"name" : "uid",
"type" : "radio",
"localizationKey" : "roleselection_input_title",
"columnNames" : [ { "localizationKey" : "roleselection_given_name" }, { "localizationKey" : "roleselection_surname" }],
"itemOptionMapping" : {
"valueProperty" : "uid",
"columns" : [ {"labelProperty" : "givenName"}, { "labelProperty" : "sn" } ]
}
} ],
"userIdentifierAttribute": "uid"
}
}
In this example, itemOptionMapping is used to provide a dynamic selection of roles for the user. The input type is radio, where a data grid is displayed and each row contains a radio-button that selects the option.
Each option is mapped from a serialized item, meaning you need to be inside a SequenceAuthenticator to utilize this configuration parameter, as the options are generated from the options property of the current item.
To achieve this, use ItemSerializerValve in the previous step of the sequenceAuthentication. You want to serialize items into the current item property options. That can be done with the following configuration:
{
"id" : "d5d9b521-d9ae-40b2-9d85-31f4a77c313b",
"name" : "ItemSerializerValve",
"enabled" : "true",
"config" : {
"dest_scope" : "item",
"dest_name" : "options",
"item_include_expr" : "item.containsProperty('uid')",
"keep_items" : "false",
"encode" : "false"
},
"pipe_ref" : "2ad94b09-c803-4dc4-b184-f06b006ddfd3",
"created" : "2024-06-17T07:22:50.200Z",
"modified" : "2024-06-17T07:34:34.607Z"
}
If items are serialized in this fashion, each item will be an option for the radio data grid. The value of each item is defined in the configuration as a property. Here it is the item's uid. Each column in the row will have a label or localizationKey taken from the item via the property defined in the configuration.
When the selection is made, the pipe is run like with any other input, but to affirm your selection, you should first use ItemDeserializerValve and then ItemRemoveValve configured so that the only item that is kept is the one where item.myValueProperty == request.inputName. In this example that would be item.uid == request.uid.
This was just a few examples of how you might configure DynamicAuthenticator to provide different types of inputs. You can also use it to perform any type of input based authentication or registration scenario.
Mutual TLS example
The last configuration example is a certificate based authentication. It will first redirect to the "rerouteUrlBase" (with the same path as the current request), which is a configured proxy server / load balancer that will perform mutual TLS and request a client certificate and add it to the request, and then send the request forward to the same path as before which should be configured to lead to this authenticator again. In this example, the rerouteUrlBase is set to use a subdomain, which means that the authentication cookie needs to be set to a specific domain. Read more on how to do that here.
A pipe here would normally consist of CertificateExtractorValve, LdapSearchValve, ItemMergeValve, CertificateValidatorValve, and FlowFailValve.
{
"id" : "2487e92b-9112-478a-5500-ae93d5af4588",
"alias" : "certificate",
"name" : "DynamicAuthenticator",
"configuration" : {
"pipeID" : "certificatepipe",
"shouldReroute" : "true",
"rerouteUrlBase" : "https://mtls.mydomain.com",
"userIdentifierAttribute" : "uid"
}
}