Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/italia/spid-express
Express middleware implementing SPID & Entra con CIE (Carta d'Identità Elettronica)
https://github.com/italia/spid-express
cie express expressjs italy node-js spid
Last synced: 2 months ago
JSON representation
Express middleware implementing SPID & Entra con CIE (Carta d'Identità Elettronica)
- Host: GitHub
- URL: https://github.com/italia/spid-express
- Owner: italia
- License: mit
- Fork: true (pagopa/io-spid-commons)
- Created: 2020-12-04T15:37:07.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-05-22T13:47:25.000Z (over 1 year ago)
- Last Synced: 2024-08-03T02:03:40.114Z (5 months ago)
- Topics: cie, express, expressjs, italy, node-js, spid
- Language: TypeScript
- Homepage:
- Size: 900 KB
- Stars: 41
- Watchers: 8
- Forks: 16
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
- .github - spid-express
README
[](https://github.com/italia/spid-express/blob/master/LICENSE)
[](https://github.com/italia/spid-express/issues)
[](https://app.slack.com/client/T6C27AXE0/C7ESTJS58)
[](https://slack.developers.italia.it/)
[](https://forum.italia.it/c/spid/5)
# spid-express
spid-express è un middleware per [Express](https://expressjs.com) che implementa
SPID e Entra con CIE (Carta d'identità Elettronica).
Puoi usare questo pacchetto per integrare SPID o CIE in un'applicazione Express.
## Requisiti
* Redis (per il salvataggio delle sessioni di autenticazione)
* `passport-saml 1.2.0` (versione esatta)
## Uso
La funzione `withSpid()` abilita SPID su un'app Express esistente.
È disponibile un esempio dell'uso in [`src/example.ts`](src/example.ts).
```js
withSpid({
acs, // Funzione che riceve i dati al login dell'utente SPID
app, // App Express
appConfig, // Endpoint dell'app
doneCb, // Callback (facoltativo)
logout, // Funzione da chiamare al logout SPID
redisClient, // Client Redis
samlConfig, // Configurazione del middleware
serviceProviderConfig // Configurazione del Service Provider
})
```
### `acs`
La funzione `acs()` (Assertion Consumer Service) riceve i dati dell'utente SPID
in `userPayload` se il login è avvenuto con successo. È definita come:
```js
type AssertionConsumerServiceT = (
userPayload: unknown
) => Promise<
| IResponseErrorInternal
| IResponseErrorValidation
| IResponsePermanentRedirect
| IResponseErrorForbiddenNotAuthorized
>
```
`userPayload` è un oggetto le cui chiavi sono gli attributi SPID richiesti in
`requiredAttributes.attributes` (nell'oggetto [`serviceProviderConfig`](#serviceProviderConfig)). Es:
```yaml
{
name: 'Carla'
familyName: 'Rossi'
fiscalNumber: 'RSSCRL32R82Y766D',
email: '[email protected]',
...
}
```
### `app`
L'istanza dell'app Express.
### `appConfig`
L'oggetto `appConfig` configura gli endpoint dell'app. Es:
```js
const appConfig: IApplicationConfig = {
assertionConsumerServicePath: "/acs",
clientErrorRedirectionUrl: "/error",
clientLoginRedirectionUrl: "/error",
loginPath: "/login",
metadataPath: "/metadata",
sloPath: "/logout"
};
```
* **`assertionConsumerServicePath`**: L'endpoint al quale verranno POSTati i
dati dell'utente dopo un login avvenuto con successo. È l'endpoint della
funzione `acs()` e viene creato automaticamente.
* **`clientErrorRedirectionUrl`**: URL al quale redirigere in caso di errore interno.
* **`clientLoginRedirectionUrl`**: URL al quale redirigere in caso di login SPID
fallito.
* **`loginPath`** L'endpoint che inizia la sessione SPID. Generalmente è l'endpoint
chiamato da [spid-smart-button](https://github.com/italia/spid-smart-button).
Viene creato automaticamente.
* **`metadataPath`**: L'endpoint del metadata. Viene creato automaticamente.
* **`sloPath`**: L'endpoint per il logout SPID. La [funzione collegata](#logout)
è quella passata in `withSpid()`.
### `doneCb`
La funzione chiamata dopo ogni risposta SAML (facoltativa).
### `logout`
La funzione da chiamare al logout di SPID, definita come:
```js
type LogoutT = () => Promise
```
### `redisClient`
L'istanza di `RedisClient` per connettersi a un server Redis.
### `samlConfig`
L'oggetto `samlConfig` configura il middleware. Es:
```js
const samlConfig: SamlConfig = {
RACComparison: "minimum",
acceptedClockSkewMs: 0,
attributeConsumingServiceIndex: "0",
authnContext: "https://www.spid.gov.it/SpidL1",
callbackUrl: "http://localhost:3000/acs",
identifierFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
issuer: "https://spid.agid.gov.it/cd",
logoutCallbackUrl: "http://localhost:3000/slo",
privateCert: fs.readFileSync("./certs/key.pem", "utf-8"),
validateInResponseTo: true
};
```
* **`RACComparison`**: Impostare a "`minimum`".
* **`acceptedClockSkewMs`**: Impostare a `0`.
* **`attributeConsumingServiceIndex`**: Impostare all'indice degli attributi richiesti
definito nel metadata. Se l'app è l'unica applicazione SPID del Service Provider,
impostare a "`0`".
* **`authnContext`**: Livello SPID richiesto. "`https://www.spid.gov.it/SpidL1`",
"`https://www.spid.gov.it/SpidL2`" o "`https://www.spid.gov.it/SpidL3`".
* **`callbackUrl`**: L'URL completo di [`assertionConsumerServicePath`](#appConfig)
* **`identifierFormat`**: Impostare a "`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`"
* **`issuer`**: URL del Service Provider.
* **`logoutCallbackUrl`**: L'URL completo di [`sloPath`](#appConfig)
* **`privateCert`**: Stringa con la chiave privata del Service Provider in
formato PEM.
* **`validateInResponseTo`**: Impostare a `true`.
### `serviceProviderConfig`
L'oggetto `serviceProviderConfig` contiene i parametri del Service Provider. Es:
```js
const serviceProviderConfig: IServiceProviderConfig = {
IDPMetadataUrl:
"https://registry.spid.gov.it/metadata/idp/spid-entities-idps.xml",
organization: {
URL: "https://example.com",
displayName: "Organization display name",
name: "Organization name"
},
publicCert: fs.readFileSync("./certs/cert.pem", "utf-8"),
requiredAttributes: {
attributes: [
"address",
"email",
"name",
"familyName",
"fiscalNumber",
"mobilePhone"
],
name: "Required attrs"
},
spidCieUrl: "https://preproduzione.idserver.servizicie.interno.gov.it/idp/shibboleth?Metadata",
spidTestEnvUrl: "https://spid-testenv2:8088",
spidValidatorUrl: "http://localhost:8080",
strictResponseValidation: {
"http://localhost:8080": true,
"https://spid-testenv2:8088": true
}
};
```
* **`IDPMetadataUrl`**: URL dei metadata degli IdP. Impostare a "`https://registry.spid.gov.it/metadata/idp/spid-entities-idps.xml`".
* **`organization`**: Oggetto con i dati del Service Provider.
* **`publicCert`**: Stringa con il certificato del Service Provider in formato PEM.
* **`requiredAttributes`**: La lista, in `attributes`, degli attributi richiesti
(identificativi in ).
* **`spidCieUrl`**: URL per l'accesso con Carta d'Identità elettronica
("Entra con CIE").
Impostare a "`https://preproduzione.idserver.servizicie.interno.gov.it/idp/shibboleth?Metadata`"
per lo sviluppo.
* **`spidTestEnvUrl`**: URL dell'istanza di [spid-testenv2](https://github.com/italia/spid-testenv2).
Lasciare vuoto per disabilitare.
* **`spidValidatorUrl`**: URL dell'istanza di [spid-saml-check](https://github.com/italia/spid-saml-check).
Lasciare vuoto per disabilitare.
* **`strictResponseValidation`**: Impostare come da esempio con gli URL di
`spid-testenv2` e `spid-saml-check` (se abilitati).
## Avvio dell'applicazione di esempio integrata
L'applicazione di esempio (`src/example.ts`) può essere lanciata con:
```shell
docker-compose up
```
Dopo il messaggio `[spid-express] info: samlCert expire in 12 months`) l'app sarà
pronta e in ascolto su .
Iniziare la sessione SPID con una GET su
[`http://localhost:3000/login?entityID=xx_testenv2`](http://localhost:3000/login?entityID=xx_testenv2).
`xx_testenv2` è l'`entityID` di sviluppo che redirigerà il login a spid-testenv2.
Gli `entityID` che si possono usare in produzione sono "`lepidaid`", "`infocertid`",
"`sielteid`", "`namirialid`", "`timid`", "`arubaid`", "`posteid`", "`intesaid`"
e "`spiditalia`" (vedere [`src/config.ts`](src/config.ts)).
### Uso di Carta di Identità Elettronica (CIE)
Il middleware permette anche di interagire con gli IDP di collaudo e produzione di
"Entra con CIE" dell'Istituto Poligrafico Zecca dello Stato. Non è presente al momento
un ambiente di sviluppo.
Per poter utilizzare l'ambiente di collaudo è necessario federarsi inviando un
modulo di richiesta come specificato nel
[manuale operativo CIE](https://www.cartaidentita.interno.gov.it/CIE-ManualeOperativoperifornitoridiservizi.pdf).
Una volta federati, è possibile utilizzare lo stesso endpoint utilizzato per SPID
per l'accesso con CIE: l'entityID è "`xx_servizicie`" in produzione e
"`xx_servizicie_test`" in collaudo.
# Licenza
spid-express è rilasciato con [licenza MIT](LICENSE).