With a User Driven Federation (UDF) configuration it is possible to allow users to link their external identities to Ubisecure CustomerID internal identities (accounts). For example, the user could favor to authenticate with a social login or strong authentication application from the bank of their choice with the Ubisecure CustomerID account and effectively login to the web service in question using this external account instead.

Also see User driven federation - SSO page for Ubisecure SSO configurations. All Agent configuration that needs to be completed within SSO, (Agent).

At this time there is no convenient user interface for this configuration, so it has to be performed either by importing an LDIF file using command line utilities or directly modifying Ubisecure Directory manually. This section describes performing the configuration using LDIF file import.

Note following points:

If making the LDIF file for Open LDAP on Linux, make sure that the LDIF content only contains Unix-style line breaks, i.e. only linefeed character but not carriage return character.
All LDIF blocks below can be concatenated to the same file and imported at once.
If using a graphical LDAP client to make the modifications, it is required to have root privileges to Ubisecure Directory.

Register the CIDFederationManagerFactory as an ubiloginService Instance.

Listing 1. LDIF block creating the CustomerID Federation Service

dn: cn=CustomerID Federation,cn=Services,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: add
objectClass: ubiloginService
objectClass: top
cn: CustomerID Federation
ubiloginClassname: com.ubisecure.customerid.federation.CIDFederationManagerFactory
ubiloginServiceInputParameter: subject
ubiloginTitle: CustomerID Federation

Configure a User Mapping Table

Listing 2. LDIF block creating a User Mapping Table for Ubisecure CustomerID

dn: cn=CustomerID User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: add
objectClass: top
objectClass: ubiloginLDAPURLUserMappingTable
cn: CustomerID User Mapping

Listing 3. LDIF block creating a Ubisecure CustomerID specific Ubilogin Service User Mapping Entry

dn: cn=44a5a6c3-706e-419f-adf8-d31f182bcffa,cn=CustomerID User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: add
objectClass: ubiloginServiceUserMappingEntry
objectClass: ubiloginServiceReference
objectClass: top
ubiloginServiceDN: cn=CustomerID Federation,cn=Services,ou=System,cn=Ubilogin,dc=example,dc=com
ubiloginServiceInputParameter: subject ${nameID}
cn: 44a5a6c3-706e-419f-adf8-d31f182bcffa

NOTE: There may be legal requirements to protect certain kind of user information, e.g. Personal Identity Numbers or Social Security Numbers. If this kind of data is used for account linking purposes, then a hash algorithm can be applied to them using Expression Language syntax. e.g.

ubiloginServiceInputParameter: nameID ${nameID.format('finpin').value(sha256.text(method.CUSTID))}

NOTE: Federation Manager Template definition is needed in the eidm.policy if federation is used when logging into CustomerID. However this will be added to the policy automatically so the below LDIF example doesn´t need to be imported manually. It is presented here only for informational and troubleshooting purposes.

If you want to use federation when logging into other services, you need to do a similar modification to the policies those services use.

Listing 4. LDIF block defining a Federation Manager Template

dn: cn=eidm.policy,ou=eIDM Services,cn=Ubilogin,dc=example,dc=com 
changeType: modify
replace: ubiloginConfString
ubiloginConfString: FederationManager.TemplateName federation
-

Modify Authentication Method(s) with Federation Capabilities

Listing 5. Modifying tupas.test.1 method to offer federation

dn: cn=tupas.test.1,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: modify
replace: ubiloginLDAPURLUserMappingTableDN
ubiloginLDAPURLUserMappingTableDN: cn=CustomerID User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
-
changetype: modify
replace: ubiloginDirectoryServiceDN
ubiloginDirectoryServiceDN: cn=CustomerID Directory,cn=Services,ou=System,cn=Ubilogin,dc=example,dc=com
-

In the example above there is a precondition that there is already a configured authentication method called tupas.test.1, which is now equipped with the ubiloginLDAPURLMappingTableDN and ubiloginDirectoryServiceDN attributes, which enable the user driven federation functionality.

Configuring User Driven Federation with Authentication Method Grouping

When a set of authentication methods are operating in, what could be considered, the same domain such as TUPAS, it may be feasible to configure the system in such a way that it allows the user to form a federation link from one authentication method and have this link be recognized when signing on from another authentication method of the same conceptual domain. This is only possible when authentication methods return an exactly matching user identifier, like a personal identity number, a social security number or something similar.

It may be desired to have other authentication methods operate in their own domains, and still be available to form federation links with. Furthermore, not all authentication methods have the same set of attributes identifying the user, so what may work for one authentication method may not work for another when customized.

If a unifunctional federation is desired between a set of TUPAS methods, it is sufficient to modify the previously created Ubisecure CustomerID specific Ubilogin Service User Mapping Entry and override parts of the NameID definition which makes the identifier domain specific. Although the NameID definition is based on SAML 2.0 NameIDType parameters, there are no enforced naming conventions how to define values for these attributes, but still these choices should be guided by business requirements rather than random naming. The NameID consists of following attributes, differing only by capitalization (which is important to get right), described by SAML 2.0 as follows:

Configuration attribute	SAML 2.0 counterpart	SAML 2.0 definition
nameQualifier	NameQualifier	The security or administrative domain that qualifies the name. This attribute provides a means to federate names from disparate user stores without collision.
spNameQualifier	SPNameQualifier	Further qualifies a name with the name of a service provider or affiliation of providers. This attribute provides an additional means to federate names on the basis of the relying party or parties.
format	Format	A URI reference representing the classification of string-based identifier information…
spProvidedID	SPProvidedID	A name identifier established by a service provider or affiliation of providers for the entity…
value	Element's text content	The string content containing the actual identifier.

It is worth repeating, that the SAML 2.0 definitions hold no semantics in the context of account linking, but can be useful when deciphering how the NameID is formed by default and deciding how to form federation links. In the example below a common authentication domain for TUPAS is configured by modifying the NameID formation.

Listing 6. LDIF block creating a specialized Ubilogin Service User Mapping Entry

dn: cn=44a5a6c3-706e-419f-adf8-d31f182bcffa,cn=CustomerID User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: add
objectClass: ubiloginServiceUserMappingEntry
objectClass: ubiloginServiceReference
objectClass: top
ubiloginServiceDN: cn=CustomerID Federation,cn=Services,ou=System,cn=Ubilogin,dc=example,dc=com
ubiloginServiceInputParameter: subject ${nameID.format('hetu').nameQualifier('tupas.group').spNameQualifier('tupas.group').spProvidedID(method.CUSTID).value(method.CUSTID)}

Authorization Policy Requirements for Authentication Method Grouping

It is possible to configure CustomerID to create federation links during registration. In case authentication method grouping configuration should be in effect, it is necessary to configure the SAML Assertion's NameID element to be produced with compatible attributes. This can be done by extending the workflow.policy Authorization Policy definitions.
For example, if the serviceInputParameter in Listing 6 were to be used, the authorization policy should be modified as follows:

Log on to SSO Management application with administrative privileges
Locate workflow.policy by navigating to eIDM Services and select Authorization Policies
Switch to Attributes tab
Click Add... button, navigate to eIDM Groups, choose the PendingTupasUsers group and click Ok
Specify a descriptive name to the new attribute, e.g. setNameID
Click Show values and enter the same nameID expression as earlier, omitting the label
Click Update to store the new value

Listing 7. Authorization policy setNameID() attribute's example value

${nameID.format('hetu').nameQualifier('tupas.group').spNameQualifier('tupas.group').spProvidedID(method.CUSTID).value(method.CUSTID)}

The resulting workflow.policy should look as below


Figure 1 workflow.policy modifications

Listing 8. Authorization policy setNameID() with references to original NameID, read from the username object

${nameID.format('hetu').value(method.CUSTID).spProvidedID(username.spProvidedID).spNameQualifier(username.spNameQualifier).nameQualifier(username.nameQualifier)}

Configuring Differing NameID Formations for User Driven Federation

This use case may arise from various business requirements. For example, two authentication methods are required to work in a common domain and a third one in a separate or maybe some common domain authentication methods supply the same identifying attribute with different names. In these cases it is required to register specialized User Mapping Tables for each authentication method.
In the example below, the previously defined specialized Ubilogin Service Mapping Entry has been registered to the method tupas.test.1 using an LDIF like below:

Listing 9. Modifying tupas.test.1 method to offer federation

dn: cn=tupas.test.1,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: modify
replace: ubiloginLDAPURLUserMappingTableDN
ubiloginLDAPURLUserMappingTableDN: cn=CustomerID User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
-

Now, a third authentication method - let's call it myidp.test.1 - is required to operate with a different federation configuration, so following LDIFs need to be imported.

Listing 10. LDIF block creating a new User Mapping Table

dn: cn=MyIDP User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: add
objectClass: top
objectClass: ubiloginLDAPURLUserMappingTable
cn: MyIDP User Mapping

This authentication method would then operate in its own domain, so just rely on the NameID formed by default.

Listing 11. LDIF block creating a new Ubilogin Service User Mapping Entry

dn: cn=12341234-706e-419f-adf8-d31f182bcffa,cn= MyIDP User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: add
objectClass: ubiloginServiceUserMappingEntry
objectClass: ubiloginServiceReference
objectClass: top
ubiloginServiceDN: cn=CustomerID Federation,cn=Services,ou=System,cn=Ubilogin,dc=example,dc=com
ubiloginServiceInputParameter: subject ${nameID}
cn: 12341234-706e-419f-adf8-d31f182bcffa

Next, register the User Mapping Table to the authentication method myidp.test.1

Listing 12. Modifying myidp.test.1 method to offer federation

dn: cn=myidp.test.1,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
changetype: modify
replace: ubiloginLDAPURLUserMappingTableDN
ubiloginLDAPURLUserMappingTableDN: cn=MyIDP User Mapping,cn=Server,ou=System,cn=Ubilogin,dc=example,dc=com
-

Importing LDIF to Ubisecure Directory

Listing 13. Importing LDIF file to Ubisecure Directory (linux)

cd /usr/local/ubisecure/ubilogin-sso/ubilogin/ldap/openldap
./import.sh /path/to/file.ldif

Listing 14. Importing LDIF file to Ubisecure Directory (Windows)

cd /D "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\ldap\adam"
import.cmd C:\path\to\file.ldif

Language keys for User Driven Federation

Listing 15. UDF language keys in i18n/uas.properties

CONFIRM_INTRO_TITLE = Create Account Link
CONFIRM_INTRO_TEXT = Before entering the requested service you can link your external identity with your existing user permanently. 
CONFIRM_HELP_TITLE = Help
CONFIRM_HELP_TEXT = The account you used has not been linked to your existing account. Please save the link and continue to the service.
CONFIRM_HELP_LINKS = 
CONFIRM_LOGIN_TITLE = Account Settings
CONFIRM_LOGIN_TEXT = Please select to remember the account link.
CONFIRM_LOGIN_PERSISTENT_TEXT = Remember this next time

Listing 16. UDF language keys in i18n/errors.properties

FEDERATION_MISSING = No federated account found

Listing 17. UDF language keys in template/messages/federation.properties

MENU_LOGIN_TITLE = Already have an account?
MENU_LOGIN_TEXT = Please enter your existing username and password.
MENU_HELP_TITLE = Help
MENU_HELP_TEXT = The account you used to log in hasn't been used before at this service. If you already have an existing local account, please sign in with your username and password above to link your account. Please sign in with your existing username and password or register a new account.
MENU_HELP_LINKS = <li><a href="javascript:view.navigate('register.account')">Register</a></li><li><a href="javascript:view.navigate('password.reset')">Password Reset</a></li>
PASSWORD_HELP_TITLE = Help
PASSWORD_HELP_TEXT = The account you used to log in hasn't been used before at this service. If you already have an existing local account, please sign in with your username and password above to link your account. If you don't have an account, please create one by registering.

Listing 18. UDF configuration keys in template/default/federation.properties

title = Ubisecure SSO
usemethodgroups = true
links = federation.links

Listing 19. UDF configuration keys in custom/template.index

federation = templates/federation.properties

Listing 20. UDF configuration keys in template/default/federation.links

register.account.url = https://cid.example.com/eidm2/wf/protection/1
register.account.methods = password.1 password.2, tupas.test.1

The configuration above defines to which registration users should be redirected if it is desired for users to be able to create their user accounts on the fly. It is possible to widely use the configuration options detailed in Ubisecure CustomerID Configuration document, please refer therein for further documentation. If you want to utilize the attributes of the external authentication method in the registration or perform the authentication method linking automatically during registration, you should use a protection URL definition here instead of a direct registration URL. So instead of using for example: "https://cid.example.com/eidm2/wf/register/udf" you should use something like the following: "https://cid.example.com/eidm2/wf/protection/1". You then need to configure the protection so that it forwards to the correct registration.

Listing 21. UDF configuration keys in protection.properties

protection.1.methods = password.2, tupas.test.1
protection.1.sso.template = udf
protection.1.continue = https://cid.example.com/eidm2/wf/register/udf
protection.1.customeriduseronly = false

Preventing Disabled Users From Logging In Using User Driven Federation

This chapter is relevant if you are using Ubisecure SSO version lower than 8.3.x.

If a user has an existing authentication method linkage that has been created using user driven federation that user can by default still use that method to access applications even though the user is later disabled. To prevent this you can modify the authorization policy for the application in Ubisecure SSO Management. Here is an example for an authorization policy attribute value definition:

${eidm['user:status'].contains('1') ? 'true' : null}


In this example the attribute has been named 'enabled'.

Then you need to add the same attribute to the list of required attributes.


In this example the 'enabled' attribute has been added to the list of required attributes.

Browser not supported