I Service Provider che intendono erogare i propri servizi tramite App mobile, hanno la possibilitá di integrare lo schema di autenticazione "Entra con CIE".
- Flusso con reindirizzamento: l'App del Service Provider, all'atto della richiesta di autenticazione dell'utente, reindirizza la richiesta all'App CieID che prende in carico la comunicazione e l'autenticazione con la CIE.
- 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 software.
Flusso con reindirizzamento
Flusso integrato
La versione del SDK per SO Android ,**CieID-android-sdk**, é disponibile al link https://github.com/italia/cieid-android-sdk. É costituita da una libreria software, realizzata in codice nativo Android Kotlin, e integra un app di esempio che descrive le diverse modalitá di integrazione dello schema "Entra con CIE":
L'utilizzo dell'SDK presuppone che il Service Provider sia correttamente federato con l'Identity Provider e che abbia implementato i protocolli SAML v2 previsti dallo schema di autenticazione "Entra con CIE" (cfr. le sezioni relative a :ref:`federazione`, :ref:`protocolli` e :ref:`binding`).
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 ad internet.
L'IdP mette a disposizione due ambienti: uno di preproduzione, per gli sviluppi applicativi, e l'altro di produzione, per la messa in esercizio. Per tale ragione é necessaria una fase iniziale di configurazione, che dipende dal tipo di flusso integrato.
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")Nel caso di flusso con reindirizzamento, per far proseguire correttamente il flusso, é necessario selezionare l'applicazione "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"Per quanto riguarda il flusso integrato, invece, la fase di autenticazione viene gestita dalla libreria software. In questo caso é necessario integrare il modulo "CieIDSdk":
implementation project(path: ':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:
//AMBIENTI:
//Ambiente di produzione
//buildConfigField "String", "BASE_URL_IDP", "\"https://idserver.servizicie.interno.gov.it/idp/\""
//Ambiente di collaudo
buildConfigField "String", "BASE_URL_IDP", "\"https://preproduzione.idserver.servizicie.interno.gov.it/idp/\""L'SDK fornisce un 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.
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 trueUna 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)
}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
}CieID-iOS-sdk è un SDK per smartphone iOS sviluppato in Swift che include le funzionalità di autenticazione di "Entra con CIE". Utilizzando questo kit, gli sviluppatori di applicazioni terze iOS possono integrare nella propria app l'autenticazione mediante la cartà d'identità elettronica.
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).
CieID-iOS-sdk necessita che il fornitore del servizio digitale sia un Service Provider federato e che integri la tecnologia abilitante al flusso di autenticazione "Entra con CIE" (cfr. le sezioni relative a :ref:`federazione`, :ref:`protocolli` e :ref:`binding`).
Il kit integra per il momento 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
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.
Non disponibile in questa versione
Trascinare la folder CieIDsdk all'interno del progetto xCode
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:
<key>SP_URL_SCHEME</key>
<string>Inserisci qui il parametro URL Scheme</string>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:
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
guard let url = URLContexts.first?.url else {
return
}
var urlString : String = String(url.absoluteString)
if let httpsRange = urlString.range(of: "https://"){
//Rimozione del prefisso dell'URL SCHEME
let startPos = urlString.distance(from: urlString.startIndex, to: httpsRange.lowerBound)
urlString = String(urlString.dropFirst(startPos))
//Passaggio dell'URL alla WebView
let response : [String:String] = ["payload": urlString]
let NOTIFICATION_NAME : String = "RETURN_FROM_CIEID"
NotificationCenter.default.post(name: Notification.Name(NOTIFICATION_NAME), object: nil, userInfo: response)
}
}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:
<key>SP_URL</key>
<string>Inserisci qui l'URL dell'ambiente di produzione del Service Provider</string>Aggiungere nello storyboard di progetto un oggetto di tipo UIButton ed inserire nella voce Class del menù Identity inspector la classe che lo gestisce: CieIDButton. L'oggetto grafico verrà automaticamente renderizzato con il pulsante ufficiale Entra con CIE.
Di seguito un esempio di gestione dell'evento TouchUpInside per eseguire il codice necessario per inizializzare e presentare la WebView di autenticazione.
@IBAction func startAuthentication(_ sender: UIButton){
let cieIDAuthenticator = CieIDWKWebViewController()
cieIDAuthenticator.modalPresentationStyle = .fullScreen
cieIDAuthenticator.delegate = self
present(cieIDAuthenticator, animated: true, completion: nil)
}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.
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)")
}Il codice sorgente è rilasciato sotto licenza BSD (codice SPDX: BSD-3-Clause).