Attribute Completion Flow
Services that are used by SWITCH edu-ID users sometimes need certain attributes about the user, which might not have been added by the user to his profile. In such a case, the service should display the user an error message and ask him to add the required attribute to his SWITCH edu-ID account. This page describes how to initiate this workflow that sends the user to his SWITCH edu-ID account to add missing attributes and also redirect the user back to the service afterwards.
The process how to make a user add a particular attribute to his SWITCH edu-ID account and have him return automatically to the service page is illustrated and described in the graphic below:
Please have a look at the edu-ID Link Composer to easily generate attribute completion flow (and more) URLs related to edu-ID login and registration flows.
For the following scenario we assume that:
- The user has used his SWITCH edu-ID account to access a service
- The (web) service is protected by a SAML Service Provider (e.g. Shibboleth)
- The service has detected that the user misses an attribute in his account, which the service needs to function
The flow is composed of the following steps:
- The web application should display the user a message that invites him to add the missing attribute to his SWITCH edu-ID account. This message could be for example: "In order to get immediate access to the <service name> content, you need to add a Swiss mobile phone number to your SWITCH edu-ID account". The link to send to the user is composed by the following parameters:
- Base URL (mandatory): This can be https://eduid.ch/web/edit-attribute/ or https://eduid.ch/web/verify-attribute/ depending on which attribute(s) should be added or verified. For the Swiss edu-ID Test instance, just add "test." before the hostname of these two URLs.
- GET parameter "attribute" (mandatory): The value of this attribute is the name of the attribute to add or verify. Common attributes to add/verify are "postaladdress", "homepostaladdress", "telephonenumber", "homephone", "mobile", "preferredlanguage", "swissedupersondateofbirth", "swissedupersongender", "swissedupersonadditionalemail".
- GET parameter "providerId" (mandatory): The SAML2 entityID of the Service Provider that protects the service
- GET parameter "target" (mandatory): URL to send the user to on the service after he added the attribute. Note that this URL must use the same hostname like the "entityID" or the optional "shire" parameters in case the Service Provider has several assertion consumter URLs.
- GET parameter "shire" (optional): Endpoint URL where the Swiss edu-ID IdP should send the SAML assertion to. This has only to be provided if another endpoint should be used than the default one for the SP.
- Two example links URL (pointing to the test instance and making the user add his day of birth or add his verified mobile number) would look like this: https://test.eduid.ch/web/edit-attribute/?attribute=swissedupersondateofbirth&providerId=https%3A%2F%2Fattribute-viewer.aai.switch.ch%2Fshibboleth&target=https%3A%2F%2Fattribute-viewer.aai.switch.ch%2Faai https://test.eduid.ch/web/verify-attribute/?attribute=mobile&providerId=https%3A%2F%2Fattribute-viewer.aai.switch.ch%2Fshibboleth&target=https%3A%2F%2Fattribute-viewer.aai.switch.ch%2Faai
- Upon clicking the link generated above, the user is sent to the SWITCH edu-ID Account Management web site. Unless he was already authenticated to edit his account, he has to authenticated again. He will be directly sent to the page where he is asked to provide the missing attribute (e.g. the mobile number). He then provides and/or verifies the attribute using the predefined process for the particular attribute. Please take into account that the verification process can take some time (from a few seconds in case of email or mobile number till a few days in case of the home postal address).
- Once the particular attribute has been provided or verified, the user will see a confirmation message and a button that asks him to proceed. Clicking the button to proceed, the user is sent to the Identity Provider Session Initiatiator which is called using the arguments from step 1.
- Because the user at this point still has an authenticated IdP session, no re-authentication is needed. Instead, the IdP generates a new SAML assertion (now including the added attribute) and sends the user to the Shibboleth SP assertion consumer URL endpoint. In case, a "shire" parameter was provided in step 1, this endpoint is used instead of a default endpoint for the Service Provider.
- The SAML Service Provider receives a new SAML assertion for the user. Therefore, it will overwrite the user's session with the new up-to-date data and attributes now also including the new attribute that the user added in step 2. The Service Provider finally should sent the user to the URL that was provided in the "target" parameter in step 1.