README.en.md

keycloak-franceconnect

• keycloak-franceconnect
  • Features
  • Compatibility
  • Migration
  • Installation
  • How to use it
    • Requirements
    • Configuration
      • Mappers
      • Theme
  • Q&A
  • How to contribute

This Keycloak plugin adds an identity provider allowing to use France Connect services.

Features

• Signature verification (based on client-secret)
• User account warranty level (eIDAS) required on authorization request (cf communication FranceConnect)
• Login themes with FranceConnect buttons (fc-theme and iron-theme)
• Better management for logout (https://issues.jboss.org/browse/KEYCLOAK-7209)

Compatibility

• The version 6.2.0 of this plugin is compatible with Keycloak 24.0.0 and higher. It's configurable with UI.
• The version 6.1.0 of this plugin is compatible with Keycloak 22.0.0 and higher. (not configurable with UI)
• The version 5.0.0 of this plugin is compatible with Keycloak 21.x.y. (not configurable with UI)
• The version 4.0.0 of this plugin is compatible with Keycloak 15.0.0 until 20.0.0. (not configurable with UI starting keycloak 19)
• The version 2.1 up to 3.0.0 of this plugin is compatible with Keycloak 9.0.2 until 15.0.0.
• The version 2.0 of this plugin is compatible with Keycloak 8.0.1 until 9.0.2.

Migration

If you are already using an older version of the plugin, it's better to delete your configuration to avoid any conflict.

• 2.x/3.x -> 4.x : Delete your identity provider configuration so that the plugin can automatically generate the mappers when saving the configuration and that there are no conflict.
• 1.x -> 2.x: Check that your identity provider still exists and that the selected France Connect environment is good
• 1.x -> 1.4: You will need to configure the new eIDAS level in the configuration

Installation

The plugin installation is simple and can be done without a Keycloak server restart.

• Download the latest release from the releases page
• Copy the JAR file into the standalone/deployments directory in your Keycloak server's root
• Restart Keycloak (optional, hot deployment should work)

You can also clone the Github Repository and install the plugin locally with the following command:

$ mvn clean install wildfly:deploy

How to use it

Requirements

You must have a France Connect account to retrieve plugin configuration information (clientId, clientSecret, authorized redirect uri, ...)

There are 2 environments, Integration and Production. The request for an Integration account is made by email to the France Connect support team.

France Connect account can be managed at https://partenaires.franceconnect.gouv.fr

Configuration

Once the installation is complete, the France Connect Particulier identity provider appears. Once selected, you can see the following configuration page:

Choose the France Connect environment, enter your clientId, clientSecret, requested scopes, the eIDAS authentication level.
The configured alias (france-connect-particulier) is used by fc-theme and iron-theme themes. You can rename this alias if you don't use one of theses themes.

You will also find the redirect uri you will need to enter on the France Connect partner portal:

• endpoint: https://<keycloak-url>/auth/realms/<realm>/broker/franceconnect-particulier/endpoint
• logout: https://<keycloak-url>/auth/realms/<realm>/broker/franceconnect-particulier/endpoint/logout_response

Mappers

Once the configuration validated, you can add the mappers needed to retrieve the attributes you want from claims provided by France Connect. The main mappers are automatically added when creating the identity provider.

Mappers examples:

• Name : lastName, Mapper Type : Attribute Importer, Claim : family_name, User Attribute Name : lastName
• Name : firstName, Mapper Type : Attribute Importer, Claim : given_name, User Attribute Name : firstName
• Name : email, Mapper Type : Attribute Importer, Claim : email, User Attribute Name : email

Theme

This plugin provides 1 theme:

• fc-ac-theme

Choose your theme and go to the following url: https://<keycloak-url>/auth/realms/<realm>/account

Q&A

See Q&A

How to contribute

See here