With OIDC protocol, relying party (tenant) and OIDC Provider (EIDG) have shared a configuration that allows parties to communicate and share information. This configuration is composed by:

Client Id (provided by EIDG to tenant)
Client Secret (provided by EIDG to tenant)
Redirect URIs (provided by tenant to EIDG)
List of required authentication schemas and their configurations

Client Id and secrets are parameter to identify tenant and avoid uncontrolled accesses. Redirect URIs is list of tenant application URIs that are allowed to receive callback from OIDC Provider. Before using EIDG tenant has agreed about which authentication schemas is interested to use and with their specific configurations. For example in case tenant is interested to SPID authentication schema, it must provide list of SPID attributes it is interested to and also SPID livel (level 1 or level2) this complete configuration will be stored EIDG implements authorization code flow to start OIDC authentication session, with this authentication flow user is redirected from tenant application to OIDC provider frontend, and there user provides his credentials, when login succeeds user is redirected from OIDC Provider to tenant application and then authentication flow is correctly closed. With this integration method user does not provide his credentials outside OIDC Provider environment, tenant application and OIDC provider are separated environment.

User Interface customization

EIDG User interface can be configured for each Client Id with:

header
footer
Background color

Header can be an image, accepted formats are: png, jpg, svg; CSS rule is backgroud-size: cover and high is 180 pixels. Suggested size is: 4000x 180 pixels. Footer can be an image, accepted formats are: png, jpg, svg; CSS rule is backgroud-size: cover and high is 100 pixels. Suggested size is: 4000x 100 pixels. Background color can be any RGB color, note font color can’t be changed.

API details

Authorization code flow

The authorisation process on EIDG is initiated by redirecting the user to the following endpoint: <url_servizio>/authorize?client_id=<client_id>&state=<state>&redirect_uri=<redirect_uri>&acr_values=<acr_values>&response_type=<response_type>&scope=<scope>&ui_locales=<ui_locales>&code_challenge_method=<code_challenge_method>&code_challenge<code_challenge> The parameters in this URL are:

<url_servizio> URL at which EIDG is published, different depending on the environment to be targeted (TESTING https://eid-gatewaycl.infocert.it/oauth2 PRODUCTION https://eid-gateway.infocert.it/oauth2)
<client_id>: Client ID provided by EIDG during enrolment.
<state>: String for use by the client application, useful for saving a session ID or status before the authorisation flow is started. EIDG will return it as it is at the end of the process.
<redirect_uri>: Absolute URL that EIDG must redirect to at the end of the authentication process. This redirection occurs regardless of the outcome of the user authentication. This URL must match the one provided during enrollment.
<acr_values>: A space-separated list of method codes among the ones provided in the enrollment phase. It is possible to send methods pertaining to different channel (e.g. infocert:identification:method:SPID_LEVEL_2 infocert:identification:method:CIE ) while any request with multiple same-channel methods will be rejected (e.g. infocert:identification:method:SPID_LEVEL_1 infocert:identification:method: SPID_LEVEL_2 ).
<response_type>: Must be set to code
<scope>: Must be set to openid
<ui_locales>: Indicates a preferred language for EIDG’s user interface and any potential error descriptions. Must be set with the ISO two-letter code (e.g. it for Italian, en for English)
<code_challenge_method>: Optional but highly recommended. Verification method of the client according to the PKCE for OAuth2 Must be set to S256
<code_challenge>: Optional but highly recommended. Verification string of the client in SHA256 hash format according to the PKCE for OAuth2

The EIDG authorisation process is based on the OAuth2 protocol and involves a series of steps to authorise the client so that the requested user information can be retrieved. The various steps that make up a complete authorisation flow are detailed below. All endpoints listed are to be considered relative to the main URL of the service indicated as <url_servizio>.

STEP 1 – initial endpoint

Endpoint: /authorize Method: GET (redirect from client application) This is the first endpoint of the authorisation flow. See the previous section for the parameters to be appended to the address. By redirecting the user to this endpoint, they will be taken to the EIDG front end, where they will be able to select the desired authentication method as well as the provider, if any, from those associated with the requested <acr_values>.

STEP 2 – Authentication of the user by the identity provider

At this point, the user will have to authenticate using the credentials of the chosen service and complete any credential verification steps, such as providing an OTP token or confirming the operation via app. Once authentication is complete, regardless of the outcome, the Identity Provider (hereafter IDP) redirects the user to EIDG, which processes the response received and redirects the user to the callback URL of the client application.

STEP 3 – client callback

At this point, EIDG redirects the user to the client application. Depending on the outcome of the authentication, the composition of the URL is slightly different. Method: GET (redirect da EIDG) Endpoint:

<redirect_uri>?code=<authrorization_code>&state=<state> (authentication successful)
<redirect_uri>?error=<oauth_error>&errorCode=<eidg_error>&errorDescription=<error_description>&state=<state> (authentication failed)

The parameters of the URLs are as follows:

<redirect_uri> Absolute URL of the endpoint on the client application indicated in step 1, which EIDG must redirect to at the end of the authentication process. This redirection occurs regardless of the outcome of the user authentication.
<authorization_code> Code to be used in the next call to obtain access and refresh tokens.
<state> String of the client application indicated in step 1.
<oauth_error> Summary error code according to OAuth and OIDC
<eidg_error> Error code produced by EIDG identifying the specific problem encountered. See Error Handling chapter below.
<error_description> Description of the error. If available, the translated string according ti the requested starting localization will be provided, or Italian otherwise.

STEP 4 – Requesting access/refresh token

Endpoint: /token Method: POST Authentication: Basic base64(<client_id>:<client_secret>) (client_id and client_secret provided during enrolment) Content-type: application/x-www-form-urlencoded Parameters:

code Authorisation code returned by EIDG in the previous redirect.
grant_type Type of grant to be requested. In this case, pass “authorization_code”.
code_verifier Mandatory if PKCE was adopted during the /authorize call. Client verification string in plain format, accordin to the PKCE for OAuth2
redirect_uri Redirect URI provided during enrolment. This stage serves to validate the origin of the request.

With this endpoint, the authorisation code is exchanged for the first access and refresh tokens. Unless otherwise required, the access token is valid for 3 minutes, while the refresh token is valid for 24 hours. In the event of a successfully created token, a status code of 201 (Created) is returned and a JSON response consisting of the two tokens, the type of authentication to be used (always Bearer for now) and the expiration of the access token in seconds.

{
    "idToken": "eyJ....fg",
    "accessToken": "eyj....fg",
    "refreshToken": "eyJ....pb",
    "expiresIn": 360,
    "tokenType": "Bearer"
}

In the event of an error during token creation, EIDG will respond with the status code appropriate to the type of problem (e.g. 400, 403, 500) and a JSON response as follows:

{
    "error": "access_denied",
    "errorCode": "EIDG_5",
    "errorDescription": "Invalid client_id or client_secret"
}

For the error list, see the Error Handling chapter.

STEP 5 – User info retrivial

Endpoint: /user-info Method: GET Authentication: Bearer <access_token> (access_token obtained in the previous step) With this endpoint, the data of the authenticated user can be retrieved. EDIG will return a JSON that always has the same attributes. Depending on the dataset agreed to with the client, the respective attributes in the response will be valued, while the rest will be null. In the event of a successful call, EIDG will return a JSON with the user’s data, an excerpt of which is reproduced below. For a more detailed description of the complete data model, see the Data Model chapter.

{
    "version": "1.0",
    "givenName": "Ada",
    "familyName": "Lovelace",
    "birthPlace":
        {
            "address": 
                {
                    "streetAddress": "null",
                    "postalCode": "null",
                    "addressRegion": "PI",
                    "addressLocality": "PISA",
                    "addressCountry": "IT"
                }
            }
    "birthDate": "1985-12-10",
    "gender": "F",
    "taxID": "LVLDAA85T50G702B",
    "....": "....",
    "errorDescription": "Invalid client_id or client_secret"
}

In the event of an error during token creation, EIDG will respond with the status code appropriate to the type of problem (e.g. 400, 403, 500) and a JSON response as follows:

{
    "error": "access_denied",
    "errorCode": "EIDG_5",
    "errorDescription": "Invalid client_id or client_secret"
}

For the error list, see the Error Handling section.

STEP 6 – Request for new access token (optional)

Endpoint: /token Method: POST Authentication: Basic base64(<client_id>:<client_secret>) (client_id and client_secret provided during enrolment) Content-type: application/x-www-form-urlencoded Parameters:

grant_type Type of grant to be requested. In this case, pass “refresh_token”.
refresh_token Refresh token obtained with the first call to /token

With this endpoint, a new access token is provided if the one available has expired. In the event of a successfully created token, a status code of 201 (Created) is returned and a JSON response consisting of the two tokens, the type of authentication to be used (always Bearer for now) and the expiration of the access token in seconds.

{
    "idToken": "eyJ....fg",
    "accessToken": "eyj....fg",
    "refreshToken": "eyJ....pb",
    "expiresIn": 360,
    "tokenType": "Bearer"
}

In the event of an error during token creation, EIDG will respond with the status code appropriate to the type of problem (e.g. 400, 403, 500) and a JSON response as follows:

{
    "error": "access_denied",
    "errorCode": "EIDG_5",
    "errorDescription": "Invalid client_id or client_secret"
}

For the error list, see the Error Handling chapter.

STEP 7 – token revoke

Endpoint: /revoke Method: POST Authentication: Bearer <token_to_revoke> With this endpoint, an access or refresh token can be revoked to prevent further access to the user information associated with it. If an access token is passed, only this will be revoked. If a refresh token is passed, the corresponding access token will also be revoked and a new end-user authentication will be necessary in order to retrieve his personal data again.

Use Cases

Tenant wants to use SPID authentication

Tenant will sign a contract with InfoCert as “SPID soggetto aggregato” and must provide:

Redirect URIs
List of admitted origins for cors policy
List of desided SPID attributes
Desired SPID level

InfoCert must provide:

Client Id
Client Secret
List of identification methods
EIDG base url

With following info InfoCert will prepare a specific metadata for tenant and will communicate that metadata to AGID. After AGID checks metatada will be sent (byAGID) to all SPID IDPs to make it available. Tenant will start OIDC authorization code flow passing identification method(s) as arc values so EIDG will present proper User Interface. After user authenticated tenant application will call userInfo to get userInfo attributes.

Tenant wants to use CIE authentication

Tenant has already become “CIE Service Provider” and must provide:

Redirect URIs
List of admitted origins for cors policy
CIE Metadata that refers to EIDG CIE callback
its private key to sign requests

InfoCert must provide:

Client Id
Client Secret
List of identification methods
EIDG base url

With following info InfoCert will configure tenant metadata and key. Tenant will start OIDC authorization code flow passing identification method(s) as arc values so EIDG will present proper User Interface. After user authenticated tenant application will call userInfo to get userInfo attributes.

Tenant wants to use FranceConnect authentication

Tenant must provide:

Redirect URIs
Desired FranceConnect level (FranceConnect or FranceConnectPlus)

InfoCert must provide:

Client Id
Client Secret
List of identification methods
EIDG base url

Tenant will start OIDC authorization code flow passing identification method(s) as arc values so EIDG will present proper User Interface. After user authenticated tenant application will call userInfo to get userInfo attributes.

API Reference

User info model

The fields that make up the user data model are detailed below.

Attribute	strong>Parent attribute	Example	Description
version		1.0	Data model version. There will be versions of this model to facilitate backward compatibility
givenName		Marisa	Subject’s name
familyName		Italy	Subject’s surname
birthPlace			Birthplace attributes
address	birthPlace		Birthplace address. Not to be confused with the address attribute below
streetAddress	BirthPlace.address		Not used
postalCode	BirthPlace.address		Not used
addressRegion	BirthPlace.address	RM	Birthplace province (only for those born in Italy)
addressLocality	BirthPlace.address	ROME	Birthplace municipality (only for those born in Italy)
addressCountry	BirthPlace.address	IT	Birthplace country code according to the ISO 3166 alpha-2 standard
birthDate		1930-01-01	Date of birth yyyy-mm-dd
gender		F	Subject’s gender
taxID		TLIMRS30A41H501K	Tax code (for individuals)
vatID		IT12345678901	VAT number or equivalent (for companies)
telephone		+393330000100	Phone number
email		marisa.italia.cl@mailsac.com	Email
digitalAddress		marisa.italia.cl@pecmail.com	PEC certified email
address			Residence address. Not to be confused with the birthPlace.address attribute above
streetAddress	address	Via Delle Robe 20	Residence address (street, square, etc.)
postalCode	address	10156	Residence postcode
addressRegion	address	TO	Residence province
addressLocality	address	Turin	Residence municipality
addressCountry	address	IT	Residence country ISO 3166 alpha-2 standard
electronicId			Digital identity attributes
name	electronicId	SPID	Digital identity type
country	electronicId	IT	Country of issue
id	electronicId	INFC0000012739	Unique ID of the provider relating to the subject.
expirationDate	electronicId	2024-08-24	Identity expiry
physicalId			Attributes relating to the physical identification document
name	physicalId	ID card	Document type
documentNumber	physicalId	AV0639329	Document ID
issuer	physicalId	MunicipalityPianoro	Document issuing body
issuerDate	physicalId	2014-03-21	Issue date
expirationDate	physicalId	2024-08-22	Expiry
_idp		https://identity.infocert.it	Identity provider used to retrieve the dataset
_rawRequest			Base64 of the body of the request to the IDP
_rawResponse			Base64 of the body of the IDP’s response

Error handling

List of error codes

Below is an up-to-date list of error codes handled by EIDG and any recommended actions.

errorCode	error	Error type	Resolution owner	Cause of error	Suggested operation
SPID_19	access_denied	ErrorCode SPID	End user	Authentication failed due to repeated submission of incorrect credentials	Show the error to the end user asking them to try again
SPID_20	access_denied	ErrorCode SPID	End user	User without credentials compatible with the level required by the service provider	Show the error to the end user asking them to try again
SPID_21 or CIE_21	access_denied	ErrorCode SPID/CIE	End user	Timeout during user authentication	Show the error to the end user asking them to try again
SPID_22 or CIE_22	access_denied	ErrorCode SPID/CIE	End user	Consent to submit data was denied by the user	Show the error to the end user asking them to try again
SPID_23 or CIE_23	access_denied	ErrorCode SPID/CIE	End user	User with suspended/revoked identity or blocked credentials	Show the error to the end user asking them to try again
SPID_25 or CIE_25	access_denied	ErrorCode SPID/CIE	End user	Authentication process cancelled by the user	Show the error to the end user asking them to try again
SPID_OTHER_CODE or CIE_OTHER_CODE	server_error	ErrorCode SPID/CIE (other)	EIDG (IDP)	Incorrect response format – Contact Identity manager	Show the end user a generic error. Contact EIDG to analyse the problem.
SPID_TECHNICAL or CIE_TECHNICAL	server_error	Server error	EIDG	An error occurred during the authentication process. Please try again.	Show the end user a generic error. Contact EIDG to analyse the problem.
SPID_VALIDATION or CIE_VALIDATION	server_error	SAML validation error	EIDG (IDP)	Incorrect response format – Contact Identity manager	Show the end user a generic error. Contact EIDG to analyse the problem.
SPID_PARSING or CIE_PARSING	server_error	SAML parsing error	EIDG (IDP)	Incorrect response format – Contact Identity manager	Show the end user a generic error. Contact EIDG to analyse the problem.
EIDG_1	invalid_request	Error in the parameters	Client application	No client_id provided	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_2	invalid_request	Error in the parameters	Client application	The client_id provided is not valid	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_3	invalid_request	Error in the parameters	Client application	The redirect URL does not match the one agreed to	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_4	invalid_request	Error in the parameters	Client application	The requested identification_method is not valid or not available for this client	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_5	access_denied	Error in the parameters	Client application	The client_id or client_secret is not valid	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_6	access_denied	Error in the parameters	Client application	The client_secret provided is not valid	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_7	access_denied	Error in the parameters	Client application	No grant_type provided	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_8	access_denied	Error in the parameters	Client application	The grant_type provided is not valid	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_9	invalid_request	Error in the parameters	Client application	Error during request validation	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_10	access_denied	Server error	EIDG	Error during token generation	Show the end user a generic error. Contact EIDG to analyse the problem.
EIDG_11	server_error	Server error	EIDG	Error communicating with LegalDoc	Show the end user a generic error. Contact EIDG to analyse the problem.
EIDG_12	server_error	Request missing	Client application	Request config not found	Request expired. Invite the user to log in again with EIDG.
EIDG_13	server_error	Request missing	EIDG	Error while retrieving request config	Show the end user a generic error. Contact EIDG to analyse the problem.
EIDG_14	access_denied	Error in the parameters	Client application	Access or refresh token not found	Request expired. If the token in question is access then refresh the new token, otherwise invite the user to log in again with EIDG.
EIDG_15	invalid_request	Error in the parameters	Client application	Access or refresh token not valid	Show the end user a generic error. Check the correctness of the call to EIDG.
EIDG_16	server_error	Server error	EIDG	Error while parsing access or refresh token	Show the end user a generic error. Contact EIDG to analyse the problem.

Integration methodologies

User Interface customization

API details

Authorization code flow

STEP 1 – initial endpoint

STEP 2 – Authentication of the user by the identity provider

STEP 3 – client callback

STEP 4 – Requesting access/refresh token

STEP 5 – User info retrivial

STEP 6 – Request for new access token (optional)

STEP 7 – token revoke

Use Cases

Tenant wants to use SPID authentication

Tenant wants to use CIE authentication

Tenant wants to use FranceConnect authentication

API Reference

User info model

Error handling

List of error codes

Scenario of usage

Use refresh token to get new valid access code

Logout particular user -> Delete access and refresh tokens

UI Customization

Rules applied to the web page

Header

Footer

Body

EID Gateway

Fill the form to request information