Added doc for general OAuth2 and specific FranceConnect config

docs/authzn.adoc

@@ -155,7 +155,101 @@ georchestra:
 
 == OpenID Connect
 
-=== Configuration
+OAuth2 authentication is enabled by setting `georchestra.gateway.security.oauth2.enabled` to `true`.
+
+=== Provider configuration
+
+Identity providers are declared as shown in [Spring OAuth2 Log In documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/login/core.html). Some providers are natively supported by Spring, resulting in less needed configuration which often summarizes as defining `client-name`, `client-id` and `client-secret`, and `scope` as in the following example :
+[source,yaml]
+----
+spring:
+ security:
+ oauth2:
+ client:
+ registration:
+ google:
+ client-name: <display-name>
+ clientId: <client-id>
+ clientSecret: <client-secret>
+ scope: openid, email, profile
+----
+
+For providers compatibles with OAuth2 or OpenID Connect but not natively supported, this section needs more detail which depends on the provider used, shown in this example but may vary :
+[source,yaml]
+----
+spring:
+ security:
+ oauth2:
+ client:
+ registration:
+ <provider-name>:
+ client-name: <display-name>
+ client-id: <client-id>
+ client-secret: <client-secret>
+ authorization-grant-type: authorization_code
+ redirect-uri: https://<gateway-url>/login/oauth2/code/<provider-name>
+ scope: openid, email, profile
+----
+
+Then an additional section is needed to define entry point URLs. With OpenID Connect, configuration can be automatically loaded using the discovery endpoint if the provider has one, by adding `spring.security.oauth2.provider.<provider-name>.issuer-uri: <configuration-entry-point-url>` (without specifying the `.well-known/openid-configuration` part).
+
+If the provider does not have this endpoint, configuration must be manually defined. An example is provided below, but it may vary according to provider configuration :
+[source,yaml]
+----
+spring:
+ security:
+ oauth2:
+ client:
+ provider:
+ <provider-name>:
+ authorization-uri: <authorization-entry-point-url>
+ token-uri: <token-entry-point-url>
+ user-info-uri: <user-info-entry-point-url>
+ end-session-uri: <end-session-entry-point-url>
+ user-name-attribute: sub
+----
+
+The `authorization-uri`, `token-uri` and `user-info-uri` endpoints are always required, but other parameters shown here may not, and other parameters not shown here may also be required. Please check [Spring documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/login/core.html) about available parameters, and note that `end-session-uri` is not a Spring parameter but an addition that was made to the gateway to add support for logout endpoint.
+
+Identity providers may ask about authorized callback URLs so that they can check which client domain has access to their identification features with given secrets. Here are the callback URLs used by the gateway :
+Login callback : `https://<gateway-url>/login/oauth2/code/franceconnect`
+Logout callback : `https://<gateway-url>/login?logout`
+
+=== FranceConnect provider
+
+FranceConnect is a widely used french identity provider for public administration websites. It is available only to public entities, has some strict technical and ergonomics guidelines, and requires an administrative validation procedure when functionality of the web is fully tested against theses guidelines before providing production secrets. Until this procedure is complete, they provide integration secrets, endpoints, and dummy accounts for testing purpose.
+
+It also requires some specific parameters to be used with the gateway. Here is an example of a working configuration using integration platform (URLs may change) :
+
+[source,yaml]
+----
+spring:
+ security:
+ oauth2:
+ client:
+ registration:
+ <provider-name>:
+ client-name: <display-name>
+ clientId: <client-id>
+ clientSecret: <client-secret>
+ client-authentication-method: post
+ authorization-grant-type: authorization_code
+ redirect-uri: https://<gateway-url>/login/oauth2/code/<provider-name>
+ scope: openid, email, given_name, family_name
+ provider:
+ <provider-name>:
+ authorization-uri: https://fcp.integ01.dev-franceconnect.fr/api/v1/authorize
+ token-uri: https://fcp.integ01.dev-franceconnect.fr/api/v1/token
+ user-info-uri: https://fcp.integ01.dev-franceconnect.fr/api/v1/userinfo
+ end-session-uri: https://fcp.integ01.dev-franceconnect.fr/api/v1/logout
+ user-name-attribute: sub
+----
+
+`end-session-uri` is strictly mandatory because FranceConnect will keep track of active logins and won't allow a new login if the previous one was not logged out properly by a call to this endpoint. If locked when testing, login state can be reset by deleting FranceConnect cookies or by pasting this endpoint URL in the locked browser.
+
+FranceConnect does not support the general `profile` scope, so it is required to specify each necessary OpenID fields one by one, as in the example. It will also show to the user when logging in which scope has been requested.
+
+=== Claims configuration
 
 Both standard and non-standard claims can be used to set the `GeorchestraUser`'s
 `organization` short name and `roles` properties using JSONPath expressions with