Añade autenticación a tu aplicación Flutter

Este tutorial te mostrará cómo integrar Logto en tu aplicación Flutter.

tip

El paquete SDK está disponible en pub.dev y en el repositorio de GitHub de Logto.
El proyecto de ejemplo está construido usando Flutter material. Puedes encontrarlo en pub.dev y en nuestro repositorio de GitHub.
El SDK es compatible solo con las plataformas Android e iOS.
El SDK v1.x es compatible con Dart 2.x. Para el SDK v2.x, necesitas actualizar tu versión de Dart a 3.x o superior.

Prerrequisitos

Una cuenta de Logto Cloud o un Logto autoalojado.
Una aplicación nativa de Logto creada.
Un entorno de desarrollo Flutter o Dart.

Instalación

pub.dev
GitHub

Puedes instalar el logto_dart_sdk package directamente usando el gestor de paquetes pub. Ejecuta el siguiente comando en la raíz de tu proyecto:

flutter pub get logto_dart_sdk

Si prefieres bifurcar tu propia versión del SDK, puedes clonar el repositorio directamente desde GitHub.

git clone https://github.com/logto-io/dart

Módulos

El logto_dart_sdk incluye dos módulos principales:

logto_core.dart Este módulo central proporciona las funciones e interfaces básicas para el SDK de Logto.
logto_client.dart Este módulo cliente ofrece una clase cliente de Logto de alto nivel para interactuar con el servidor de Logto.

Dependencias y configuraciones

Este SDK tiene las siguientes dependencias, algunas requieren configuraciones adicionales:

flutter_secure_storage

Usamos flutter_secure_storage para implementar el almacenamiento seguro de tokens persistente y multiplataforma.

Se utiliza Keychain para iOS
Se utiliza cifrado AES para Android.

Configurar la versión de Android

Establece el android:minSdkVersion a 18 en el archivo android/app/build.gradle de tu proyecto.

build.gradle
  android {
      ...

      defaultConfig {
          ...
          minSdkVersion 18
          ...
      }
  }

Deshabilitar autobackup

Por defecto, Android puede hacer una copia de seguridad de los datos en Google Drive automáticamente. Esto puede causar la excepción java.security.InvalidKeyException:Failed to unwrap key.

Para evitar esto, puedes deshabilitar la copia de seguridad automática para tu aplicación o excluir sharedprefs de FlutterSecureStorage.

Para deshabilitar la copia de seguridad automática, ve al archivo de manifiesto de tu aplicación y establece los atributos android:allowBackup y android:fullBackupContent en false.

AndroidManifest.xml
<manifest ... >
    ...
    <application
      android:allowBackup="false"
      android:fullBackupContent="false"
      ...
    >
        ...
    </application>
</manifest>

Excluir sharedprefs de FlutterSecureStorage.

Si necesitas mantener android:fullBackupContent para tu aplicación en lugar de deshabilitarlo, puedes excluir el directorio sharedprefs de la copia de seguridad. Consulta más detalles en la documentación de Android.

En tu archivo AndroidManifest.xml, agrega el atributo android:fullBackupContent al elemento <application>, como se muestra en el siguiente ejemplo. Este atributo apunta a un archivo XML que contiene reglas de copia de seguridad.
AndroidManifest.xml
```
<application ...
  android:fullBackupContent="@xml/backup_rules">
</application>
```
Crea un archivo XML llamado @xml/backup_rules en el directorio res/xml/. En este archivo, agrega reglas con los elementos <include> y <exclude>. El siguiente ejemplo respalda todas las preferencias compartidas excepto device.xml:
@xml/backup_rules
```
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
  <exclude domain="sharedpref" path="FlutterSecureStorage"/>
</full-backup-content>
```

Por favor, consulta flutter_secure_storage para más detalles.

flutter_web_auth

flutter_web_auth se utiliza detrás del SDK de flutter de Logto. Confiamos en su interfaz de interacción basada en webview para autenticar a los usuarios.

nota

Este plugin utiliza ASWebAuthenticationSession en iOS 12+ y macOS 10.15+, SFAuthenticationSession en iOS 11, Chrome Custom Tabs en Android y abre una nueva ventana en Web.

Registrar la URL de callback en Android

Para capturar la URL de callback desde la página web de inicio de sesión de Logto, necesitarás registrar tu redirectUri de inicio de sesión en tu archivo AndroidManifest.xml.

AndroidManifest.xml
<activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
    <intent-filter android:label="flutter_web_auth">
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        <data android:scheme="io.logto"/>
    </intent-filter>
</activity>

http.dart

Dado que el SDK necesita realizar solicitudes de red, necesitarás pasar un cliente HTTP al SDK. Puedes usar el http.Client predeterminado de http.dart o crear tu propio http.Client con configuraciones personalizadas.

  import 'package:http/http.dart' as http;

Integración

Inicializar LogtoClient

Importa el paquete logto_dart_sdk e inicializa la instancia de LogtoClient en la raíz de tu aplicación.

lib/main.dart
import 'package:logto_dart_sdk/logto_dart_sdk.dart';
import 'package:http/http.dart' as http;

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(title: 'Logto Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key, required this.title}) : super(key: key);
  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late LogtoClient logtoClient;

  void render() {
    // cambio de estado
  }

  // LogtoConfig
  final logtoConfig = const LogtoConfig(
    endpoint: "<your-logto-endpoint>",
    appId: "<your-app-id>"
  );

  void _init() {
    logtoClient = LogtoClient(
      config: logtoConfig,
      httpClient: http.Client(), // Cliente http opcional
    );
    render();
  }

  @override
  void initState() {
    super.initState();
    _init();
  }

  // ...
}

Implementar inicio de sesión

Antes de profundizar en los detalles, aquí tienes una visión general rápida de la experiencia del usuario final. El proceso de inicio de sesión se puede simplificar de la siguiente manera:

Tu aplicación invoca el método de inicio de sesión.
El usuario es redirigido a la página de inicio de sesión de Logto. Para aplicaciones nativas, se abre el navegador del sistema.
El usuario inicia sesión y es redirigido de vuelta a tu aplicación (configurada como el URI de redirección).

Sobre el inicio de sesión basado en redirección

Este proceso de autenticación sigue el protocolo OpenID Connect (OIDC), y Logto aplica medidas de seguridad estrictas para proteger el inicio de sesión del usuario.
Si tienes múltiples aplicaciones, puedes usar el mismo proveedor de identidad (Logto). Una vez que el usuario inicia sesión en una aplicación, Logto completará automáticamente el proceso de inicio de sesión cuando el usuario acceda a otra aplicación.

Para aprender más sobre la lógica y los beneficios del inicio de sesión basado en redirección, consulta Experiencia de inicio de sesión de Logto explicada.

Antes de comenzar, necesitas agregar un URI de redirección en la Consola de Administración para tu aplicación.

Vamos a cambiar a la página de detalles de la aplicación en Logto Console. Añade un URI de redirección io.logto://callback y haz clic en "Guardar cambios".

Para iOS, el esquema del URI de redirección realmente no importa ya que la clase ASWebAuthenticationSession escuchará el URI de redirección independientemente de si está registrado.
Para Android, el esquema del URI de redirección debe estar registrado en el archivo AndroidManifest.xml.

Después de configurar el URI de redirección, añadimos un botón de inicio de sesión a tu página, que llamará a la API logtoClient.signIn para invocar el flujo de inicio de sesión de Logto:

lib/main.dart
class _MyHomePageState extends State<MyHomePage> {
  // ...
  final redirectUri = 'io.logto://callback';

  @override
  Widget build(BuildContext context) {
    // ...

    Widget signInButton = TextButton(
      onPressed: () async {
        await logtoClient.signIn(redirectUri);
        render();
      },
      child: const Text('Sign In'),
    );

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            SelectableText('My Demo App'),
            signInButton,
          ],
        ),
      ),
    );
  }
}

Implementar cierre de sesión

Ahora vamos a añadir un botón de cierre de sesión en la página principal para que los usuarios puedan cerrar sesión en tu aplicación.

lib/main.dart
class _MyHomePageState extends State<MyHomePage> {
  // ...

  @override
  Widget build(BuildContext context) {
    // ...

    Widget signOutButton = TextButton(
      onPressed: () async {
        await logtoClient.signOut();
        render();
      },
      child: const Text('Sign Out'),
    );

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            SelectableText('My Demo App'),
            signInButton,
            signOutButton,
          ],
        ),
      ),
    );
  }
}

Manejar el estado de autenticación

Logto SDK proporciona un método asincrónico para verificar el estado de autenticación. El método es logtoClient.isAuthenticated. El método devuelve un valor booleano, true si el usuario está autenticado, de lo contrario false.

En el ejemplo, renderizamos condicionalmente los botones de inicio y cierre de sesión basándonos en el estado de autenticación. Ahora vamos a actualizar el método render en nuestro Widget para manejar el cambio de estado:

lib/main.dart
class _MyHomePageState extends State<MyHomePage> {
  // ...
  bool? isAuthenticated = false;

  void render() {
    setState(() async {
      isAuthenticated = await logtoClient.isAuthenticated;
    });
  }

  @override
  Widget build(BuildContext context) {
    // ...

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            SelectableText('My Demo App'),
            isAuthenticated == true ? signOutButton : signInButton,
          ],
        ),
      ),
    );
  }
}

Punto de control: Prueba tu aplicación

Ahora, puedes probar tu aplicación:

Ejecuta tu aplicación, verás el botón de inicio de sesión.
Haz clic en el botón de inicio de sesión, el SDK iniciará el proceso de inicio de sesión y te redirigirá a la página de inicio de sesión de Logto.
Después de iniciar sesión, serás redirigido de vuelta a tu aplicación y verás el botón de cierre de sesión.
Haz clic en el botón de cierre de sesión para limpiar el almacenamiento local y cerrar sesión.

Obtener información del usuario

Mostrar información del usuario

Para mostrar la información del usuario, puedes usar el getter logtoClient.idTokenClaims. Por ejemplo, en una aplicación Flutter:

lib/main.dart
class _MyHomePageState extends State<MyHomePage> {
  // ...

  @override
  Widget build(BuildContext context) {
    // ...

    Widget getUserInfoButton = TextButton(
      onPressed: () async {
        final userClaims = await logtoClient.idTokenClaims;
        print(userInfo);
      },
      child: const Text('Obtener información del usuario'),
    );

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            SelectableText('Mi Aplicación de Demostración'),
            isAuthenticated == true ? signOutButton : signInButton,
            isAuthenticated == true ? getUserInfoButton : const SizedBox.shrink(),
          ],
        ),
      ),
    );
  }
}

Solicitar reclamos adicionales

Es posible que encuentres que falta alguna información del usuario en el objeto devuelto desde client.idTokenClaims. Esto se debe a que OAuth 2.0 y OpenID Connect (OIDC) están diseñados para seguir el principio de privilegio mínimo (PoLP), y Logto está construido sobre estos estándares.

De forma predeterminada, se devuelven reclamos limitados. Si necesitas más información, puedes solicitar alcances adicionales para acceder a más reclamos.

info

Un "reclamo (Claim)" es una afirmación hecha sobre un sujeto; un "alcance (Scope)" es un grupo de reclamos. En el caso actual, un reclamo es una pieza de información sobre el usuario.

Aquí tienes un ejemplo no normativo de la relación alcance - reclamo:

tip

El reclamo "sub" significa "sujeto", que es el identificador único del usuario (es decir, el ID del usuario).

El SDK de Logto siempre solicitará tres alcances: openid, profile y offline_access.

Para solicitar alcances adicionales, puedes pasar los alcances al objeto LogtoConfig. Por ejemplo:

lib/main.dart
// LogtoConfig
final logtoConfig = const LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  scopes: ["email", "phone"],
);

También proporcionamos un enum LogtoUserScope incorporado en el paquete SDK para ayudarte a usar los alcances predefinidos.

// LogtoConfig
final logtoConfig = const LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  scopes: [LogtoUserScope.email.value, LogtoUserScope.phone.value],
);

Reclamos que necesitan solicitudes de red

Para evitar sobrecargar el Token de ID, algunos reclamos requieren solicitudes de red para ser obtenidos. Por ejemplo, el reclamo custom_data no se incluye en el objeto de usuario incluso si se solicita en los alcances. Para acceder a estos reclamos, puedes usar el método logtoClient.getUserInfo():

lib/main.dart
class _MyHomePageState extends State<MyHomePage> {
  // ...

  @override
  Widget build(BuildContext context) {
    // ...

    Widget getUserInfoButton = TextButton(
      onPressed: () async {
        final userInfo = await logtoClient.getUserInfo();
        print(userInfo);
      },
      child: const Text('Obtener información del usuario'),
    );

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            SelectableText('Mi Aplicación de Demostración'),
            isAuthenticated == true ? signOutButton : signInButton,
            isAuthenticated == true ? getUserInfoButton : const SizedBox.shrink(),
          ],
        ),
      ),
    );
  }
}

Este método obtendrá la información del usuario solicitando al endpoint de userinfo. Para aprender más sobre los alcances y reclamos disponibles, consulta la sección de Alcances y reclamos.

Alcances y reclamos

Logto utiliza las convenciones de alcances y reclamos (scopes and claims) de OIDC para definir los alcances y reclamos para obtener información del usuario del Token de ID y del endpoint userinfo de OIDC. Tanto "alcance" como "reclamo" son términos de las especificaciones de OAuth 2.0 y OpenID Connect (OIDC).

Aquí está la lista de alcances (Scopes) soportados y los reclamos (Claims) correspondientes:

openid

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
sub	`string`	El identificador único del usuario	No

profile

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
name	`string`	El nombre completo del usuario	No
username	`string`	El nombre de usuario del usuario	No
picture	`string`	URL de la foto de perfil del usuario final. Esta URL DEBE referirse a un archivo de imagen (por ejemplo, un archivo de imagen PNG, JPEG o GIF), en lugar de a una página web que contenga una imagen. Ten en cuenta que esta URL DEBERÍA referirse específicamente a una foto de perfil del usuario final adecuada para mostrar al describir al usuario final, en lugar de una foto arbitraria tomada por el usuario final.	No
created_at	`number`	Momento en que se creó el usuario final. El tiempo se representa como el número de milisegundos desde la época Unix (1970-01-01T00:00:00Z).	No
updated_at	`number`	Momento en que se actualizó por última vez la información del usuario final. El tiempo se representa como el número de milisegundos desde la época Unix (1970-01-01T00:00:00Z).	No

Otros reclamos estándar incluyen family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo y locale también se incluirán en el alcance profile sin necesidad de solicitar el endpoint de userinfo. Una diferencia en comparación con los reclamos anteriores es que estos reclamos solo se devolverán cuando sus valores no estén vacíos, mientras que los reclamos anteriores devolverán null si los valores están vacíos.

nota

A diferencia de los reclamos estándar, los reclamos created_at y updated_at utilizan milisegundos en lugar de segundos.

email

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
email	`string`	La dirección de correo electrónico del usuario	No
email_verified	`boolean`	Si la dirección de correo electrónico ha sido verificada	No

phone

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
phone_number	`string`	El número de teléfono del usuario	No
phone_number_verified	`boolean`	Si el número de teléfono ha sido verificado	No

address

Por favor, consulta el OpenID Connect Core 1.0 para los detalles del reclamo de dirección.

custom_data

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
custom_data	`object`	Los datos personalizados del usuario	Sí

identities

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
identities	`object`	Las identidades vinculadas del usuario	Sí
sso_identities	`array`	Las identidades SSO vinculadas del usuario	Sí

urn:logto:scope:organizations

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
organizations	`string[]`	Los IDs de las organizaciones a las que pertenece el usuario	No
organization_data	`object[]`	Los datos de las organizaciones a las que pertenece el usuario	Sí

urn:logto:scope:organization_roles

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
organization_roles	`string[]`	Los roles de organización a los que pertenece el usuario con el formato `<organization_id>:<role_name>`	No

Considerando el rendimiento y el tamaño de los datos, si "¿Necesita userinfo?" es "Sí", significa que el reclamo no aparecerá en el Token de ID, pero se devolverá en la respuesta del endpoint de userinfo.

Recursos de API y organizaciones

Recomendamos leer primero 🔐 Control de acceso basado en roles (RBAC) para entender los conceptos básicos de Logto RBAC y cómo configurar correctamente los recursos de API.

Configurar el cliente de Logto

Una vez que hayas configurado los recursos de API, puedes agregarlos al configurar Logto en tu aplicación:

lib/main.dart
// LogtoConfig
final logtoConfig = const LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  // Add your API resources
  resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
);

Cada recurso de API tiene sus propios permisos (alcances).

Por ejemplo, el recurso https://shopping.your-app.com/api tiene los permisos shopping:read y shopping:write, y el recurso https://store.your-app.com/api tiene los permisos store:read y store:write.

Para solicitar estos permisos, puedes agregarlos al configurar Logto en tu aplicación:

lib/main.dart
// LogtoConfig
final logtoConfig = const LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
  // Add your API resources' scopes
  scopes: ["shopping:read", "shopping:write", "store:read", "store:write"]
);

Puedes notar que los alcances se definen por separado de los recursos de API. Esto se debe a que Resource Indicators for OAuth 2.0 especifica que los alcances finales para la solicitud serán el producto cartesiano de todos los alcances en todos los servicios objetivo.

Así, en el caso anterior, los alcances se pueden simplificar desde la definición en Logto, ambos recursos de API pueden tener alcances read y write sin el prefijo. Luego, en la configuración de Logto:

lib/main.dart
// LogtoConfig
final logtoConfig = const LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
  // Alcances compartidos por todos los recursos
  scopes: ["read", "write"]
);

Para cada recurso de API, se solicitarán tanto los alcances read como write.

nota

Está bien solicitar alcances que no están definidos en los recursos de API. Por ejemplo, puedes solicitar el alcance email incluso si los recursos de API no tienen el alcance email disponible. Los alcances no disponibles serán ignorados de manera segura.

Después de un inicio de sesión exitoso, Logto emitirá los alcances apropiados a los recursos de API de acuerdo con los roles del usuario.

Obtener token de acceso para el recurso de API

Para obtener el token de acceso para un recurso de API específico, puedes usar el método getAccessToken:

lib/main.dart
Future<AccessToken?> getAccessToken(String resource) async {
  var token = await logtoClient.getAccessToken(resource: resource);

  return token;
}

Este método devolverá un token de acceso JWT que se puede usar para acceder al recurso de API cuando el usuario tiene permisos relacionados. Si el token de acceso en caché actual ha expirado, este método intentará automáticamente usar un token de actualización para obtener un nuevo token de acceso.

Obtener token de acceso para organizaciones

Al igual que los recursos de API, también puedes solicitar un token de acceso para organizaciones. Esto es útil cuando necesitas acceder a recursos que están definidos utilizando el alcance de la organización en lugar del alcance del recurso de API.

Si la organización es nueva para ti, por favor lee 🏢 Organizaciones (Multi-tenancy) para comenzar.

Necesitas añadir el alcance LogtoUserScope.Organizations al configurar el cliente Logto:

lib/main.dart
// LogtoConfig
final logtoConfig = const LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  scopes: [LogtoUserScopes.organizations.value]
);

Una vez que el usuario ha iniciado sesión, puedes obtener el token de organización para el usuario:

// Los IDs de organización válidos para el usuario se pueden encontrar en el reclamo del Token de ID `organizations`.
Future<AccessToken?> getOrganizationAccessToken(String organizationId) async {
  var token = await logtoClient.getOrganizationToken(organizationId);

  return token;
}

Lecturas adicionales

Flujos de usuario final: flujos de autenticación, flujos de cuenta y flujos de organización Configurar conectores Protege tu API

Prerrequisitos​

Instalación​

Módulos​

Dependencias y configuraciones​

Configurar la versión de Android​

Deshabilitar autobackup​

Registrar la URL de callback en Android​

Integración​

Inicializar LogtoClient​

Implementar inicio de sesión​

Implementar cierre de sesión​

Manejar el estado de autenticación​

Punto de control: Prueba tu aplicación​

Obtener información del usuario​

Mostrar información del usuario​

Solicitar reclamos adicionales​

Reclamos que necesitan solicitudes de red​

Alcances y reclamos​

Recursos de API y organizaciones​

Configurar el cliente de Logto​

Obtener token de acceso para el recurso de API​

Obtener token de acceso para organizaciones​

Lecturas adicionales​

Prerrequisitos

Instalación

Módulos

Dependencias y configuraciones

Configurar la versión de Android

Deshabilitar autobackup

Registrar la URL de callback en Android

Integración

Inicializar LogtoClient

Implementar inicio de sesión

Implementar cierre de sesión

Manejar el estado de autenticación

Punto de control: Prueba tu aplicación

Obtener información del usuario

Mostrar información del usuario

Solicitar reclamos adicionales

Reclamos que necesitan solicitudes de red

Alcances y reclamos

Recursos de API y organizaciones

Configurar el cliente de Logto

Obtener token de acceso para el recurso de API

Obtener token de acceso para organizaciones

Lecturas adicionales