Skip to main content

Authentication chains: Components

Authentication chain scenario components

Bravura Security Fabric has several authentication chains and selector modules available for installation through the Component Framework. The following scenario components are installed with the Default repository:

hid_authchain_2factor:

  • Selector for basic second-factor authentication.

  • Allows for users to store company and personal email addresses and cell phone numbers (text and mobile app), to be used along with password or security questions.

  • If the browser is recognized, it will be used as the second factor.

  • Imports the scenarios for the authentication methods.

  • Dependencies:

    • Functional.hid_authchain_2factor

    • Scenario.hid_authchain_select

    • Scenario.hid_authchain_pii

    • Scenario.hid_authchain_personal_emailpin

    • Scenario.hid_authchain_smspin_email

    • Functional.hid_authchain_select

hid_authchain_emailpin:

  • Authenticate using an email PIN by sending a PIN to company email.

  • Dependencies:

    • Functional.hid_authchain_emailpin

    • Functional.hid_global_configuration (adds the EMAIL-ATTRIBUTE, MAXLIFE, LENGTH, and TRIES settings to the AUTHCHAIN_EMAILPIN_CONFIG namespace in the associated table)

hid_authchain_forgot_password:

  • Provides a 'forgot my password' authchain by sending a ”link to password change” email.

  • Dependencies:

    • Scenario.hid_authchain_select

    • Functional.hid_authchain_forgot_password

    • Functional.hid_authchain_select

    • Functional.hid_global_configuration (adds the MAXLIFE and EMAIL_ATTR settings to the FORGOT_PASSWORD namespace in the associated table)

hid_authchain_localauth:

Note

This component is meant for demonstration or development environments only; not for testing or production systems.

  • Allow users to skip authentication when instance is accessed from localhost; if the connection is from ::1 or 127.0.0.1, allow access without authentication.

  • Dependencies:

    • Functional.hid_authchain_localauth

    • Scenario.hid_authchain_select

    • Functional.hid_authchain_select

hid_authchain_oneauth:

  • Provides a Bravura OneAuth authentication scenario.

  • Dependencies:

    • Data.hid_target_hypr

    • Data.hid_authchain_oneauth

    • Functional.hid_authchain_select

hid_authchain_oneauth_2factor:

  • Provides a Bravura OneAuth two-factor authentication scenario.

  • Dependencies:

    • Scenario.hid_authchain_oneauth

    • Scenario.hid_authchain_select

    • Data.hid_authchain_oneauth_2factor

    • Functional.hid_authchain_fingerprint

    • Functional.hid_authchain_select

hid_authchain_personal_emailpin:

  • Send PIN to personal email previously registered by the user.

  • Dependencies:

    • Data.hid_attribute_personal_email

    • Functional.hid_authchain_personal_emailpin

    • Functional.hid_global_configuration (adds the EMAIL-ATTRIBUTE, MAXLIFE, and LENGTH settings to the AUTHCHAIN_PERSONAL_EMAILPIN_CONFIG namespace in the associated table)

hid_authchain_pii:

  • Use Personally Identifiable Information (PII) to authenticate a user.

  • These are Q&A from HR, almost always used only for a first login scenario (as using PII is susceptible to social engineering, and can be legally dangerous with users eligible for GPDR).

  • Dependencies:

    • Data.hid_attribute_dob

    • Data.hid_attribute_dl

    • Data.hid_attribute_mmn

    • Data.hid_attribute_ssn

    • Functional.hid_authchain_pii

    • Functional.hid_user_interface

    • Functional.hid_global_configuration (adds the DOB, DL, MMN, SSN, and PII_REQUIRED settings to the AUTHCHAIN_PII_ATTRS and AUTHCHAIN_PII_CONFIG namespaces, respectively, in the associated table)

hid_authchain_recaptcha:

  • Adds an authentication chain and required code for ReCAPTCHA2 (usually for external access) to frustrate robots attempting invalid access attempts.

  • Dependencies:

    • Functional.hid_authchain_recaptcha

    • Functional.hid_global_configuration

    • Functional.hid_dbe_update_trigger

hid_authchain_recaptcha_invisible:

  • Adds required configuration for invisible ReCAPTCHA2 (usually for external access) to frustrate robots attempting invalid access attempts.

    This ReCAPTCHA implementation uses the User Identification chain. Improper configuration may prevent any user from logging in.

  • Dependencies:

    • Functional.hid_authchain_recaptcha_invisible

    • Functional.hid_global_configuration

    • Functional.hid_dbe_update_trigger

hid_authchain_recaptcha_v3:

  • Adds an authentication chain and required code for ReCAPTCHA3.

  • Dependencies:

    • Functional.hid_authchain_recaptcha_v3

    • Functional.hid_global_configuration

    • Functional.hid_dbe_update_trigger

hid_authchain_saml_sp:

  • Authentication scenario to allow Bravura Security Fabric to be used as an SAML service provider.

  • Dependencies:

    • Scenario.hid_authchain_select

    • Data.hid_authchain_saml_sp

    • Data.hid_userclass_saml_users

    • Functional.hid_authchain_select

hid_authchain_select:

  • Default authentication scenario for console-only and regular users.

  • Dependencies:

    • Functional.hid_authchain_select

hid_authchain_smspin_celltrust:

  • SMS PIN authentication scenario that uses Celltrust as a SMS service provider; uses CellTrust account to send SMS texts to registered cell phones.

  • Dependencies:

    • Data.hid_attribute_mobile

    • Functional.hid_authchain_smspin

    • Functional.hid_sms_celltrust

    • Functional.hid_global_configuration

  • Conflicts:

    • Scenario.hid_authchain_smspin_email

    • Scenario.hid_authchain_smspin_twilio

hid_authchain_smspin_email:

  • Use mobile providers’ email-to-text gateways to send SMS texts to registered cell phones.

  • Major US and Canadian providers are automatically onboarded; other providers must be added before users register the phone to be available.

  • Dependencies:

    • Data.hid_attribute_mobile

    • Data.hid_attribute_mobile_provider

    • Functional.hid_authchain_smspin

    • Functional.hid_sms_email

    • Functional.hid_global_configuration

  • Conflicts:

    • Scenario.hid_authchain_smspin_twilio

    • Scenario.hid_authchain_smspin_celltrust

hid_authchain_smspin_twilio:

  • Use Twilio account to send SMS texts to registered cell phones.

  • Dependencies:

    • Data.hid_attribute_mobile

    • Functional.hid_authchain_smspin

    • Functional.hid_sms_twilio

    • Functional.hid_global_configuration

  • Conflicts:

    • Scenario.hid_authchain_smspin_email

    • Scenario.hid_authchain_smspin_celltrust

hid_saml_idp:

  • This component enables Bravura Security Fabric to act as a federated Identity Provider (IdP) using the Security Assertions Markup Language (SAML v2.0) protocol.

  • This allows other applications, either on-premise or hosted in a Software-as-a-Service (SaaS) manner, to hand off their user login processes to Bravura Security Fabric .

  • Dependencies:

    • Scenario.hid_authchain_select

    • Functional.hid_configuration

    • Functional.hid_extdb

    • Functional.hid_policy_saml_sso

    • Data.hid_authchain_saml

    • Functional.hid_saml_authentication

    • Functional.hid_authchain_reguser

    • Functional.hid_authchain_select

hid_authchain_select

The hid_authchain_select component provides a policy framework for controlling the authentication process by allowing product administrators to define rules that determine which authentication chains are available to users attempting to login.

This component is not meant to be installed on its own since it does not provide any initial configuration as part of its installation. Instead, it should always be installed as a dependency of another authentication chain scenario component, which would then have to provide some initial configuration for the policy engine to ensure that the authentication process remains unaffected. The hid_authchain_select component is installed when you install any of the shipped authentication chain scenario components.

Two authentication chains are configured by default when you install Bravura Security Fabric :

  • DEFAULT_LOGIN called when a user attempts to log into Bravura Security Fabric .

  • HELPDESK_LOGIN called when a helpdesk user attempts to authenticate a user to assist them.

Installing this component overrides the built-in authentication chain selection process by configuring its script extension to become part of the DEFAULT_LOGIN chain via a chain selector module that:

  1. Sets SELECT_AUTHCHAIN_MODULE_OBJPLUGINPOINT to DEFAULT_LOGIN .

  2. Configures DEFAULT_LOGIN to use authselect.py.

    When components are installed to configure authentication chains, any manually created authentication chain settings will not be used. The hid_authchain_select component will override any settings done via the GUI. A workaround is to convert manual settings to a component, so that hid_authchain_select can know about them.

Once installed, the authentication process becomes subject to rules defined in an External data store (ExtDB) configuration table called hid_authchain_select. Other authentication chain components can leverage this table by injecting their own rules here when installed.

If using the 2factor scenario component, a browser fingerprint option can be added after the chain decided by the selector runs, to take/update the fingerprint; that fingerprint if it exists, can be used as the "second factor”. Apart from that, once the selected chain runs successfully, the user is granted access.

Deployment

This component should be used for all decision points in your authentication process. Therefore:

  1. Plan the entire tree, and flag the decision points.

  2. For each decision point, determine the rules.

  3. Run authcfg -export to back up current configuration.

  4. Back up <instance>\db\ extdb.db using the appropriate database backup software.

  5. Implement the chains required.

  6. For each module that is a decision point, set Run this plugin to automatically select sub-chain to hid_authchain_select.py.

  7. Run authcfg -export again and determine CfgIds for all selection plugin modules.

  8. Add the rules into the hid_authchain_select external database table, each labeled with the relevant CfgId. See Obtaining the GUID .

  9. Backup and test.

The hid_authchain_select policy configuration ExtDB table controls the authentication sequence for any available authentication chain.

Whenever the authentication chain selector plugin script is executed, rules in this table are processed sequentially, ordered by their stage number first, and within each stage, in an incremental order dictated by their rule number.

For each plugin run, only rules pertaining to the calling authentication chain module are processed. The calling module is identified by its GUID (the CfgId column in this table).

The hid_authchain_select table contains all the rules that determine what chains are to be allowed for a particular login attempt, when the authentication selection module uses hid_authchain_select.py. Like all component framework policy tables, it contains the following basic fields:

Stage Number

(int) The policy engine will run checks in stages. Each stage completes before rules in the next stage are tested; only after all stages are completed, or a rule finalizes processing, are the final results passed.

Rule Number

(int) Within each stage, the engine processes the rules in number order. Note that this is not necessarily table entry order.

SkipRemaining

This field can have three values:

  • Empty: Proceed with all remaining rules

  • Stage: Skip rules from the same stage and proceed with rules in different stages

  • All: Skip all remaining rules

Comment

(string) Used to explain what the rule means in English. Like all comments, very useful if kept correct, and actively dangerous if not.

The hid_authchain_select table also contains the following fields:

CfgId

The GUID or blank and determines which module the rule apply to. Each module is assigned a GUID on creation. To determine a module’s GUID see Obtaining the GUID .

If the rule’s CfgId is blank, it will run on every invocation of the selection plugin. This should only be used when the selector is only invoked in one place.

Note: It is recommended that you do not leave the CfgId blank.

When the selector is used in two places in authentication, knowing which rules should be tested for each invocation is critical, and therefore each rule should have the CfgId of its module. For example; in Bravura Workforce Pattern , DEFAULT_CHAIN is a selector, to determine if two-factor authentication is required, or if this is the first login for a user; then the 2FACTOR chain is a selector, determining what second factor types are possible for this user; and FIRST_LOGIN is also a selector, determining if we can use SMS or PII to authenticate the user for the first time.

MatchType, MatchKey, MatchCondition, MatchValue

Optional . Within a plugin run, each module rule is then further evaluated based on optional values configured for matching parameters in these four fields.

Example; if the rule must match authenticating users based on their membership in a user class:

  • MatchType = userclass

  • MatchKey = MOBILEUSERS (user class ID)

  • MatchCondition = in

  • MatchValue = (empty)

    Example; if the rule is to identify users who have registered for authentication via security questions:

  • MatchType = userstat

  • MatchKey = PSQDONE

  • MatchCondition = equal

  • MatchValue = true

MatchType

This field can have one of the following restricted values:

  • acl: For logic involving plugin.viewer.acl entries (admin table Boolean flags). The MatchCondition field can be set or notset if acl is used.

    Example; Set MatchType=acl, MatchKey=superuser and MatchCondition=set to apply the rule to superusers.

  • cgi: Determines which page the user logs into. For logic involving plugin.cgi.value entries. HTTP HEADER information.

  • parameter: For logic involving plugin.parameters entries. HTTP Post information such as HOSTID, USER_IDENT, LANG, SKIN.

  • sessdata: Does this item exist in the session data for this login/session? Or, does it have this value? For logic involving plugin.sessdata entries, such as NEW_SERVICE_NAME (authentication chain calling this selector), SAML_REQUEST (SAML XML request data).

  • state: For state between authentication chains. Has this state value been created during this login attempt, or is it equal to this value? For more advanced logic which requires the maintenance of a shared state between multiple AuthChainSelect component runs during authentication.

  • userclass: Is the user in this userclass?

  • userstat: Does the user have this key (or this key with this value) in the USERSTAT table? The most common keys in USERSTAT are PSQDONE, LAST_LOGIN and LAST_LANG;

    For example; if PSQDONE is false or is not set, then it is a ”first login” scenario so the user will be required to create a valid question set.

MatchCondition

This field can have one of the following restricted values:

  • set/notset: Whether the MatchKey value exists. Applies to the acl, cgi, parameter, sessdata and userstat types.

  • equal/notequal: Whether MatchKey is equal/not equal to MatchValue. Applies to the cgi, parameter, sessdata and userstat types.

  • in/notin: Whether the user is or is not a member of the MatchKey user class. Applies to the userclass type.

MatchKey

The key to match based on the MatchType flag.

MatchValue

(string) The value to match based on the values based on the values of MatchType and MatchKey.

Examples:

  • MatchType = userstat

  • MatchKey = PSQDONE

  • MatchCondition = equal

  • MatchValue = false

  • MatchType = userclass

  • MatchKey = MOBILE_APP_USERS

  • MatchCondition = in

  • MatchValue = (empty)

Action

(selection) If a match is found, the ”Action” column determines what the policy engine should do with the list of chains already matched as part of the current run. The following options are available:

  • flush - Remove any chains that were added by a previous policy rule and add the chain specified by the Chain_ID field (if any).

  • append- Add the chain specified by the Chain_ID field to the list of existing chains.

ChainID

Optional . If this rule matches, this field determines which chain is allowed.

The value of this column is an authentication chain_ ID; it is not a GUID of an individual authentication chain module.

Built-in chains such as the password or security questions authentication must be prefixed accordingly since this is how the authentication selector plugin expects them to be listed in its output; for example, $INTERNAL_password.pss, $INTERNAL_response.pss. Other custom authentication chains must be listed by their ID; for example, SUCCESS, SMSPIN, FIRST_LOGIN.

It is important to note here that any authentication chain added to this field must first be made available to the calling chain via Manage the system > Policies > Authentication chains otherwise the plugin run will fail.

The Chain_ID field can be empty, thus allowing a rule to ’throw away’ any existing chains collected in the current run up until then, if the authentication logic requires it.

ErrorMsg

The custom error message to use if authentication fails to find any valid chains.

ComponentOwnerFQN

(string, not modifiable): The component that registered the rule. For manually created rules, this is blank.

There are several built-in USERSTAT tags.

USERSTAT built-in tags

Tag

Description

Example

LASTPSL

The last time the user used the Attach other accounts module. The time used is the authentication time of the session.

2021-10-28 14:40:16 (UTC-06:00)

LASTSKIN

The last skin the user used.

default

LASTLANG

The last language the user used.

en-us

LASTPWCHGMODULE

The last module used to reset the user's password.

pss,ida,idpm

PSLDONE

The user has satisfied mandatory account requirements. This is defined by the per target system setting Users must have accounts, and the global system variable PSL_MIN_ACCOUNTS.

The allowed value true is set by psdonechk or when the user or a help desk user uses the Attach other accounts module.

true

PSQDONE

The user has satisfied the security question requirement. The allowed value true is set by psdonechk or when the user or a help desk user uses the Update security questions module.

true

Obtaining the GUID

A complete list of authentication chain modules currently configured for an instance can be exported to a plain-text file with the authcfg command line utility:

authcfg -export authchains.txt

The modguid parameter in the exported file corresponds to the value of the CfgId column in the configuration table.

Example: Modify hid_authchain_select table

Click below for a demonstration of removing some rules from the hid_authchain_select table when the Update security questions (PSQ) module has been disabled. In this example, security question authentication is not being used; therefore, these rules may interfere with desired authentication behavior.

Individual rule examples

The following are various examples of rules to show how the fields in the table work together.

Table 1. Rule example

Rule

Skip Remaining

Match Type

Match Key

Match Cond

Match Value

Action

ChainID

1

(None)

cgi

REMOTE_ADDR

equal

::1

append

LOCALAUTH

2

(None)

cgi

REMOTE_ADDR

equal

127.0.0.1

append

LOCALAUTH

3

(None)

parameter

token

notset

append

FORGOT_PASSWORD



The rules do the following:

Rule 1

Allows users to skip authentication when instance is accessed from localhost

Rule 2

Allows users to skip authentication when instance is accessed from localhost

Rule 3

Provides a ’forgot my password’ authchain

Example of a complete set of rules

As an example, here is a complete set of rules for the 2FACTOR authchain:

Table 2. Rule example

Rule

Skip Remaining

Match Type

Match Key

Match Cond

Match Value

Action

ChainID

1

Stage

state

FINGERPRINT

in

all

append

SUCCESS

2

(None)

userclass

EMAILUSERS

in

append

EMAILPIN

3

(None)

userclass

PERSONAL_EMAILUSERS

in

append

EMAILPIN

4

(None)

userclass

MOBILEUSERS

in

append

SMSPIN

5

(None)

userclass

_MOBILE_USERS_

in

append

MOBILEAPP



The rules do the following:

  1. If there is a browser fingerprint for this user, accept that as the second factor (SUCCESS is a special chain that always returns True) and stop processing. Otherwise, add any chains that there is verification information for.

  2. If the account is in the EMAILUSERS userclass, allow them to authenticate with a PIN sent to that email.

  3. If the account has a personal email address set, allow authentication with a PIN sent to that email.

  4. If the account has a text number set, allow authentication with PIN texted to that number.

  5. If the user has the Bravura One app installed, allow authentication via QR code scan from the app.

If no 2FACTOR options are available, the user will not be able to log in unless their browser is in the fingerprint database for that user. If multiple options are available, the user will be asked which one to use. If only one option exists, the user will be pushed directly into that one.

In the B2B table, there are 20 rules. However, only these five have the 2FACTOR module GUID set as CfgId, so only they will be tested when trying to find a second factor.

Example of rules that rely on user conditions

Userstat tags can be used to create authchain rules that rely on the user having fulfilled certain conditions. This can be useful for sending users to specific authentication chains when they do not have certain conditions met such as:

  • If user's have not enrolled in security questions

  • if user's have not reset their password

As an example, here are several authentication chain rules that utilize userstat tag condiions:

Table 3. Rule example

Rule

Skip Remaining

Match Type

Match Key

Match Cond

Match Value

Action

ChainID

1

Stage

userstat

PSQDONE

equal

false

flush

FIRST_LOGIN

2

Stage

userstat

PSQDONE

notset

flush

FIRST_LOGIN

3

(None)

userstat

LASTPWCHGMODULE

notcontain

pss

flush

FIRST_LOGIN

4

Stage

userstat

LASTPWCHGMODULE

equal

ida

flush

HELPDESK_FIRST_

LOGIN



Potential MatchValues for LASTPWCHGMODULE include:

  • pss - password was changed by using the self-service product UI.

  • ida - password was changed using the help desk module.

  • idpm - password was changed using transparent synchronization.

The rules do the following:

  1. If the user has not completed security question enrollment, send the user to the first time login chain. Do not evaluate more rules in this stage if these conditions are met.

  2. If the user has not completed security question enrollment, send the user to the first time login chain. Do not evaluate more rules in this stage if these conditions are met.

    Rules 1 and 2 mean effectively the same thing, but differ in that rule 1 is checking if the PSQDONE tag is set to "false" and rule 2 is checking if it is set at all. Both values mean that the user has not completed their security questions so both rules need to exist to cover users that have either value.

  3. If the user has not reset their password using the product UI, send the user to the first time login chain. Continue to evaluate more rules in this stage even if these conditions are met.

  4. If the user has had their password reset by the help desk, send the user to a help desk first time login chain. Do not evaluate more rules in this stage if these conditions are met.

See USERSTAT built-in tags from the deployment topic to see more MatchKey options.

Click below to view a demonstration of adding a new rule to the hid_authchain_select table to identify new users that are logging in for the first time by adding criteria that checks if the LASTPWCHGMODULE has been set to pss for the user and, if it has not, sending the user to the FIRST_LOGIN authentication chain so they can authenticate for the first time using something other than a password; for example, personal identifiable information (PII).

In this section: