In this example we will walk through connecting an SP which has a list of users in it, and an IdP which also have a list of users. The users in the SP’s datastore map to those in the IdP’s datastore one-to-one. The SP wishes to be able to allow their users to log in when they’re authenticated with the IdP. To link the accounts the SP desires that the user goes through a full, valid authentication flow on both the IdP and the SP once.
To configure local account linking using the SAML2 authentication module, it’s necessary to configure some specific options inside the module and also inside the SP’s settings.
We’ll start by generating an SP using the common tasks wizard.
It is necessary to map the attributes which will be used to generate the data from the datastore - this is performed on the SP’s side. In this example, we will use the special *=* mapping, which means “for each attribute in the assertion, generate an attribute with that same name and value and store it in the generated session (and in the datastore if generating a local user account)”.
Finally as we’ll be using this SP in an authentication chain, as per the article SAML2 in chain authentication - The SAML2 Auth Module we must alter the Assertion Consumer Service for HTTP-Artifact and HTTP-POST binding types.
Now we’re ready to link our IdP and SP together using the ‘register remote [service/identity] provider’ common tasks in the appropriate provider. While you’re linking the SP to the IdP, you should set up some attributes from the IdP which will be included in the assertion which is sent to the SP - earlier we indicated that ‘uid’ would be our unique identifier, so let’s ensure we’re going to expose that, alongside a field we’ll recognise when we see it on the SP’s side - in the example here I’ve chosen the ‘mail’ attribute, and mapped it to a key/value in our assertion whose key is also ‘mail’. As the SP was configured with *=*, the ‘mail’ attribute in our assertion will be dynamically mapped to a ‘mail’ attribute in our SP’s datastore, as well as a session property named ‘mail’.
Finally on the IdP, let us generate a subject in the IdP’s datastore with a subject whose mail attribute is populated so that we will recognise it when we see it in the SP’s datastore later, and when we check the value of the federated session's properties.
Now the IdP is configured, it’s time to set up the authentication module proper.
Head back to the SP. Generate a new SAML2 authentication module. Here you’ll want to enter the meta alias and IdP Entity ID for your local SP and your remote IdP respectively. As we want the accounts to be persistently linked, we’ll allow for identifiers to be generated on the IdP by enabling Allow IdP to Create NameID and setting the NameID Format to urn:oasis:names:tc:SAML:2.0:named-format-persistent. To link the accounts, we need to specify the name of the authentication chain which will be used to identify the user in the SP's datastore. Enter the name of the chain in the Linking Authentication Chain field that will identify the user (this chain must include at least one first factor module - a module which results in the system knowing the local username of the user, for example the DataStore module). In this example we’ll call it ‘linkChain’. No other configuration settings are necessary to demonstrate the local account linking federation process.
We’ll need to generate the chain which will hold the authentication module. In this example, we will simply have the authentication module alone, and no other module following it.
Now let’s create ‘linkChain' - a secondary authentication chain which simply contains a DataStore module and nothing else.
Users attempting to access the SP will be prompted to log in to the IdP. If their accounts are already linked, they will then immediately be logged into the SP also. If their accounts aren't already linked, after successful IdP authentication they will be redirected to the SP's 'linkChain' authentication chain, and after successfully completing that chain their accounts will be linked and they will be logged in.