SDK de iOS Guardian.swift

Describe cómo instalar, usar y configurar las opciones del SDK de iOS Guardian.swift.

Guardian.swift le permite integrar el servicio Guardian de autenticación multifactor de Auth0 en su propia aplicación de iOS, transformándola en el segundo factor. Sus usuarios obtendrán todos los beneficios de nuestra autenticación multifactor sin fricciones directamente desde su aplicación. Para obtener más información, lea Primeros pasos con Apple Push Notification Service.

​

Requisitos

• Se requiere iOS 10+ y Swift 4.1 para usar Guardian.
• Para usar este SDK, debes configurar el servicio Guardian de tu inquilino con tus propias credenciales de notificaciones push; de lo contrario, no recibirás ninguna notificación push. Para obtener más información, consulta Configure Push Notifications for MFA.

​

Instale el SDK de Guardian para iOS

​

CocoaPods

Guardian.swift está disponible mediante CocoaPods. Para instalarlo, agrega la siguiente línea a tu Podfile:

pod 'Guardian', '~> 1.1.0'

​

Carthage

Agrega esta línea a tu archivo Cartfile:

github "auth0/Guardian.swift" ~> 1.1.0

​

Habilitar las notificaciones push de Guardian

1. Ve a Dashboard > Seguridad > Autenticación multifactor.
2. Activa la opción Push Notification para habilitarla.
3. Configura las notificaciones push.

​

Uso

Guardian es el componente principal del SDK. Para usar el SDK, importa la biblioteca:

import Guardian

Configura el dominio de tu inquilino. O usa el dominio personalizado si configuraste uno para tu inquilino:

let domain = "<tenant>.<region>.auth0.com"

​

Inscribir

Una inscripción es un vínculo entre el segundo factor y una cuenta de Auth0. Cuando una cuenta esté inscrita, deberás proporcionar el segundo factor necesario para verificar la identidad. Si tu aplicación aún no usa notificaciones push o no estás familiarizado con ellas, consulta Apple Push Notification Service Overview para obtener más información.

Para una inscripción necesitas la siguiente información, además del dominio de tu inquilino:

Variable	Descripción
Enrollment URI	Valor codificado en el código QR escaneado desde Guardian Web Widget o en el ticket de inscripción que se te envió por correo electrónico o SMS.
APNS Token	Token APNS de Apple para el dispositivo. Debe ser una cadena que contenga los 64 bytes (en formato hexadecimal).
Key Pair	Un par de claves RSA (privada/pública) que se usa para acreditar tu identidad ante Auth0 Guardian.

Después de tener esta información, puedes inscribir tu dispositivo:

Guardian
        .enroll(forDomain: "{yourTenantDomain}",
                usingUri: "{enrollmentUri}",
                notificationToken: "{apnsToken}",
                signingKey: signingKey,
                verificationKey: verificationKey
                )
        .start { result in
            switch result {
            case .success(let enrolledDevice):
                // éxito, tenemos los datos del dispositivo inscrito disponibles
            case .failure(let cause):
                // algo falló, revisa cause para ver qué salió mal
            }
        }

Si la operación se completa correctamente, obtendrás la información de inscripción, que debe almacenarse de forma segura en tu aplicación. Esta información incluye el identificador de inscripción y el token de la API de Guardian asociado a tu dispositivo para actualizar o eliminar tu inscripción.

​

Claves de firma y verificación

Guardian.swift proporciona una clase auxiliar para generar una clave de firma:

let signingKey = try DataRSAPrivateKey.new()

Esta clave solo existe en memoria, pero puedes obtener su representación Data y almacenarla de forma segura, por ejemplo, en una SQLiteDB cifrada:

// Almacenar datos
let data = signingKey.data
// realizar el almacenamiento

// Cargar desde el almacenamiento
let loadedKey = try DataRSAPrivateKey(data: data)

Pero si solo quieres almacenarlo en el llavero de iOS:

let signingKey = try KeychainRSAPrivateKey.new(with: "com.myapp.mytag")

El ejemplo anterior crea una clave y la almacena automáticamente bajo la etiqueta proporcionada. Si desea recuperarla, puede usar la etiqueta:

let signingKey = try KeychainRSAPrivateKey(tag: "com.myapp.mytag")

La clave de verificación se puede obtener simplemente de cualquier SigningKey, por ejemplo:

let verificationKey = try signingKey.verificationKey()

​

Permitir solicitudes de inicio de sesión

Una vez que haya configurado la inscripción, recibirá una notificación push cada vez que el usuario deba validar su identidad con MFA. Guardian proporciona un método para analizar los datos recibidos de APNs y devolver una instancia de Notification lista para usar.

if let notification = Guardian.notification(from: notificationPayload) {
    // hemos recibido una notificación push de Guardian
}

Una vez que tengas la instancia de la notificación, puedes aprobar fácilmente la solicitud de autenticación con el método allow. También necesitarás cierta información del dispositivo inscrito que obtuviste anteriormente. En caso de que tengas más de una inscripción, tendrás que encontrar la que tenga el mismo id que la notificación (la propiedad enrollmentId).

Cuando tengas la información, el parámetro device puede ser cualquier objeto que implemente el protocolo AuthenticatedDevice:

struct Authenticator: Guardian.AuthenticationDevice {
    let signingKey: SigningKey
    let localIdentifier: String
}

El identificador local es el id local del dispositivo; de forma predeterminada, al inscribirse se usa UIDevice.current.identifierForVendor. Luego, simplemente llama a:

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .allow(notification: notification)
        .start { result in
            switch result {
            case .success:
                // la solicitud de autenticación fue permitida exitosamente
            case .failure(let cause):
                // algo falló, revisa cause para ver qué salió mal
            }
        }

​

Rechazar solicitudes de inicio de sesión

Para denegar una solicitud de autenticación, llame a reject en su lugar. También puede enviar un motivo de rechazo opcional. El motivo de rechazo aparecerá en los registros de Guardian.

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .reject(notification: notification)
        // o reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // la solicitud de autenticación fue rechazada correctamente
            case .failure(let cause):
                // algo falló, revisa cause para ver qué salió mal
            }
        }

​

Eliminar la inscripción

Si desea eliminar una inscripción, por ejemplo, para deshabilitar MFA, puede realizar la siguiente solicitud:

Guardian
        .api(forDomain: "{yourTenantDomain}")
        .device(forEnrollmentId: "{userEnrollmentId}", token: "{enrollmentDeviceToken}")
        .delete()
        .start { result in
            switch result {
            case .success:
                // éxito, la inscripción fue eliminada
            case .failure(let cause):
                // algo falló, revisa cause para ver qué salió mal
            }
        }

​

Configurar la inscripción de OTP solo para móviles

Puede habilitar las contraseñas de un solo uso (OTP) como factor de MFA mediante el Auth0 Dashboard o la Management API. Esta opción no requiere un código QR y permite a los usuarios inscribirse manualmente.

Para invitar a un usuario a inscribirse, vaya a Auth0 Dashboard > User Management > Users y seleccione un usuario. Luego, acceda a la pestaña Details y use la sección Multi-Factor Authentication para enviar una invitación de inscripción.

​

Conectar un recurso

Puede conectar un recurso mediante el Auth0 Dashboard o el SDK de Guardian.

Usa Auth0 Dashboard

1. Accede a la pantalla de inicio de sesión de Auth0 y copia el code proporcionado o una clave similar codificada en base32 obtenida de otra fuente. En el siguiente paso, introducirás este code en una aplicación de autenticación.

   

2. Agrega el code que copiaste a una aplicación de autenticación, como Guardian.

Usa el SDK

1. Importa la biblioteca Guardian.

   import Guardian
   

2. Crea un generador de code.

   let codeGenerator = try Guardian.totp(
   
      base32Secret: enrollmentCode,  // Code de inscripción introducido por el usuario
   
      algorithm: .sha1			// Algoritmo utilizado por TOTP
   
   )
   

3. Obtén el code generado.

   codeGenerator.code()
   

​

Introduzca el código de un solo uso

En la pantalla de inicio de sesión de Auth0, introduzca el code que generó en el paso anterior.

Después de seleccionar Continuar, se muestra un mensaje indicando que su aplicación se ha añadido como factor de autenticación para su usuario.

​

Iniciar sesión con la aplicación

Después de inscribir el factor, el usuario podrá iniciar sesión con la aplicación. Primero, elija la aplicación Guardian como método de autenticación.

Luego, introduzca el código de un solo uso en la pantalla de inicio de sesión para verificar su identidad.