You're going to connect your service to SURFconext. Instead of username and password, your service will be dealing with user 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 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
The best possible way (from a privacy perspective) to make your service work within SURFconext is to use a pseudonymised identifier generated by SURFconext. In SAML, this value can be found in the NameID element; in OpenID Connect, it will be in the sub claim.
When using this identifier, there are 2 options: transient and persistent.
| SAML Attributes | OpenID Connect Claims | Explanation |
|---|---|---|
| NameID element (transient) | sub claim (transient) | Service Providers who have no need to identify one user from another should use this attribute. The transient NameID/sub claim 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. |
| NameID element (persistent) | sub claim (persistent) | If you do need to identify returning users, the persistent NameID/sub claim is available; a persistent NameID/sub claim is like the transient NameID/sub claim explained above, except that returning users will have the same value each time they return. |
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 (ordered from more to less privacy preserving):
| SAML Attribute | OpenID Connect Claim | Explanation |
|---|---|---|
| schac_personal_unique_codes | 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 | uids | 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). Be aware that uid is reusable. This means that when 'John' leaves the university, a second John could be provided with the same uid. |
| The principal name can be used to uniquely identify a user. Bear in mind that the principal name is reusable. | ||
| 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.
| SAML Attributes | OpenID Connect Claims | Explanation |
|---|---|---|
edu_person_affiliations | This attribute indicates whether the user logging in is a student, employee, faculty, prestudent and/or affiliate. | |
| eduPersonEntitlement | edu_person_entitlements | 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. |
| SchacHomeOrganization | schac_home_organization | This attribute allows you to discern users from university 'x' from university 'y'. This attribute is extremely handy if you don't need to know who the user is, only which institute the user is from. |
For all available attributes check the following page. Remember, the more attributes you request, less obvious it becomes an institutions wants to connect to your service. Choose wisely.
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:
| Existing user information | SAML Attributes | OpenID Connect Claims |
|---|---|---|
| username | uid | uids |
| student number | schacPersonalUniqueCode | schac_personal_unique_codes |