spid-smart-button: A JavaScript repository from Developers Italia

⚠️ WORK IN PROGRESS ⚠️

Lo SPID Button consente all'utente la scelta del proprio Identity Provider per l'autenticazione.

Con l'utilizzo di spid-smart-button si intende:

facilitare l'integrazione del bottone "Entra con SPID";
fornire un bottone ospitato via CDN;
migliorare l'esperienza utente.

Link utili

Utilizzo dello smart-button

Nel momento in cui lo spid-smart-button sara' disponibile tramite CDN, sarà sufficiente importare lo script presente su CDN nella pagina web in cui si intende posizionare il bottone:

<script type="text/javascript" src="https://XXXXXXXXXXXX/spid-button.min.js"></script>

Nel punto in cui si intende posizionare il bottone si dovrà inserire un placeholder <div> come da esempio:

<div id="spid-button">
    <noscript>
        Il login tramite SPID richiede che JavaScript sia abilitato nel browser.
    </noscript>
</div>

Si dovrà poi inizializzare il bottone con una chiamata JavaScript:

SPID.init({
    url: '/Login?idp={{idp}}',
    supported: [
        'https://idp1.it',
        'https://idp2.it'
    ]
});

Configurazione

`SPID.init({ ... })`

La funzione SPID.init() inizializza il bottone secondo i parametri forniti, che possono essere i seguenti:

Parametro	Descrizione	Esempio
lang	`it`/`en`/`de` (default: `it`)	`"it"`
method	`GET`/`POST` (default: `GET`)	`"GET"`
url	(obbligatorio) URL da chiamare (anche relativo). Il placeholder `{{idp}}` sarà sostituito con l’entityID dell’IdP selezionato (o con il valore custom specificato nel parametro `mapping`). Se questo parametro è assente, sarà scritto un errore in console.error()	`"/spid/login/idp={{idp}}"`
fieldName	Se method=POST, contiene il nome del campo hidden in cui passiamo l’IdP selezionato (default: `idp`)	`"idp"`
extraFields	Se method=POST, contiene eventuali valori aggiuntivi da passare in campi hidden	`{ foo: "bar" }`
selector	Selettore CSS da usare per individuare l’elemento in cui iniettare lo Smart Button (default: #spid-button)	`"#spid-button"`
mapping	Dizionario di mappatura tra entityID e valori custom, da usare quando un SP identifica gli IdP con chiavi diverse dall’entityID	`{ "https://www.poste.it/spid": "poste" }`
supported	(obbligatorio) Array di entityID relativi agli IdP di cui il SP ha i metadati. Gli IdP non presenti saranno mostrati in grigio all’utente.	`[ "https://www.poste.it/spid" ]`
extraProviders	Array di oggetti contenenti le configurazioni di ulteriori Identity Provider (di test) non ufficiali che si vogliano abilitare. I provider qui elencati sono automaticamente aggiunti all’elenco supported sopra descritto. Per motivi di sicurezza, qualora si configurino dei provider extra, i provider ufficiali verranno disabilitati.	`[{ "entityID": "https://testidp.mycorp.com/", "entityName": "Test IdP" }]`
protocol	`SAML`/`OIDC`. Protocollo usato dal SP per interagire con gli IdP. Dal momento che alcuni IdP potrebbero non supportare OIDC (ad oggi nessun IdP lo supporta), questo parametro serve per mostrare in grigio gli IdP non supportati (default: `"SAML"`)	`"SAML"`
size	`small`/`medium`/`large`. Dimensione di visualizzazione (default: `medium`)	`"medium"`
colorScheme	`positive`/`negative`. Schema di colori da adottare in base allo sfondo (default: `positive`)	`"positive"`
fluid	`true`/`false`. Adatta la larghezza del bottone all’elemento che lo contiene (ma max 400px). (default: `false`)	`true`
cornerStyle	`rounded`/`sharp`. Stile degli angoli del bottone. Se impostato a `sharp`, il bottone non avrà margine. (default: `rounded`)	`"rounded"`

La funzione SPID.init() restituisce un oggetto che può essere ignorato oppure assegnato ad una variabile qualora si intendano chiamare gli altri metodi documentati di seguito.

Esempio completo:

var spid = SPID.init({
    lang: 'en',                   // opzionale
    selector: '#my-spid-button',  // opzionale
    method: 'POST',               // opzionale
    url: '/Login',                // obbligatorio
    fieldName: 'idp',             // opzionale
    extraFields: {                // opzionale
        foo: 'bar',
        baz: 'baz'
    },
    mapping: {                    // opzionale
        'https://loginspid.aruba.it': 4,
        'https://posteid.poste.it': 5,
        'https://idp.namirialtsp.com/idp': 7,
    },
    supported: [                  // obbligatorio
        'https://identity.sieltecloud.it'
    ],
    extraProviders: [            // opzionale
        {
            "protocols": ["SAML"],
            "entityName": "valore de IDP entity ID",
            "logo": "spid-idp-aruba.svg",
            "entityID": "https://loginciccio.it",
            "active": true
        },
        {
            "protocols": ["SAML"],
            "entityName": "Foo bar ",
            "logo": "spid-idp-infocertid.svg",
            "entityID": "https://identity.pippocert.it",
            "active": true
        }
    ],
    protocol: "SAML",           // opzionale
    size: "small"               // opzionale
});

`changeLanguage(lang)`

Questo metodo consente di cambiare la lingua dello Smart Button a run-time. La stringa lang deve essere costituita da due caratteri eg it. Le lingue supportate sono italiano it, inglese en e tedesco de

spid.changeLanguage('en');

Configurazione degli Identity Provider

I dati degli IdP sono riportati staticamente nel codice sorgente dello Smart Button, e pertanto non è necessario aggiornarli manualmente. Eventuali variazioni al nome o al logo, così come eventuali rimozioni di Identity Provider, verranno automaticamente recepite dallo Smart Button senza bisogno di alcun intervento.

In caso di aggiunta di nuovi Identity Provider, o in caso di variazione di EntityID, il Service Provider dovrà aggiornare il proprio backend con i nuovi metadati e poi aggiungere l'entityID all'array supported dello Smart Button che quindi renderà cliccabile il nuovo Identity Provider. Si consiglia, se possibile in base al proprio stack applicativo, di generare la lista supported automaticamente a partire dai metadati caricati nell'applicazione.

Configurazione di Identity Provider di test

Il parametro extraProviders permette di configuare ulteriori Identity Provider rispetto a quelli ufficiali. Questa cosa può essere utile per usare un Identity Provider di test. I parametri per la configurazione di ciascun Identity Provider aggiuntivo sono i seguenti:

Parametro	Descrizione
entityID	(obbligatorio) Identificativo dell'Identity Provider
entityName	(obbligatorio) Nome pubblico dell'Identity Provider da mostrare nella lista
logo	URL completo del file PNG raffigurante il logo
protocols	Array che può contenere i valori `SAML` e/o `OIDC` a seconda dei protocolli supportati dall'IdP (default: `["SAML"]`)
active	`true`/`false`. Può essere usato per mostrare l'IdP come non attivo (default: `true`)

Per motivi di sicurezza, qualora si configurino dei provider extra i provider ufficiali verranno automaticamente disabilitati.

italia/spid-smart-button