-
Notifications
You must be signed in to change notification settings - Fork 22
Generating SP metadata
The SPID federation requires a single metadata document for a service provider, while Keycloak generates a metadata document for each IdP. We need to take the N metadata documents that Keycloak generates and join them in a new document that we'll have to host separately.
Starting from version 1.0.7, this provider can automatically generate and sign the SPID SP metadata document for the SPID federation. If you have filled in the required fields as described in the previous page, just look for the SPID Service Provider Metadata link in any of the SPID IdP settings page, or go directly to the address http(s)://<host>:<port>/auth/realms/<realm_name>/spid-sp-metadata. You can share the same link with AGID to complete the SPID onboarding process.
TIP: Remember that all of the "shared" data in the metadata is actually set by the first SPID IdP in alphabetical order only! There is no need to copy the same data in all of the IdPs.
TIP: The attribute mappings in the AttributeConsumingService section are automatically populated from the configured Mappers for the first SPID IdPs. As we haven't configured them yet, it is normal that this section is empty - you can proceed to define the attribute mappers now.
If for any reason the automatic metadata generation is not enough for your needs, you can always manually edit the metadata document. In this case I strongly suggest starting from the automatically generated document described above. However, if you really like the smell of handcrafted, artisanal SAML SP metadata documents, you can always build one yourself. The basic idea is that you'll have to join all of the individual SP metadata documents for each SPID IdP, join them together, apply the changes you need and then sign the resulting document.
To download the SP metadata documents for our providers, access the Identity Providers configuration screen and enter the Edit page for each of the Identity Providers defined. Look for the SAML 2.0 Service Provider Metadata link and download it.
TIP: Make sure to give a sensible name to the downloaded documents, because they will have the same name.
Now that you have the N documents on your disk, copy one of them into a new one called spmetadata.xml. We will add the required sections to this document.
For each document you have downloaded, find its AssertionConsumerService element and copy it under the SPSSODescriptor in spmetadata.xml. Make sure to update the index attribute - there must not be any duplicates.
The end result will look like this:
<SPSSODescriptor>
...
<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.domain.com:8443/auth/realms/public/broker/NamirialSpidL2/endpoint" index="0" isDefault="true" />
<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.domain.com:8443/auth/realms/public/broker/PosteSpidL2/endpoint" index="1" />
<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.domain.com:8443/auth/realms/public/broker/LepidaSpidL2/endpoint" index="2" />
...
<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.domain.com:8443/auth/realms/public/broker/InfocertSpidL2/endpoint" index="8" />
...
</SPSSODescriptor>
TIP: The XML elements of metadata documents have a precise sequence. The AssertionConsumerService elements must be right one after the other.
Now we'll need to declare an Attribute Consuming Service. Inside the SPSSODescriptor element, after the AssertionConsumerServices, add the following section:
<SPSSODescriptor>
...
<AttributeConsumingService index="1">
<ServiceName xml:lang="en">My online services</ServiceName>
<RequestedAttribute Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="familyName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="fiscalNumber" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="placeOfBirth" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="dateOfBirth" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="mobilePhone" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="gender" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="spidCode" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="countyOfBirth" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="digitalAddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="address" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="ivaCode" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="companyName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
<RequestedAttribute Name="registeredOffice" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
</AttributeConsumingService>
...
</SPSSODescriptor>
These are all the attributes available in the SPID federation. Feel free to remove any attribute you don't need.
Notice the index attribute on the AttributeConsumingService element: if you want, you can define multiple attribute sets. In this case, set the Attribute Consuming Service Index parameter in the Identity Provider settings to the appropriate value.
TIP: The XML elements of metadata documents have a precise sequence. Place the AttributeConsumingService element after the AssertionConsumerService elements.
Starting with SPID Notice n. 29v3, organizations must add a few descriptive details to the SP metadata:
<SPSSODescriptor>
...
<Organization>
<OrganizationName xml:lang="en">My organization name</md:OrganizationName>
<OrganizationDisplayName xml:lang="en">My organization display name</md:OrganizationDisplayName>
<OrganizationURL xml:lang="en">https://my.organization.url</md:OrganizationURL>
</Organization>
<ContactPerson contactType="other">
<Extensions>
<spid:IPACode xmlns:spid="https://spid.gov.it/saml-extensions">your_public_administration_id</spid:IPACode>
<spid:Public xmlns:spid="https://spid.gov.it/saml-extensions"/>
</Extensions>
<EmailAddress>tech@localhost</EmailAddress>
</ContactPerson>
...
</SPSSODescriptor>
Please refer to the above mentioned notice for the details about the specific extensions applicable to your organization.
TIP: The XML elements of metadata documents have a precise sequence. Make sure the Organization element is the very last one in the document.
Now that the SP metadata document is complete, you should share its publicly reachable address with the federation central administration to start the onboarding process. While they do their job, we'll configure the Authentication flow.