# Base concepts
## OpenID Connect protocol
### Introduction

The OpenID protocol is at the heart of FranceConnect's operating system. It is an identification layer based on the OAuth 2.0 protocol. It allows Clients (in this case, the Service Providers) to access the identity of the final Users (web users) through a server authorization (here, the Identity Providers).

The protocol specification can be found at http://openid.net/connect/.

Here is the link to an OpenID Connect implementation reference: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth

### Standard flux

The OpenID Connect protocol defines 3 REST calls done by the client, and 4 endpoints (one client side, and 3 provider side).

Upstream, the client registers (usually manually) with the provider. The client provides a callback URL (the client URL the web user will be redirected to after authentication), also called "callback endpoint". In return, the provider gives the client a client ID and a client secret.

When the web user clicks on the client's authentication button, the flux is as follows:

1. The client does a redirection towards the provider's "authorization endpoint" with its client id and callback url. The provider then redirects the web user to its authentication process. If the web user logs in properly, the provider returns an authorization code to the client.
2. The client makes a Web service call to the provider's "token endpoint" with the authorization code received, and authenticates this request with its client ID and client secret. The provider returns an access token (as a base64 encoded string), an id token (as a Json Web Token), and sometimes a refresh token (as a base64 encoded string).
3. The client makes a Web service call to the provider's "userInfo endpoint" with the received access token, and the provider returns the web user's information to the client.

### In FranceConnect's case

The Service Providers' registering with FranceConnect is done by applying for a demand on the website [datapass.api.gouv.fr](https://datapass.api.gouv.fr/).

FranceConnect implements the OpenID Connect flux [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).

The service providers must be OpenID Connect clients, and the identity providers must be OpenID Connect providers. FranceConnect is an intermediary brick that is both provider (from Service Providers point of view) and client (from Identity Providers point of view).

### Encryption and signature of exchanges

All JWT token exchanges between FranceConnect and the Service Provider are signed and encrypted using the following algorithms:

**Signing of tokens by the Identity Provider** :

- Asymmetrical: 

       - ES256 (EC + SHA256)

**Token encryption (jwe+jws)** :

- Hybrid:

      - RSA-OEAP + AES256-GCM 
      - ECDH-ES + AES256-GCM

The sign and encryption algorithms specifications are as follows :

* [JWA - https://tools.ietf.org/html/rfc7518](https://tools.ietf.org/html/rfc7518)
* [JWS - https://tools.ietf.org/html/rfc7515#appendix-A.3](https://tools.ietf.org/html/rfc7515#appendix-A.3)
* [JWE - https://tools.ietf.org/html/rfc7516#appendix-A.1](https://tools.ietf.org/html/rfc7516#appendix-A.1)

The FranceConnect sign public keys are available via the *JWKS URL* found in the *Discovery URL* meta-data at the following addresses, and are regularly changed :

| Environment    | endpoint adresses    |
|----------------|----------------------|
| FC integration | https://auth.integ01.dev-franceconnect.fr/api/v2/jwks |
| FC production  | https://auth.franceconnect.gouv.fr/api/v2/jwks |

The signature public keys used by the Identity provider must be available via the *JWKS URL* found in the *Discovery URL* meta-data.

## User data

User data is provided by Identity Providers to Service Providers, via FranceConnect, in accordance with the authorization obtained via [datapass.api.gouv.fr](https://datapass.api.gouv.fr), and the data choice made by the Service Provider in this request.

The pivot identity allows to identify a particular user.

* Birth name
* First name
* Gender
* Date of birth
* [Geographic INSEE code of the city of birth](https://www.insee.fr/fr/information/5057840)
* [Geographic INSEE code of the country of birth](https://www.insee.fr/fr/information/5057840)

In addition, it is possible to obtain the usage name. However, this information is not necessarily known by all Identity Providers.

You may also have access to the email address. This contact data has also been verified by the Identity Provider. Please note that the "email address" data may differ depending on the Identity Provider chosen by the user.

FranceConnect systematically sends the Service Provider a unique identifier for each user:

* This identifier is specific to each Service Provider. A single user will have a different unique ID for each Service Provider he accesses.

* This ID is the same no matter which Identity Provider is used by the user.

Please note that for eIDAS 2 and 3 levels (substantial and high), the identity data provided to the Service Provider are those directly from the Identity Provider chosen by the user, without RNIPP adjustment (INSEE). This data may therefore vary slightly from one Identity Provider to another, so we recommend performing the adjustment based on the user's unique identifier provided by FranceConnect.


* This ID is the same no matter which Identity Provider is used by the user.

### List of scopes available during the FranceConnect authentication step

FranceConnect has extended the scopes mechanism to be more modular.

* Only one scope is mandatory: openid. It is used to retrieve the user's sub (technical unique identifier).
* It is possible to retrieve each property of the pivot identity individually using their dedicated scopes.
* It is possible to combine several scopes of your choice to retrieve only the information needed by the Service Provider.


| Field        | Type   | Description | Format |
|--------------|--------|-------------|--------|
| given_name   | string | first names separated by spaces (OpenIDConnect standard) | [A-Za-zÀÂÄÇÉÊËÎÏÔÖÛÜŸàâäçéèêëîïôöùûüÿÆŒæœ -'] |
| family_name  | string | birth surname (OpenIDConnect standard) | [A-ZÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸÆŒ \-']|
| birthdate    | string | date of birth in YYYY-MM-DD format (OpenIDConnect standard) | [ YYYY-01-01 ] - (\d{4})-01-01 - (Presumed months) [ YYYY-MM-01 ] - (\d{4})-(\d{2})-01 - (Presumed days) [ YYYY-MM-DD ] - (\d{4})-(\d{2}) |
| gender       | string | male for males, female for females (OpenIDConnect standard) | Male : M (male) Female : F (female) |  
| birthplace   | string | the 5-digit INSEE code of the place of birth (or an empty string if the person was born abroad) | If born in France (Size of 5) [([0-8][0-9AB])|(9[0-8AB])[0-9]{3}] - [Details] - [List] In case of foreign country : Empty field | 
| birthcountry | string | the INSEE code of the country of birth on 5 digits | For foreign countries (Size of 5 ) [99[0-9]{3}] - [Details] For France 99100 |



### Additional data

| Field        | Type   | Description | Format |
|--------------|--------|-------------|--------|
| sub          | string | technical identifier (OpenIDConnect standard) | 66 hex characters + letter 'v' |
| email        | string | contact email address of the person (OpenIDConnect standard) | RFC 5322 |
| preferred_username | string | user name (OpenIDConnect standard) | [A-ZÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸÆŒ \-'] |



### "aliases"

**profile:** Groups the given_name, family_name, birthdate and gender scopes. If available, also returns preferred_username.

**birth :** Combines the scopes birthplace and birthcountry. Allows you to retrieve the city and county of birth of the person.

**pivot_identity:** Combines the profile and birth scopes. Allows you to retrieve the complete pivot identity plus the custom name if available.

This list of scopes is defined by the OpenIDConnect standard : http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims