Skip to Content
Oplon Secure Access 11.0 is out! Read more →
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;
  • SPID_PUBLIC_KEY: string public key in pem format used to sign the metadata;
  • SPID_CERTIFICATE: string certificate in pem format used to sign the metadata;
  • SAML_SIGNED_ASSERTION_n: boolean must be a true;
  • BUTTON_IMAGE_BASE64_n: string encoded in base64; icon to left of button;
  • SERVICE_NAME_n: string.
  • 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;
  • 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;
  • 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;
  • 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.
  • ID_CODE_n: number
  • DENOMINATION_n: string Billing recipient;
  • INDIRIZZO_n: string
  • NUMERO_CIVICO_n: number
  • CAP_n: number
  • COMUNE_n: string
  • PROVINCIA_n: string
  • NAZIONE_n: string
  • 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.

Within the rewrite rule, we must then fill in the following variables:

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

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. In order to ensure confidentiality, data encryption mechanisms are adopted. Finally, the properties of integrity and non-repudiation are guaranteed in data storage.

# $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"

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.
Last updated on
CIEVAPP TML Setup