-
Notifications
You must be signed in to change notification settings - Fork 22
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.
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!
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.
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 |
SPID Attribute Importer | 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.