Skip to content

Pulsante login per SPID basato su finestra modale JavaScript

License

Notifications You must be signed in to change notification settings

italia/spid-smart-button

Repository files navigation

SPID

Join the #spid-smart-button channel Get invited SPID on forum.italia.it CircleCI

⚠️ 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.