Auto Link Accounts¶

Auto Link Accounts is an action that creates a link between the incoming subject from the authenticator, and another subject found in the authenticated sessions (i.e., SSO sessions).

Note

For a more detailed guide on how to work with account linking see Account Linking.

Overview¶

Auto link account silently creates a link between two subjects – the foreign account and the local account. The local account is the account found in the configured Account Manager. The foreign account is a subject (username) that should be bound to the local account.

It only creates the link if it can find the session of the configured Account Domain in the authenticated sessions. If not, it silently passes without linking.

Configuration¶

Two things are needed for auto-linking accounts:

An account domain configured on the foreign authenticator that should be linked when seen
The auto link accounts action on the other authenticator that should perform the link

The following configuration is needed for linking to work.

Configuration	Mandatory	Description
`linking-account-manager`	yes	Where the account should be linked, also where the `local` account is present
`linking-account-domain`	yes	What `account-domain` to look for when linking
`use-linked-account-as-main-account`	no	(Default false) If true, then the account manager contains the `foreign` account, so linking is reversed
`overwrite-existing-link`	no	(Default false) if a link exist, overwrite it.
`advanced/account-id-in-attribute`	no	Use an arbitrary attribute as the account id. This can have very negative implications on your setup, so use with caution.
`advanced/account-id-in-attribute-source`	no	Source location for the arbitrary attribute to use as the account id.

If use-linked-account-as-main-account is set to true, then the linking-account-domain is treated as the local account and is expected to be found in the accounts that the linking-account-manager holds, and the current authenticator that the action is configured on is the foreign account. This is also referred to as reverse linking.

Important

When using use-linked-account-as-main-account=true, the current authenticator’s account-domain will be used in the database as the linking domain.

../../_images/auto-link-account-config.png

Fig. 92 Auto Link Account Configuration Dialog

Advanced¶

Account Id in Attribute¶

In some setups, where it is impossible to use the auto-create-account action to link two foreign accounts, an arbitrary attribute can be selected to act as a the account id stored in the link. If use-linked-account-as-main-account is enabled, then this attribute is picked from the Authenticated Sessions, otherwise it is taken from the incoming attributes from the authenticator this action runs on.

The account-id-in-attribute-source setting defines the specific source location, which can be subject-attributes or context-attributes, when using Authenticated Sessions; or subject-attributes, context-attributes, or action-attributes, when using the incoming attributes from the authenticator this action runs on.

Warning

A run time error will be returned on every request using this action if account-id-in-attribute-source is configured to be action-attributes and the configuration is using the Authenticated Sessions as the source for the account id information.

No check is made to verify that the account corresponding to the given ID exists. Doing this might cause several problems as there is no guarantee that the value of this attribute is globally unique and immutable. It is strongly suggested to use a auto-create-account action before this one, instead, to avoid any future issues (see Linking two foreign accounts using auto create account).

Warning

It is strongly recommended to NOT use an attribute that might change such as subject (username) or email.

User Confirmation¶

By default this action will create the link without any user interaction. However, it is possible to ask the user for confirmation before creating the link. This is done via a confirmation screen where the user can allow or deny the link creation.

To enable the user confirmation screen, the user-confirmation setting needs to be added to the configuration. This setting has inner settings that allow the control of the information displayed to the user, namely:

Use the value of an alternative attribute for the displayed local account identifier. To be used when the `subject attribute value is not meaningful for the user.
Use the value of an alternative attribute for the displayed foreign account identifier. To be used when the `subject attribute value is not meaningful for the user.
Change the name of the configured account domain to something that is more meaningful to the user.

Configuration	Mandatory	Description
`user-confirmation`	no	Add if account linking should be subject to user confirmation. By default the account linking is done automatically without any user confirmation.
`user-confirmation/attribute-for-local-identifier`	no	Add if the displayed local account identifier should be obtained from an attribute other than `subject`.
`user-confirmation/attribute-for-local-identifier/location`	no	The location from where to retrieve the attribute used for the displayed local account identifier (`subject-attributes`, `context-attributes`, or `action-attributes`). Default value is `subject-attributes`.
`user-confirmation/attribute-for-local-identifier/name`	yes	The name of the attribute used for the displayed local account identifier.
`user-confirmation/attribute-for-foreign-identifier`	no	Add if the displayed foreign account identifier should be obtained from an attribute other than `subject`.
`user-confirmation/attribute-for-foreign-identifier/location`	no	The location from where to retrieve the attribute used for the displayed foreign account identifier (`subject-attributes`, `context-attributes`, or `action-attributes`). Default value is `subject-attributes`.
`user-confirmation/attribute-for-foreign-identifier/name`	yes	The name of the attribute used for the displayed foreign acciunt identifier.
`user-confirmation/linking-account-domain-name`	no	The name for the displayed foreign domain name used.

Important

The settings under user-confirmation only change the information that is presented to the user and not the information that is stored in the link.

Warning

The action-attributes attribute location will be empty when the information is coming from the authenticated session. This means that this location should only be used for the local account identifier if use-linked-account-as-main-account is false or for the foreign account identifier if use-linked-account-as-main-account is true.