Added doc for general OAuth2 and specific FranceConnect config

docs/authzn.adoc

@@ -155,7 +155,103 @@ 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 Cloud Gateway documentation. 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, as in this example :
+[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` are always required, but other parameters may not. Other parameters not shown here may also be required.
+
+Identity providers may ask about authorized callback URLs so that they check that they effectively redirect to the intended gateway after identification. 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 identity provider for french public administration websites. It is available only for 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 parameters.
+
+It also requires some specific parameters to be used with the gateway. Here is an example of needed sections using integration endpoints :
+
+[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