From 948181253cfe0f64fdd752e90b34e2ae79c65cae Mon Sep 17 00:00:00 2001 From: Federica Agostini Date: Thu, 27 Jun 2024 12:02:26 +0200 Subject: [PATCH] improve documentation on how to fill account creation form from external IdP (#113) Co-authored-by: Michel Jouvin --- .../external-authentication/oidc/_index.md | 5 ++ .../external-authentication/saml/_index.md | 7 ++ .../configuration/registration/_index.md | 67 +++++++++++++++---- 3 files changed, 67 insertions(+), 12 deletions(-) diff --git a/content/en/docs/reference/configuration/external-authentication/oidc/_index.md b/content/en/docs/reference/configuration/external-authentication/oidc/_index.md index 0a25e19..a307703 100644 --- a/content/en/docs/reference/configuration/external-authentication/oidc/_index.md +++ b/content/en/docs/reference/configuration/external-authentication/oidc/_index.md @@ -119,6 +119,11 @@ provider. See the [configuration reference][conf-ref] for instructions on how to override the default IAM configuration. +## Registration form: filling information from IdP + +See [registration configuration][external-idp-config] + +[external-idp-config]: {{< ref "/docs/reference/configuration/registration/#registration-with-external-idp" >}} [google-oidc]: https://developers.google.com/identity/protocols/OpenIDConnect [oidc-discovery-url]: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig [conf-ref]: {{< ref "/docs/reference/configuration/#overriding-default-configuration-templates" >}} diff --git a/content/en/docs/reference/configuration/external-authentication/saml/_index.md b/content/en/docs/reference/configuration/external-authentication/saml/_index.md index b9fc12e..960efab 100644 --- a/content/en/docs/reference/configuration/external-authentication/saml/_index.md +++ b/content/en/docs/reference/configuration/external-authentication/saml/_index.md @@ -255,3 +255,10 @@ instructions on how to override the default IAM configuration. [edugain]: https://edugain.org/ [application-saml]: https://raw.githubusercontent.com/indigo-iam/iam/{{< param version >}}/iam-login-service/src/main/resources/application-saml.yml + +## Registration form: filling information from IdP + +See [registration configuration][external-idp-config] + +[external-idp-config]: {{< ref "/docs/reference/configuration/registration/#registration-with-external-idp" >}} + diff --git a/content/en/docs/reference/configuration/registration/_index.md b/content/en/docs/reference/configuration/registration/_index.md index 00cbfc1..ea4c3da 100644 --- a/content/en/docs/reference/configuration/registration/_index.md +++ b/content/en/docs/reference/configuration/registration/_index.md @@ -9,15 +9,37 @@ IAM implements a basic registration service that implements an administrator-vetted registration flow, where users apply for membership in an organization and administrators are asked to validate membership requests. -## Requiring external authentication +## Registration with external IdP -Starting with version 1.6.0, IAM allows to request that users are authenticated -from a trusted identity provider (SAML or OIDC) in order to apply for -membership. It's also possible to control how information in authentication -tokens and assertions is mapped to IAM registration fields. +When an external OIDC or SAML IdP is used to authenticate users, IAM allows to configure: -For example, see the following fragment that requires authentication with the -CERN SSO and defines how information from identity tokens issued by CERN SSO is +- Whether users are required to authenticate through an external IdP and optionally + which ones +- Which information must be retrieved from the IdP to fill the account creation form + +This is done by creating a YAML file in `/indigo-iam/config`, for example +`/indigo-iam/config/application-registration.yaml`. When deploying IAM with a container, +a volume providing this file must be mapped into the container. + +The contents in this file must be under the following hierarchy: + +```yaml + +iam: + registration: +``` + + +### Requiring external authentication + +To require that users must authenticate through an external IdP, you need to define the +parameter `require-external-authentication`. You can also specify the type of external +IdP required (`oidc` or `saml`) and require one specific issuer. + +The following fragment requires authentication with the +(OIDC-based) CERN SSO. + +and defines how information from identity tokens issued by CERN SSO is mapped to IAM membership information ```yaml @@ -27,21 +49,42 @@ iam: require-external-authentication: true oidc-issuer: https://auth.cern.ch/auth/realms/cern authentication-type: oidc +``` + +### Filling information from IdP + +The first time a user authenticates in IAM instance, the account creation form will be displayed. It is possible to request +that some of the fields are filled with the value of an IdP attribute and to define that some of these fields are read-only, +i.e. that the value provided by the IdP cannot be changed. + +To enable filling the creation form with values provided by the IdP, you need to create a YAML file in `/indigo-iam/config`, for example +`/indigo-iam/config/application-registration.yaml`. The contents should be something similar to: + + +```yaml +iam: + registration: fields: + email: + read-only: false + external-auth-attribute: email name: - read-only: true # When false, allows user to override what comes from the authentication information + read-only: false external-auth-attribute: given_name surname: - read-only: true - external-auth-attribute: family_name - email: read-only: false - external-auth-attribute: email + external-auth-attribute: family_name username: read-only: false external-auth-attribute: preferred_username ``` +`read-only` can be set to `true` if you want to prevent that the value provided supplied by the ID is modified by the user. +**Note that if a field is defined as read-only and now value is provided +by the IdP, it may result that the user cannot submit the account creation form if the field is required.** + +`external-auth-attribue` must be the name of the IdP attribute to use for the mentioned account creation form field. + ## User editable fields Starting with version 1.6.0, IAM allows to limit which fields of the user profile are editable by users.