Skip to Content
DocsIdentity Provider ProxySPID

SPID - saml2

Introduction

In this guide, we will see how to create a login for a service using SPID.

Configuration

Precondition: The public domain IP MUST be from Italy as the Ministry of the Intern restricts logins for Italy only.

What to do:

  1. Add a rewrite rule on the service you want to protect with the “Enter with SPID” identification scheme;
  2. Change the variables of the rule as described in Rewrite rule;
  3. Verify proper operation by setting the ENVIRONMENT_n = demo-online variable described in Testing the configuration.

Rewrite rule

To allow the domain to expose the Entity Configuration, we must first apply the header rewrite rule called SPID-IDP-Simple on the domain we intend to protect.

Identity provider parameters where n is a non-zero natural number:

  • ISSUER_n: string must be valued with SPID;
  • CLIENT_ID_n: string must be valued with an HTTPS URL that uniquely identifies the RP;
  • AUTHENTICATION_PROTOCOL_n: string must be valued with saml2;
  • BUTTON_TEXT_n: string must be valorized with Continue with SPID;
  • BUTTON_FILLED_n: boolean must be valued at true;
  • BUTTON_IMAGE_BASE64_n: string must be valorized with the value of the SPID logo in base64.
  • SPID_PRIVATE_KEY: string private key in pem format used to sign the metadata Certificate Generation;
  • SPID_PUBLIC_KEY: string public key in pem format used to sign the metadata Certificate Generation;
  • SPID_CERTIFICATE: string certificate in pem format used to sign the metadata Certificate Generation;
  • SAML_SIGNED_ASSERTION_n: boolean must be true;
  • SAML_BINDING_n: string must be HTTP-POST;
  • SERVICE_NAME_n: string service name;
  • ORGANIZATION_NAME_n: string Name - complete and in full and with the correct use of lower case, uppercase, accented letters and other diacritical marks - of the SP, as given in the organizationName extension of the SP’s electronic certificate (example: “Agenzia per l’Italia Digitale”);
  • ORGANIZATION_DISPLAY_NAME_n: string Name of the SP, possibly in abbreviated form (without making any acronyms explicit) with the correct use of lower and upper case letters (example: “AgID”). During the authentication phase, IdPs alert the user to the submission of attributes to the SP, displaying the value of this tag to indicate the requesting party;
  • ORGANIZATION_URL_n: string Contains the ‘url of a page on the SP’s Website related to the authentication service or services accessible through it;
  • EMAIL_ADDRESS_n: string (1 occurrence, mandatory) - Contains the e-mail address, corporate or institutional, to contact the entity for electronic billing issues. This can be a corporate certified electronic mail (pec) address, but it does not have to be a personal e-mail box;
  • ENVIRONMENT_n: string A DEMO IDP will always exist (in addition to the official IDPs) in the list of IDPs in the “Log in with SPID” button, except when you value the variable to prod. Allowed values are:
    • validator-offline allows configuration verification on the local demo IDP (AgID validator  must be installed on the machine);
    • demo-offline allows testing of the configuration on the local demo IDP (must have the validator  AgID installed in the machine);
    • demo-online phase of testing the configuration on the AgID demo IDP;
    • validator-online phase in which SPID membership is requested;
    • prod phase following confirmation of SPID membership.

If you are a PUBLIC entity, you need to add:

  • PRIVATE_n: boolean set to false;
  • IPA_CODE_n: string is valued with the entity’s ipa code.

If you are a PRIVATE entity, you must add the following billing parameters:

  • PRIVATE_n: boolean set to true;
  • VAT_NUMBER_n: string mandatory for private SP with vat number (otherwise optional), it is valued inclusive of ISO 3166-1 α-2 country code (no spaces);
  • FISCAL_CODE_n: string mandatory for private SP with no vat number (otherwise optional), is valorized including the SP’s tax code;
  • COMPANY_n: string (0 or 1 occurrences) - if present, is valorized as the OrganizationName tag contained in the Organization tag;
  • TELEPHONE_NUMBER_n: string (0 or 1 occurrences) - contains the phone number, for contacting the SP; without spaces and including the international area code (example: “+39” for Italy);
  • ID_CODE_n: string indicates which country the VAT number belongs to (ISO 3166-1 code α-2);
  • ID_CODE_n: number VAT number of the subject;
  • DENOMINATION_n: string billing recipient;
  • INDIRIZZO_n: string address of the billing;
  • NUMERO_CIVICO_n: number house number of the billing;
  • CAP_n: number house number of the billing;
  • COMUNE_n: string municipality of the billing;
  • PROVINCIA_n: string province of the billing;
  • NAZIONE_n: string nation of the billing;
  • COMPANY_FATTURAZIONE_n: string (0 or 1 occurrence) - required if the entity for issuing invoices is distinct from the SP itself (and in all cases bearing the full and complete name of a legal entity, with the correct use of lower case, upper case and diacritical marks);
  • EMAIL_ADDRESS_FATTURAZIONE_n: string (1 occurrence, mandatory) - contains the e-mail address for contacting the SP. This must not be an address directly referable to an individual.

As for the logs instead (see Log Management):

  1. LOG_CERT: string path to the certificate (must be in p12 format);
  2. LOG_CERT_PWD: string password of the certificate;
  3. LOG_CERT_ALIAS: string alias of the certificate.

These 3 log variables are used for both CIE and SPID. Do not duplicate them on the same rewrite rule.

Certificate Generation

To generate the SPID certificate and keys, go to: Tools -> Keys Generator. Fill in the following fields:

  • Expiration days: validity duration of the certificate;
  • CN: is the value of the variable ORGANIZATION_DISPLAY_NAME_n;
  • Organization Name: is the value of the variable ORGANIZATION_NAME_n;
  • Organization Identifier: unique identifier code of the SP within the SPID federation, conforming to the syntax provided by ETSI standard en 319-412-1 , 5.1.4:
    • Public SP valued with the prefix ‘PA:IT-’ followed by the entity’s ipa code - example, for the Municipality of Rome (ipa code ‘c_h501’) this extension is valued as “PA:IT-c_h501”;
    • Private SP the following code alternative using, in order of preference:
      • the vat number, preceded by the prefix ‘VAT,’ followed by the ISO 3166-1 α-2 country code, followed by the character ‘-’ (example, “VATIT-12345678901”);
      • for entities without a VAT number, the tax code, preceded by the prefix ‘CF:IT-’ (example, “CF: IT-XYZABCAAMGGJ000W”);
      • other alternative code provided by AgID in special cases;
  • Policy Identifier:
    • publicSP: spid-publicsector-SP;
    • Private SP: spid-privatesector-SP;
  • Country: the ISO 3166-1 code of the country where the registered office of the SP is located (example: “IT”);
  • Locality: the full name of the city where the SP’s registered office is located (example: Forlì and not Forli).

Log Management

The information contained in the logs MUST be maintained and managed for a duration of not less than 24 months in full compliance with current national and European privacy regulations. To ensure confidentiality, data encryption mechanisms are adopted. Finally, the properties of integrity and non-repudiation are guaranteed in data storage.

The log files are located in: /TCOProject/bin/LBL/LBL_HOME/procsProfiles/<module>/federation_spid_xml_logs, where <module> is the module where the rewrite rule was applied, for example A10_LBLGoPlatform.

Below is the bash command to decrypt them:

# $encrypted_data replace with the file to be decrypted
# $cert replace with the certificate that encrypts the log (found in the rewrite rule)
# ${encrypted_data}.json replace with the name of the decrypted file
base64 -d "$encrypted_data" | openssl cms -decrypt -inform DER -recip "$cert" > "${encrypted_data}.json"

The deletion and management of logs is left to the system administrator.

Testing the configuration

Once you have configured the rewrite rule with the variable ENVIRONMENT_n = demo-online and applied it to the service to be protected, you need to try accessing the service. If a page with the “Log in with SPID” button is displayed, you must register the metadata (automatically generated and exposed by the rewrite rule) at https://demo.spid.gov.it/validator#/metadata-sp-download , enter the URL of the metadata and click on the “download” button. The URL is the CLIENT_ID_n followed by n followed by .well-known/saml2-entity-descriptor. For example, if we have the variable CLIENT_ID_4 = https://www.test.it/prova, then the URL to be entered would be https://www.test.it/prova/4/.well-known/saml2-entity-descriptor. If correct, the SPID Validator page will display the metadata in XML format. At this point, the SPID-protected service can be accessed, click on the “Log in with SPID” button and then on the DEMO IDP. A redirect will be made to the login page of the DEMO SPID site. Here you will be able to log in using one of the credentials on https://demo.spid.gov.it/users . Once you have successfully logged in and accepted data sharing, you will be redirected to the SPID-protected service site on the “/callback” path.

SPID membership procedure

  1. Set the variable ENVIRONMENT_n = validator-online to allow AgID verification on correct implementation;
  2. Complete and digitally sign the SPID Accession Form  and send it to spid.tech@agid.gov.it indicating in the subject line:
    • “00250 - SPID Membership Application for Aggregating Subjects of Public Service Providers - <Enterprise Name>”
    • “00340 - SPID Membership Application for Aggregator Subjects of Private Service Providers - <Entity Name>”.
  3. Wait for the confirmation email from AgID (AgID will verify the metadata received and the correctness of the implementation. If necessary, changes will be reported to ensure compliance with the technical rules);
  4. Once the technical procedure has been completed, AgID will send the copy of the agreement and the application form  for issuance of electronic certificate (CSR), in accordance with the SPID Notice №23 , to the administrative contact person, indicated in the form in item 5 of the technical procedure; The convention, form and CSR must be returned, completed and signed with qualified electronic signature, via PEC to protocollo@pec.agid.gov.it; Within a few days the agreement will be returned to you countersigned by the Director General of AgID along with the aforementioned electronic certificate; If you do not return the signed convention within 30 calendar days make immediate contact with AgID to arrange other deadline;
  5. Replace the certificate in the OPLON configuration, with the one received from AgID;
  6. Set the variable ENVIRONMENT_n = prod.

How to get the hash of the CSR

Step 4 of the SPID accession procedure, the PDF to be filled out asks for the hash of the CSR. To obtain such a hash, one must:

  1. Create a keystore via OPLON interface;
  2. Import the certificate in PEM format by copying the value of the variables SPID_PRIVATE_KEY, SPID_CERTIFICATE, SPID_PUBLIC_KEY in that exact order;
  3. Click on the Generate ACME certification request button and copy the result;
  4. Create a file ${file_name}.csr and paste the result into it;
  5. Run the following command to get the hash: openssl req -in ${file_name}.csr -outform PEM | openssl dgst -sha256.
Last updated on
CIEHTTP Compression