This page describes all the OpenID Connect (OIDC) features supported by SURFconext. All features mentioned here are compliant with the OpenID Connect specification.

Getting claims (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. Check out our extensive documentation on claims here.

There is more then one way to get claims. By default you can use the userinfo endpoint. Almost any OpenID Connect libary or OIDC supported application has support for it. If your library or application expects the claims to be present in the id_token, you can request those using the "claims" request parameter.

Use our OIDC Playground application to see how this works.

Another alternative is that we always return the claims in the id_token. Please contact support if you want us to enable that option.

Supported flows

All OpenID Connect flows (code, implicit and hybrid) are supported by SURFconext. We strongly recommend you use the code flow for your application. If you have a client that is not able to keep a secret (e.g. a Mobile App, or a JavaScript client), using PKCE is required. This method is described below.

With the response_type parameter during the authorisation request you can specify which flow to use. The following values are allowed:

Proof Key for Code Exchange (PKCE)

PKCE is a security mechanism designed for public clients (apps that cannot safely store a client secret, such as mobile apps, single-page apps, or desktop apps). It was originally created for OAuth2 and is now widely used in OIDC as well.

Without PKCE, an attacker could try to intercept the authorization code during the redirect step and then use it to request tokens. This risk is especially high for apps that use custom callback URLs (for example mobile apps), since a malicious app could register the same redirect URL and “steal” the code.

PKCE prevents this by introducing an extra secret that only the client knows:

1. Before starting login:
   The client generates a random string called the code_verifier. It also creates a hashed version of this string (the code_challenge) using SHA-256.

2. During the authorization request:
   The client includes the code_challenge and the chosen method (code_challenge_method=S256) in the request to the authorization server.

3. During the token request:
   When exchanging the authorization code for tokens, the client must also send the original code_verifier.

4. Validation by the server:
   The server checks that the code_verifier matches the earlier code_challenge. If they don’t match, the request is rejected and no tokens are issued.

This mechanism effectively ties the authorization code to the client that requested it. Even if someone else manages to intercept the code, they cannot use it without also knowing the secret code_verifier.

More information can be found in the specification: https://tools.ietf.org/html/rfc7636

Scopes

Currently, we only support the scope openid. You may use any of the other scopes as specified in the OpenID Connect specification (profile, email, address, phone) but these are silently ignored. You will receive the claims you requested during the deployment in the SP Dashboard.

Prompt = login

Adding the prompt=login parameter to the authorisation request will attempt to disable Single Sign-On, by instructing the user's Identity Provider to show the login screen and forcing the user re-authenticate. Please note that this greatly impacts the user experience, as users will have to re-enter their credentials at the IdP, even if they very recently already did so. Only use this parameter when it is really necessary. Don't hesitate to ask the SURFconext support team for help if you have doubts whether to apply it or not.

Important: Not all IdPs in SURFconext support this. You should also not rely on this feature as a security feature, since it is possible to disable it during a login request.

Adding claims to the id_token

SURFconext supports the claims request parameter, enabling Relying Parties (RPs) to receive claims directly in the ID token instead of retrieving them from the UserInfo endpoint. An example of a claims request parameter is as follows: 

{
  "userinfo": {
    "given_name": { "essential": true },
    "nickname": null,
    "email": { "essential": true },
    "email_verified": { "essential": true },
    "picture": null,
    "eduperson_scoped_affiliation": null
  },
  "id_token": {
    "auth_time": { "essential": true }
  }
}

Our minimal disclosure policy also applies to claims requested in the ID token. Any claims not essential for your service to function will not be provided. Read more about claims on this page.  

Refresh tokens

If you use OpenID Connect in combination with API security (i.e. you have a resource server) you can use refresh tokens in order to keep the lifetime of the access tokens shorter. Please refer to Refresh Tokens - What are they and when to use them for in depth information on refresh tokens.

Playground

In addition to this page, you can also play around with our playground application. This application allows you to review all features and, for instance, have a closer look at headers and responses with your application.