{"id":13650148,"url":"https://github.com/italia/spid-express","last_synced_at":"2025-04-22T18:31:03.032Z","repository":{"id":39651327,"uuid":"318559360","full_name":"italia/spid-express","owner":"italia","description":"Express middleware implementing SPID \u0026 Entra con CIE (Carta d'Identità Elettronica)","archived":false,"fork":true,"pushed_at":"2023-05-22T13:47:25.000Z","size":922,"stargazers_count":41,"open_issues_count":27,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-03T02:03:40.114Z","etag":null,"topics":["cie","express","expressjs","italy","node-js","spid"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"pagopa/io-spid-commons","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/italia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2020-12-04T15:37:07.000Z","updated_at":"2024-04-17T16:08:30.000Z","dependencies_parsed_at":"2023-02-13T17:16:34.972Z","dependency_job_id":null,"html_url":"https://github.com/italia/spid-express","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fspid-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fspid-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fspid-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fspid-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/italia","download_url":"https://codeload.github.com/italia/spid-express/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223903060,"owners_count":17222484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cie","express","expressjs","italy","node-js","spid"],"created_at":"2024-08-02T02:00:34.263Z","updated_at":"2024-11-10T01:30:34.695Z","avatar_url":"https://github.com/italia.png","language":"TypeScript","funding_links":[],"categories":["🎭 SPID"],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable no-inline-html --\u003e\n\n\u003cimg\n    src=\"https://github.com/italia/spid-graphics/blob/master/spid-logos/spid-logo-b-lb.png\"\n    alt=\"SPID\"\n    data-canonical-src=\"https://github.com/italia/spid-graphics/blob/master/spid-logos/spid-logo-b-lb.png\"\n    width=\"500\"\n    height=\"98\"\n/\u003e\n\n[![License](https://img.shields.io/github/license/italia/spid-express.svg)](https://github.com/italia/spid-express/blob/master/LICENSE)\n[![GitHub issues](https://img.shields.io/github/issues/italia/spid-express.svg)](https://github.com/italia/spid-express/issues)\n[![Join the #spid-express channel](https://img.shields.io/badge/Slack%20channel-%23spid--express-blue.svg)](https://app.slack.com/client/T6C27AXE0/C7ESTJS58)\n[![Get invited](https://slack.developers.italia.it/badge.svg)](https://slack.developers.italia.it/)\n[![SPID on forum.italia.it](https://img.shields.io/badge/Forum-spid-blue.svg)](https://forum.italia.it/c/spid/5)\n\n# spid-express\n\nspid-express è un middleware per [Express](https://expressjs.com) che implementa\nSPID e Entra con CIE (Carta d'identità Elettronica).\n\nPuoi usare questo pacchetto per integrare SPID o CIE in un'applicazione Express.\n\n## Requisiti\n\n* Redis (per il salvataggio delle sessioni di autenticazione)\n* `passport-saml 1.2.0` (versione esatta)\n\n## Uso\n\nLa funzione `withSpid()` abilita SPID su un'app Express esistente.\nÈ disponibile un esempio dell'uso in [`src/example.ts`](src/example.ts).\n\n```js\n   withSpid({\n     acs,                  // Funzione che riceve i dati al login dell'utente SPID\n     app,                  // App Express\n     appConfig,            // Endpoint dell'app\n     doneCb,               // Callback (facoltativo)\n     logout,               // Funzione da chiamare al logout SPID\n     redisClient,          // Client Redis\n     samlConfig,           // Configurazione del middleware\n     serviceProviderConfig // Configurazione del Service Provider\n   })\n```\n\n### `acs`\n\nLa funzione `acs()` (Assertion Consumer Service) riceve i dati dell'utente SPID\nin `userPayload` se il login è avvenuto con successo. È definita come:\n\n```js\n   type AssertionConsumerServiceT = (\n     userPayload: unknown\n   ) =\u003e Promise\u003c\n     | IResponseErrorInternal\n     | IResponseErrorValidation\n     | IResponsePermanentRedirect\n     | IResponseErrorForbiddenNotAuthorized\n   \u003e\n```\n\n`userPayload` è un oggetto le cui chiavi sono gli attributi SPID richiesti in\n`requiredAttributes.attributes` (nell'oggetto [`serviceProviderConfig`](#serviceProviderConfig)). Es:\n\n```yaml\n  {\n     name: 'Carla'\n     familyName: 'Rossi'\n     fiscalNumber: 'RSSCRL32R82Y766D',\n     email: 'foobar@example.com',\n     ...\n  }\n```\n\n### `app`\n\nL'istanza dell'app Express.\n\n### `appConfig`\n\nL'oggetto `appConfig` configura gli endpoint dell'app. Es:\n\n```js\n   const appConfig: IApplicationConfig = {\n     assertionConsumerServicePath: \"/acs\",\n     clientErrorRedirectionUrl: \"/error\",\n     clientLoginRedirectionUrl: \"/error\",\n     loginPath: \"/login\",\n     metadataPath: \"/metadata\",\n     sloPath: \"/logout\"\n   };\n```\n\n* **`assertionConsumerServicePath`**: L'endpoint al quale verranno POSTati i\n  dati dell'utente dopo un login avvenuto con successo. È l'endpoint della\n  funzione `acs()` e viene creato automaticamente.\n* **`clientErrorRedirectionUrl`**: URL al quale redirigere in caso di errore interno.\n* **`clientLoginRedirectionUrl`**: URL al quale redirigere in caso di login SPID\n  fallito.\n* **`loginPath`** L'endpoint che inizia la sessione SPID. Generalmente è l'endpoint\n  chiamato da [spid-smart-button](https://github.com/italia/spid-smart-button).\n  Viene creato automaticamente.\n* **`metadataPath`**: L'endpoint del metadata. Viene creato automaticamente.\n* **`sloPath`**: L'endpoint per il logout SPID. La [funzione collegata](#logout)\n  è quella passata in `withSpid()`.\n\n### `doneCb`\n\nLa funzione chiamata dopo ogni risposta SAML (facoltativa).\n\n### `logout`\n\nLa funzione da chiamare al logout di SPID, definita come:\n\n```js\n    type LogoutT = () =\u003e Promise\u003cIResponsePermanentRedirect\u003e\n```\n\n### `redisClient`\n\nL'istanza di `RedisClient` per connettersi a un server Redis.\n\n### `samlConfig`\n\nL'oggetto `samlConfig` configura il middleware. Es:\n\n```js\n   const samlConfig: SamlConfig = {\n     RACComparison: \"minimum\",\n     acceptedClockSkewMs: 0,\n     attributeConsumingServiceIndex: \"0\",\n     authnContext: \"https://www.spid.gov.it/SpidL1\",\n     callbackUrl: \"http://localhost:3000/acs\",\n     identifierFormat: \"urn:oasis:names:tc:SAML:2.0:nameid-format:transient\",\n     issuer: \"https://spid.agid.gov.it/cd\",\n     logoutCallbackUrl: \"http://localhost:3000/slo\",\n     privateCert: fs.readFileSync(\"./certs/key.pem\", \"utf-8\"),\n     validateInResponseTo: true\n   };\n ```\n\n* **`RACComparison`**: Impostare a \"`minimum`\".\n* **`acceptedClockSkewMs`**: Impostare a `0`.\n* **`attributeConsumingServiceIndex`**: Impostare all'indice degli attributi richiesti\n  definito nel metadata. Se l'app è l'unica applicazione SPID del Service Provider,\n  impostare a \"`0`\".\n* **`authnContext`**: Livello SPID richiesto. \"`https://www.spid.gov.it/SpidL1`\",\n  \"`https://www.spid.gov.it/SpidL2`\" o \"`https://www.spid.gov.it/SpidL3`\".\n* **`callbackUrl`**: L'URL completo di [`assertionConsumerServicePath`](#appConfig)\n* **`identifierFormat`**: Impostare a \"`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`\"\n* **`issuer`**: URL del Service Provider.\n* **`logoutCallbackUrl`**: L'URL completo di [`sloPath`](#appConfig)\n* **`privateCert`**: Stringa con la chiave privata del Service Provider in\n  formato PEM.\n* **`validateInResponseTo`**: Impostare a `true`.\n\n### `serviceProviderConfig`\n\nL'oggetto `serviceProviderConfig` contiene i parametri del Service Provider. Es:\n\n```js\n   const serviceProviderConfig: IServiceProviderConfig = {\n     IDPMetadataUrl:\n       \"https://registry.spid.gov.it/metadata/idp/spid-entities-idps.xml\",\n     organization: {\n       URL: \"https://example.com\",\n       displayName: \"Organization display name\",\n       name: \"Organization name\"\n     },\n     publicCert: fs.readFileSync(\"./certs/cert.pem\", \"utf-8\"),\n     requiredAttributes: {\n       attributes: [\n         \"address\",\n         \"email\",\n         \"name\",\n         \"familyName\",\n         \"fiscalNumber\",\n         \"mobilePhone\"\n       ],\n       name: \"Required attrs\"\n     },\n     spidCieUrl: \"https://preproduzione.idserver.servizicie.interno.gov.it/idp/shibboleth?Metadata\",\n     spidTestEnvUrl: \"https://spid-testenv2:8088\",\n     spidValidatorUrl: \"http://localhost:8080\",\n     strictResponseValidation: {\n       \"http://localhost:8080\": true,\n       \"https://spid-testenv2:8088\": true\n     }\n   };\n```\n\n* **`IDPMetadataUrl`**: URL dei metadata degli IdP. Impostare a \"`https://registry.spid.gov.it/metadata/idp/spid-entities-idps.xml`\".\n* **`organization`**: Oggetto con i dati del Service Provider.\n* **`publicCert`**: Stringa con il certificato del Service Provider in formato PEM.\n* **`requiredAttributes`**: La lista, in `attributes`, degli attributi richiesti\n  (identificativi in \u003chttps://docs.italia.it/italia/spid/spid-regole-tecniche/it/stabile/attributi.html\u003e).\n* **`spidCieUrl`**: URL per l'accesso con Carta d'Identità elettronica\n  (\"Entra con CIE\").\n  Impostare a \"`https://preproduzione.idserver.servizicie.interno.gov.it/idp/shibboleth?Metadata`\"\n  per lo sviluppo.\n* **`spidTestEnvUrl`**: URL dell'istanza di [spid-testenv2](https://github.com/italia/spid-testenv2).\n  Lasciare vuoto per disabilitare.\n* **`spidValidatorUrl`**: URL dell'istanza di [spid-saml-check](https://github.com/italia/spid-saml-check).\n  Lasciare vuoto per disabilitare.\n* **`strictResponseValidation`**: Impostare come da esempio con gli URL di\n  `spid-testenv2` e `spid-saml-check` (se abilitati).\n\n## Avvio dell'applicazione di esempio integrata\n\nL'applicazione di esempio (`src/example.ts`) può essere lanciata con:\n\n```shell\ndocker-compose up\n```\n\nDopo il messaggio `[spid-express] info: samlCert expire in 12 months`) l'app sarà\npronta e in ascolto su \u003chttp://localhost:3000\u003e.\n\nIniziare la sessione SPID con una GET su\n[`http://localhost:3000/login?entityID=xx_testenv2`](http://localhost:3000/login?entityID=xx_testenv2).\n`xx_testenv2` è l'`entityID` di sviluppo che redirigerà il login a spid-testenv2.\n\nGli `entityID` che si possono usare in produzione sono \"`lepidaid`\", \"`infocertid`\",\n\"`sielteid`\", \"`namirialid`\", \"`timid`\", \"`arubaid`\", \"`posteid`\", \"`intesaid`\"\ne \"`spiditalia`\" (vedere [`src/config.ts`](src/config.ts)).\n\n### Uso di Carta di Identità Elettronica (CIE)\n\nIl middleware permette anche di interagire con gli IDP di collaudo e produzione di\n\"Entra con CIE\" dell'Istituto Poligrafico Zecca dello Stato. Non è presente al momento\nun ambiente di sviluppo.\n\nPer poter utilizzare l'ambiente di collaudo è necessario federarsi inviando un\nmodulo di richiesta come specificato nel\n[manuale operativo CIE](https://www.cartaidentita.interno.gov.it/CIE-ManualeOperativoperifornitoridiservizi.pdf).\n\nUna volta federati, è possibile utilizzare lo stesso endpoint utilizzato per SPID\nper l'accesso con CIE: l'entityID è \"`xx_servizicie`\" in produzione e\n\"`xx_servizicie_test`\" in collaudo.\n\n# Licenza\n\nspid-express è rilasciato con [licenza MIT](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitalia%2Fspid-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitalia%2Fspid-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitalia%2Fspid-express/lists"}