KNF:OpenID-Connect: verschil tussen versies

Huidige versie van 12 jan 2024 om 09:43

Entree Federatie supports OpenID Connect (OIDC) for Service Providers or Relying Party (RP) in OIDC terminology:

For OIDC, more standard implementations are available that can easily be integrated into an (existing) application; connecting to Entree Federatie therefore is easier as with SAML.
OIDC is a RESTful API-like service; it is less complex than SAML.
In mobile apps OIDC is the defacto standard.

Preparation with OpenID Connect

If you want to use OpenID Connect you will have to make sure your software supports this protocol. Several software products already support OpenID Connect out of the box. If your software is amongst these, you can continue to to the paragraph about Claims and attributes below.

More information: http://openid.net/connect/

We strongly advise you not to build your own OpenID Connect implementation, but use one of the products off the shelf. The official OpenID website provides an overview of certified implementations.

Claims and attributes

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.

For testing purposes you can our Referentie Omgeving (Test IdP's).

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

OpenID Connect or SAML?

When you connect to Entree Federatie you can use OpenID Connect or SAML as a protocol to authenticate a user using Entree Federatie. 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 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. In Entree Federatie, the user authenticates at his Identity Provider (called OpenID Provider in OIDC) - this all happens using SAML. Entree Federatie 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.

Entree Federatie has a data minimisation policy, which means you only receive those claims that are strictly needed to make your service work.

When you connect to Entree Federatie you can use OpenID Connect or SAML as a protocol to authenticate a user using Entree Federatie. 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.

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 list of SAML attributes together with their details and properties can be found on our page about attributes. Those SAML attributes are provided by institutions connected to Entree Federatie as Identity Provider. You can use any of those attributes in your service (Entree Federatie translates them to OpenID Connect claims).

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 Entree Federatie will generate a hashed uid, which is placed 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. Entree Federatie will generate a subject for each user. It is unique for every user.

OpenID Connect features

Connect your Service

First register as a Service Provider for Entree Federatie: https://www.kennisnet.nl/entree-federatie/voor-dienstaanbieders/ After your request is accepted you get an invitation for the Mijn Entree Federatie dashboard.

When you have access to Mijn Entree Federatie:

+ Add new service
Connect with Entree Federation
+ Add test connection
Choose OIDC Client
And fill all fields

.well-known endpoint

Test connection

@@ Regel 1: / Regel 1: @@
-Documentatie in ontwikkeling
+Entree Federatie supports [https://openid.net/connect/faq/ OpenID Connect (OIDC)] for Service Providers or Relying Party (RP) in OIDC terminology:
+* For OIDC, more standard implementations are available that can easily be integrated into an (existing) application; connecting to Entree Federatie therefore is easier as with SAML.
-Dit artikel bevat technische informatie voor een koppeling met OpenID Connect.
+* OIDC is a RESTful API-like service; it is less complex than SAML.
-Meer informatie: http://openid.net/connect/
+* In mobile apps OIDC is the defacto standard.
+==Preparation with OpenID Connect==
-Entree Federatie ondersteunt OpenID Connect (OIDC) voor Service Providers (of Relying Party in OIDC-terminologie). OIDC heeft verschillende voordelen ten opzichte van SAML:
-* Voor OIDC zijn er meer standaard implementaties beschikbaar die eenvoudig te integreren zijn in een (bestaande) applicatie; aansluiten op Entree Federatie wordt daardoor makkelijker
-* OIDC is een RESTful API-achtige service; het is minder complex dan SAML
-* Voor Service Providers die ook mobiele apps gebruiken, kan OIDC als enige technologie worden gebruikt
+If you want to use OpenID Connect you will have to make sure your software supports this protocol. Several software products already support OpenID Connect out of the box. If your software is amongst these, you can continue to to the paragraph about Claims and attributes below.
-Het .well-known endpoint
-https://oidcng.entree.kennisnet.nl/.well-known/openid-configuration
+More information: http://openid.net/connect/
+{{Info|We strongly advise you not to build your own OpenID Connect implementation, but use one of the products off the shelf. [http://openid.net/developers/libraries/ The official OpenID website provides an overview of certified implementations.]}}
+==Claims and attributes==
+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.
+For testing purposes you can our [[KNF:Service provider koppeling testen/en|Referentie Omgeving]] (Test IdP's).
+Alternatively, by using the [https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter claims request parameter] claims are included in the id_token. Entree Federatie also supports this method because some client implementations expect this behaviour.
+=== OpenID Connect or SAML? ===
+When you connect to Entree Federatie you can use OpenID Connect or SAML as a protocol to authenticate a user using Entree Federatie. 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 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'''. In Entree Federatie, the user authenticates at his Identity Provider (called OpenID Provider in OIDC) - this all happens using SAML. Entree Federatie 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.
+{{Info|Entree Federatie has a data minimisation policy, which means you only receive those claims that are strictly needed to make your service work.}}
+When you connect to Entree Federatie you can use OpenID Connect or SAML as a protocol to authenticate a user using Entree Federatie. 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.
+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 list of SAML attributes together with their details and properties can be found on our [https://developers.wiki.kennisnet.nl/index.php?title=KNF:Attributen_overzicht_voor_Service_Providers page about attributes].  Those SAML attributes are provided by institutions connected to Entree Federatie as Identity Provider. You can use any of those attributes in your service (Entree Federatie translates them to OpenID Connect claims).
+===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 Entree Federatie will generate a hashed uid, which is placed 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. Entree Federatie will generate a subject for each user. It is unique for every user.
+==OpenID Connect features==
+[[KNF:OpenID_Connect_features|OpenID Connect features]]
+==Connect your Service==
+First register as a Service Provider for Entree Federatie: https://www.kennisnet.nl/entree-federatie/voor-dienstaanbieders/
+After your request is accepted you get an invitation for the [https://kn.nu/mef Mijn Entree Federatie] dashboard.
+When you have access to Mijn Entree Federatie:
+* + Add new service
+* Connect with Entree Federation
+* + Add test connection
+* Choose OIDC Client
+* And fill all fields
+.well-known endpoint
+* Production: https://oidcng.entree.kennisnet.nl/.well-known/openid-configuration
+* Staging: https://oidcng.entree-s.kennisnet.nl/.well-known/openid-configuration
+==Test connection==
+[[KNF:Service_provider_koppeling_testen/en|Test connection]]