The OpenID connect standard defines two methods for retrieving user characteristics using claims: through the userinfo endpoint, or through the claims request parameter.

The userinfo method is the most commonly used method and is supported by all certified libraries. The userinfo endpoint acts as an OAuth2 resource server, and the client can use the access_token obtained after a successful login flow to authenticate against the userinfo endpoint and retrieve the user claims as a json document.

You can use our playground application to check how this works. For testing purposes you can one of our test-IdP's. The playground application shows how the client creates the request, and what the userinfo endpoint returns.

Alternatively, by using the claims request parameter claims are included in the id_token. SURFconext also supports this method because some client implementations expect this behaviour.

OpenID Connect or SAML?

When you connect to SURFconext you can use OpenID Connect or SAML as a protocol to authenticate a user using SURFconext. Different standards result in different protocols and in their turn tend to use a jargon specific to that standard. This is also the case with OpenID Connect and SAML. This page depicts how to translate the commonly used SAML attributes to OpenID Connect claims and vice versa.

OpenID Connect Claims and SAML attributes

Most services require extra information about the authenticated user, such as a name, email address or affiliation. In OpenID Connect (OIDC), this extra information comes in the form of claims, whereas in SAML, claims are called attributes. In SURFconext, the user authenticates at his Identity Provider (called OpenID Provider in OIDC) - this all happens using SAML. SURFconext translates the incoming SAML attributes to OIDC Claims and provides them at the userinfo endpoint for your Service Provider (called Relying Party in OIDC) to consume.

Please note: The access token has a lifetime, which is by default configured at 1 hour. After the lifetime of the access token has expired, it's no longer possible to retrieve the claims.

An extensive list of SAML attributes together with their details and properties can be found on our support page about attributes.  Those SAML attributes are provided by institutions connected to SURFconext as Identity Provider. You can use any of those attributes in your service (SURFconext translates them to OpenID Connect claims), however you must comply with our data minimisation policy, meaning you are only allowed to receive the bare minimum of attributes strictly needed for you to operate your service.

User identifiers

The user's identity is transmitted in the form of the NameID element by an IdP. Every IdP must supply this, but for privacy reasons SURFconext will generate a new one, which is duplicated in the subject.

To identify a user the relying party can use the subject. This subject is made available in the "sub" claim. In SAML this is called the NameID. This subject is guaranteed to be stable for a fixed user, except in the case of transient identifiers. SURFconext will generate a subject for each new user. It is unique for the user and specific to the relying party, so RP's cannot correlate their received subject's between each other. There are two types:

  • persistent
    A persistent subject contains a unique string identifying the user for this RP and is persisting over multiple sessions.
  • transient
    A transient subject contains a unique string identifying the user for this RP during the session. If the user logs in again, a new transient subject will be generated.


The subject, when set to persistent, is unlikely to change and very privacy aware but can change when service providers or identity provider make critical changes. This can cause user profiles for services to be lost. The subject is generated using the uid, schacHomeOrganization, the Client id of the relying party together with a secret that uses a SHA algorithm. Institutions or services that are in production and change one of these attributes, will cause a new subject to be generated by SURFconext when doing so. This can cause loss of access to profiles at services. We will notify identity providers and relying parties when we see a change in one of these claims to prevent user data being lost.

The following table describes the translation from OpenID Connect Claims to SAML attributes.

OpenID Connect Claim

SAML Attribute

Description of attribute


OpenID Subject (not available as SAML attribute)



Given name






Common name (e.g. Prof.dr. John Doe)



Display name (e.g. Prof.dr. Jane Doe)



Display name (e.g. Prof.dr. Jane Doe)



Preferred language (e.g. nl, en)



Email address
Boolean, always "true" when an email address is provided
ouurn:mace:dir:attribute-def:ouOrganizational Unit


Organization (e.g.


Organization type (e.g. educationInstitution, universityHospital)



Affiliation (student, employee, etc)



Scoped affiliation (e.g., )



UID (unique code for a person that is used as the login name within the institution)



Personal code (e.g. student number)



EduPersonPrincipleName (This is a scoped identifier. e.g.



eduPersonEntitlement (e.g.


-nlEduPersonOrgUnitDeprecated and unavailable in both OIDC and SAML
-nlEduPersonStudyBranchDeprecated and unavailable in both OIDC and SAML
-nlStudielinkNummerDeprecated and unavailable in both OIDC and SAML

  • No labels