You're going to connect your service to SURFconext. Instead of username and password, your service will be dealing with attributes (or claims if you use OpenID Connect) in the future. But what attributes should you request?
In short:
- As few as possible (for your service to work properly)
- As privacy preserving as possible (for your service to work properly)
SURFconext, in line with the forthcoming European General Data Protection Regulation (GDPR), assumes a minimum disclosure principle. In short, this means a service should only process (personal) information that is strictly necessary for providing the service.
Identifiers: the best option
Of course, from a privacy perspective, the best option is to request no user information at all. However, every it would then be challenging to recognise actual users. The next best option and most privacy preserving option is to use the transient NameID. The NameID is a standard element in the SAML response, but is also available as the eduPersonTargetedID attribute.
| NameID | Service Providers who have no need to identify one user from another can use this attribute. The transient NameID is an opaque identifier generated by SURFconext - it is impossible to see who is behind it. It also changes every time the user re-authenticates - as a Service Provider, you are therefore unable to see whether it is the same user logging in, or someone else. |
|---|
If you do need to identify returning users, the persistent NameID is available; a persistent Name ID is like the transient NameID explained above, except that returning users will have the same NameID.
Identifiers: the second best option
If your service needs more information (for example, if your service needs to be able to recognise users prior to their first login), the following identifiers are available (from more to less privacy preserving):
Employee-student number | This is a number that is often used within internal institution systems and very well suited for uniquely identifying users without affecting their privacy too much. However, currently only a few institutions provide this attribute. If you wish to use this attribute, please inform the SURFconext Team; they will ask the institution to provide this attribute. |
|---|---|
| UID | A UID is unique for an institution, but it is not unique within SURFconext. The same UID could be used for different persons in different institutions. A solution to this problem would be to combine UID with another attribute, schacHomeOrganization, which allows uniquely identifying users across organisations. However, UIDs often leak more information than necessary, since they often contain usernames or other personally identifiable information (such as first or last names). |
Principle Name | The principal name can be used to uniquely identify a user. However, principle name is reusable: that means that when john@example.edu leaves the university, a second John could be provided with the same principle name. In other words, principle name is reassignable. |
| The email attribute could also be used to identify a user. However, we strongly advise against it: an email address can change over time (e.g. after marriage or when someone changes surname). Also, email is reusable: that means that when john@university.edu leaves the university, a second John could be provided with the same email address. Furthermore, the email attribute is multi valued, which means a user can have more than one email address. |
Other attributes
Next to identifiers, there are other types of attributes available to discern between different types of users without necessarily knowing the exact identity of the user.
eduPersonAffiliation | This attribute indicates whether the user logging in is a student, employee, faculty, prestudent and/or affiliate. |
|---|---|
| eduPersonEntitlement | Sometimes the Identity Provider is in charge of managing authorisations, e.g. which user or group is entitled to which roles and rights within a Service Provider. A very handy attribute for managing this is the eduPersonEntitlement attribute. |
| eduPersonOrcid | For services specifically aimed at researchers, it might be necessary to use the eduPersonOrcid attribute. |
Mapping attributes to existing users
If you are connecting an existing service you probably already have a user database. You need attributes which you can map to the information you already have about users. Common options are:
| User information | username | student number | |
|---|---|---|---|
| SAML attributes | ? | schacPersonalUniqueCode | |
| OpenID Connect Clains | ? | ? | ? |
By connecting your service to SURFconext, the institutions connected to SURFconext will take care of authenticating your users. After the user has successfully authenticated at his institution, SURFconext, who acts as a proxy, delivers a message to your service which states that the user is successfully authenticated. So what's next?
Introduction: attributes, claims and privacy
Besides knowing that a user is successfully authenticated, your service might need to know additional things about the user, such as whether the user is a student or employee. The Identity Providers connected to SURFconext can provide your service with this information, in the form of attributes. (If your service uses OpenID Connect, you might only know the term claims; this term is interchangeable with attributes.)
SURFconext, in line with the forthcoming European General Data Protection Regulation (GDPR), assumes a minimum disclosure principle. In short, this means a service should only maintain (personal) information that is strictly necessary for providing the service.
In practice, this means you are only allowed by law to receive those user attributes that you strictly need for providing the service. For instance, if your service allows users to share files with each other and sends out notifications to users when a new file is shared, you can use the user's email address attribute. However, if you only use the user's email address for marketing purposes, you might want to reconsider whether this fits the requirements of the GDPR. Because of this, SURFconext requires each Service Provider to specify which attributes are needed and why during the registration process.
It is therefore highly recommended that you carefully think about the attributes your Service Provider needs early in the process of connecting your service to SURFconext. The remainder of this page provides some guidance on most used attributes within SURFconext.
Identifiers
First of all, think about whether your service really needs to identify one user from another. If not, SURFconext provides a very privacy-friendly identifier, the transient NameID. This is an opaque identifier generated by SURFconext - it is impossible to see who is behind it. It also changes every time the user re-authenticates - as a Service Provider, you are therefore unable to see whether it is the same user logging in, or someone else.
If you need additional functionality, such as knowing whether it is the same user again or which identifier is associated with the user has at his institution, other options are available. Please refer to this page with additional information on identifiers.
Names and email addresses
Your service might also need a way for other users to be able to see who is who, for instance when users are able to collaborate with each other through your service. In such a case, you might need attributes like name and email address. SURFconext offers several options for such attributes; please refer to the technical attributes page to see which you can use.
Institution
In some cases, your service does not necessarily need to know who the user is, only which institution the user comes from. Your service might need to be able to discern between users from the University of Harderwijk and the Applied University of Monnickendam. In this case, it could be argued your service needs an attribute that contains exactly this information, such as schacHomeOrganization. Please refer to the technical attributes page for more information about this attribute.
Other attributes
Another attribute that can be used to discern between differents types of users without necessarily knowing the exact identity of the user, is using the eduPersonAffiliation attribute. This attribute indicates whether the user logging in is a student, employee, faculty, prestudent and/or affiliate. Please refer to the technical attributes page for more information about this attribute.
Sometimes the Identity Provider is in charge of managing authorisations, e.g. which user or group is entitled to which roles and rights within a Service Provider. A very handy attribute for managing this is the eduPersonEntitlement attribute. Please refer to the technical attributes page for more information about this attribute.
For services specifically aimed at researchers, it might be necessary to use the eduPersonOrcid attribute. Please refer to the technical attributes page for more information about this attribute.