KNF:OpenID Connect features

This page describes all the OpenID Connect (OIDC) features supported by Entree Federatie. 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 lastname, email address or a known identifier. In OpenID Connect (OIDC), this extra information comes in the form of claims, whereas in SAML, claims are called attributes. Entree Federatie can provide these from the user.

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

Supported flows

All OpenID Connect flows (code, implicit and hybrid) are supported by Entree Federatie. 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:

flow	response_type parameter
Authorization Code	code
Implicit	id_token
Implicit	id_token token
Hybrid	code id_token
Hybrid	code token
Hybrid	code id_token token

Proof Key for Code Exchange (PKCE)

PKCE is a security extension for public clients, originally for OAuth2. It mitigates attacks where the authorization code on public clients can be intercepted, such as Mobile or Desktop Apps which use callback URLs. For example, a rogue app can hijack the redirect URL and then obtain the authorisation code. These public clients typically do not have a secret configured when they exchange the code for an access_token at the token endpoint.

PKCE solves this problem as follows. When an authorisation request is made, the RP generates a secret, and for more security, a hash of that secret. Two additional parameters are used:

• code_challenge=XXXXX: The hash of the secret that has been generated
• code_challenge_method=S256: This can be either S256, meaning that the SHA-256 hash of the secret is given, or plain, meaning that the secret itself is transmitted.

The server then ensures the generated code and the supplied code_challenge are stored.

In the request to the token endpoint, the code_verifier is added, which is the secret that has been generated. The OIDC server then checks whether the secret is the same as the one in the original authorisation request. If not, no access_token and id_token are provided. This effectively binds the first authorisation request to the token request.

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 (attributes) you added to the service in Mijn Entree Federatie 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 Entree Federatie support team for help if you have doubts whether to apply it or not.

Important: Not all IdPs in Entree Federatie 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.

Request adding claims to the id_token

Entree Federatie supports the claims request parameter which allows RPs to have the claims in the id_token instead of in the user-info endpoint.

Skip WAYF - select school for authentication

Using the login_hint parameter, the OIDC integration can skip the WAYF screen. OIDC Authentication request with login_hint from the Service Provider to Entree Federatie.

&login_hint=https://mijn-idp

Example:

https://oidcng.entree-s.kennisnet.nl/oidc/authorize?client_id=bestelshop.nl&redirect_uri=https%3A%2F%2Fbestelshop.nl&response_type=code&grant_types=%5B%22implicit%22%5D&scopes=%5B%22openid%22,%22profile%22,%22email%22%5D&login_hint=https%3A%2F%2Fmijn-idp

You can find connected schools and IdP's here