Flusso con reindirizzamento¶

L'App del Service Provider, all'atto della richiesta di autenticazione dell'utente, reindirizza la richiesta all'App CieID che cura i dettagli la comunicazione e l'autenticazione con la CIE, mascherando tali aspetti all'applicazione chiamante.

Autenticazione di livello 1 - Flusso con reindirizzamento

Autenticazione di livello 2 - Flusso con reindirizzamento

Autenticazione di livello 3 - Flusso con reindirizzamento

Flusso integrato¶

Il processo di autenticazione viene effettuato direttamente all'interno dell'app del Service Provider, il quale integra la comunicazione con la CIE mediante una libreria SDK, disponibile sia per sistemi operativi Android che iOS.

Autenticazione di livello 3 - Flusso interno

Requisiti di integrazione¶

L'utilizzo dell'SDK presuppone che il Service Provider sia correttamente federato con l'Identity Provider e che abbia implementato almeno uno tra i protocolli previsti dallo schema di autenticazione «Entra con CIE”.

Inoltre, è necessario che i seguenti requisiti siano soddisfatti:

• versione Android 6.0 (API level 23) o successive;
• utilizzo di un dispositivo mobile dotato di tecnologia NFC;
• disponibilità di una connessione internet

Configurazione¶

Dell'IdP sono messi a disposizione degli erogatori di servizi due ambienti: uno di preproduzione, per gli sviluppi applicativi e i test di federazione e l'altro di produzione, per il deploy in esercizio. Difatti, per l'impiego di un'app terza con uno dei flussi disponibili è necessaria una fase iniziale di configurazione, che dipende dal tipo di flusso adottato.

Entrambi i flussi vengono avviati tramite l'utilizzo di una Webview: é necessario caricare la URL del Service Provider che integra il pulsante «Entra con CIE» come mostrato nell'esempio:

*//inserire url service provider*
webView.loadUrl("URL del Service Provider")

Flusso con reindirizzamento

Nel caso di flusso con reindirizzamento, per far proseguire correttamente il flusso, è necessario selezionare l'applica- zione «CieID» a cui indirizzare le richieste di autenticazione. Ciò può essere fatto modificando i commenti dalle righe di interesse, come mostrato di seguito.

val appPackageName = "it.ipzs.cieid"
*//COLLAUDO*
*//val appPackageName = "it.ipzs.cieid.collaudo"*

Flusso integrato

Per quanto riguarda il flusso integrato, invece, la fase di autenticazione viene gestita dalla libreria software. In questo caso é necessario integrare il modulo «CieIDSdk».

L'SDK utilizza Gradle con strumento di build automatico. Per configurare correttamente il flusso, é necessario selezionare l'ambiente server dell'Identity Provider a cui indirizzare le richieste di autenticazione. Ció puó essere fatto modificando il file build.gradle modificando i commenti dalle righe di interesse, come mostrato di seguito:

Modalità di integrazione¶

L'SDK fornisce una app di esempio, con 2 activity, una per flusso, per facilitare al Service Provider l'integrazione all'interno della propria App. La gestione degli errori è demandata all'app integrante.

Integrazione del flusso con reindirizzamento

Per integrare nativamente le funzionalità dell'SDK é necessario, per prima cosa, intercettare la URL contenente il valore «/OpenApp» ed avviare l'App CieID integrando il codice seguente:

val intent = Intent()
**try** {

        intent.setClassName(appPackageName, className)
        *//settare la url caricata dalla webview su /OpenApp*
        intent.data = Uri.parse(url)
        intent.action = Intent.ACTION_VIEW
        startActivityForResult(intent, 0)
} **catch** (a : ActivityNotFoundException) {
        startActivity(

                Intent(

                        Intent.ACTION_VIEW,

                        Uri.parse("https://play.google.com/store/apps/details?id=$appPackageName")

                )

        )

)

**return true**

Una volta avviata correttamente l'App CieID, avviene l'autenticazione tramite la CIE, e al termine viene restituita una nuova URL da ricarica nella WebView precedente, come mostrato nell'esempio seguente:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {

        **super**.onActivityResult(requestCode, resultCode, data)
        val url = data?.getStringExtra(URL)

        webView.loadUrl(url)

}

Integrazione del flusso integrato

Per integrare le funzionalità dell'SDK si utilizzano i seguenti metodi:

*//Configurazione iniziale*

CieIDSdk.start(activity, callback)

*//Avvio utilizzo NFC*

CieIDSdk.startNFCListening(activity)

*//Abilitare o disabilitare i log, da disattivare in produzione*

CieIDSdk.enableLog = **true**

*//Bisogna settare la url caricata dalla pagina web dell' SP dalla
webview su /OpenApp*

CieIDSdk.setUrl(url.toString())

*//inserire il pin della CIE*

CieIDSdk.pin = input.text.toString()

*//Avviare NFC*

startNFC()

É necessario, inoltre, realizzare le interfacce di Callback implementando i seguenti metodi:

override fun onEvent(event: Event) {

*//evento*

}

override fun onError(e: Throwable) {

*//caso di errore*

}

override fun onSuccess(url: String) {

*//caso di successo con url della pagina da caricare*

}

Requisiti tecnici¶

CieID-iOS-sdk richiede versione iOS 13.0 o successive, inoltre è necessario uno smartphone iOS con tecnologia NFC (iPhone 7 o successivo, non è compatibile con iPhone SE di prima generazione - mod 2016).

Requisiti di integrazione¶

L'utilizzo dell'SDK presuppone che il Service Provider sia correttamente federato con l'Identity Provider e che abbia implementato almeno uno tra i protocolli previsti dallo schema di autenticazione «Entra con CIE».

Come si usa¶

Il kit prevede il solo flusso di autenticazione con reindirizzamento di seguito descritto. L'integrazione richiede pochi semplici passaggi:

• Importazione del kit all'interno del progetto
• Configurazione dell'URL Scheme
• Configurazione dell'URL di un Service Provider valido all'interno del file Info.plist
• Configurazione dello smart button Entra con CIE all'interno dello storyboard
• Inizializzazione e presentazione della webView di autenticazione
• Gestione dei delegati

Flusso con reindirizzamento¶

Il flusso di autenticazione con reindirizzamento permette ad un Service Provider accreditato di integrare l'autenticazione Entra con CIE nella propria app iOS, demandando le operazioni di autenticazione all'app CieID. Questo flusso di autenticazione richiede che l'utente abbia l'app CieID installata sul proprio smartphone in versione 1.2.1 o successiva.

Flusso interno¶

Non disponibile.

Importazione¶

Trascinare il folder CieIDsdk all'interno del progetto xCode

Configurazione URL Scheme¶

Nel flusso di autenticazione con reindirizzamento l'applicazione CieID avrà bisogno aprire l'app chiamante per potergli notificare l'avvenuta autenticazione. A tal fine è necessario configurare un URL Scheme nel progetto Xcode come segue:

Selezionare il progetto Target, aprire il pannello Info ed aprire poi il pannello URL Types. Compilare i campi

Identifier e URL Scheme inserendo il Bundle Identifier dell'app, impostare poi su none il campo Role.

Il parametro appena inserito nel campo URL Scheme dovrà essere riportato nel file Info.plist, aggiungendo un parametro chiamato SP_URL_SCHEME di tipo String, come mostrato nell'esempio:

A seguito dell'apertura dell'app la webView dovrà ricevere un nuovo URL e proseguire la navigazione. Di seguito si riporta il metodo openUrlContext da importare nello SceneDelegate che implementa tale logica:

Configurazione Service Provider URL¶

Entrambi i flussi vengono avviati tramite l'utilizzo di una WebView, per questo motivo è necessario caricare la URL dell'ambiente di produzione della pagina web del Service Provider che integra il pulsante «Entra con CIE» all'interno del file Info.plist, aggiungendo un parametro chiamato SP_URL di tipo String, come mostrato nell'esempio:

Importazione del pulsante Entra con CIE¶

Aggiungere nello storyboard di progetto un oggetto di tipo UIButton ed inserire nella voce Class del menù Iden- tity inspector la classe che lo gestisce: CieIDButton. L'oggetto grafico verrà automaticamente renderizzato con il pulsante ufficiale “Entra con CIE”.

Eseguire l'autenticazione¶

Di seguito un esempio di gestione dell'evento TouchUpInside per eseguire il codice necessario per inizializzare e presentare la WebView di autenticazione.

La classe chiamante dovrà essere conforme al protocollo CieIdDelegate come mostrato nell'esempio.

**class ExampleViewController**: UIViewController, CieIdDelegate {
...
}

L'utente potrà navigare nella webView mostrata che lo indirizzerà sull'app CieID dove potrà eseguire l'autenticazione con la Carta di Identità Elettronica, al termine verrà nuovamente reindirizzato sull'app chiamante in cui potrà dare il consenso alla condivisione delle informazioni personali e portare al termine l'autenticazione.

Al termine dell'autenticazione verrà chiamato il delegato CieIDAuthenticationClosedWithSuccess. La chiamata di questo delegato avviene nella classe CieIDWKWebViewController. Potrebbe rendersi necessario posticipare la chiamata di questo delegato in base alla logica di autenticazione del Service Provider.

Gestione eventi¶

Il protocollo impone la gestione dei seguenti eventi mediante delegati

**func** CieIDAuthenticationClosedWithSuccess() {
                        print("Authentication closed with SUCCESS")

}

**func** CieIDAuthenticationCanceled() {
                        print("L'utente ha annullato l'operazione")

}

**func** CieIDAuthenticationClosedWithError(errorMessage: String) {
                        print("ERROR MESSAGE: *\\(*\ errorMessage\ *)*")

}