Mapping SPID attributes

This is the most tedious task. It is easy but repetitive and any error can go unnoticed for a long time, so be careful when following the next steps.

The idea is that we have to tell Keycloak how to store the SPID attributes in its local user representation. There is no one-size-fits-all way to do that, but I'll share the way I do it. Feel free to change this strategy to fit your needs - just be consistent and look out for typos.

For each Identity Provider, click on the Edit button and go to the Mappers tab. We'll have to create a new Mapper for each attribute we want to import.

User Name attribute

We'll start with the User Name attribute. Click on the Create button and set the following attributes:

Name	Mapper Type	Template
User Name	SPID Username Template Importer	${ATTRIBUTE.fiscalNumber}

This setup means that all SPID users will have their username set to their fiscalNumber SAML assertion value, lowercased according to the Keycloak convention (e.g. tinit-jpqvqn30s18x699c).

NOTE: There is no limit on how many SPID providers a user can register to. By mapping the User Name attribute to the fiscalNumber assertion, if a user logs in with different SPID providers the two different accounts will be mapped to the same Keycloak user. Make sure you selected the Sync Mode: Force value in the Identity Provider configuration!

Basic attributes

First Name and Last Name are essential to identify the user and should be mapped to special Keycloak attributes. Use the following table as a reference for the two required mappers:

Name	Mapper Type	Attribute Name	User Attribute Name
First Name	SPID Attribute Importer	name	firstName
Last Name	SPID Attribute Importer	familyName	lastName

TIP: You could be tempted to map the email assertion to the basic email Keycloak attribute. You can of course do that, but it has a pretty important side-effect: users can trigger the Forgot Password flow, and set a local password for the SPID account. If this happens, you can't trust the user to have a valid SPID session. It is much safer to map the email attribute to a SPID-specific attribute as described in the next paragraph.

Other attributes

All of the other SPID attributes are optional and follow the same convention. I'll leave the mapping table here for sake of consistency:

Name	Mapper Type	Attribute Name	User Attribute Name
SPID Code	SPID Attribute Importer	spidCode	spid-spidCode
Email	SPID Attribute Importer	email	spid-email
Tax Id	SPID Attribute Importer	fiscalNumber	spid-fiscalNumber
Gender	SPID Attribute Importer	gender	spid-gender
Date of Birth	SPID Attribute Importer	dateOfBirth	spid-dateOfBirth
Place of Birth	SPID Attribute Importer	placeOfBirth	spid-placeOfBirth
County of Birth	SPID Attribute Importer	countyOfBirth	spid-countyOfBirth
Mobile Phone	SPID Attribute Importer	mobilePhone	spid-mobilePhone
Address	SPID Attribute Importer	address	spid-address
Digital Address	SPID Attribute Importer	digitalAddress	spid-digitalAddress
Company Name	SPID Attribute Importer	companyName	spid-companyName
Company Address	SPID Attribute Importer	registeredOffice	spid-registeredOffice
VAT Number	SPID Attribute Importer	ivaCode	spid-ivaCode

Once mappings have been created for all SPID IdPs, we have to prepare our Service Provider metadata.