Aller au contenu principal

Ajoutez l’authentification à votre application Flutter

Ce tutoriel vous montrera comment intégrer Logto dans votre application Flutter.

astuce
  • Le package SDK est disponible sur pub.dev et le répertoire GitHub de Logto.
  • Le projet d'exemple est construit en utilisant Flutter material. Vous pouvez le trouver sur pub.dev et notre répertoire GitHub.
  • Le SDK est compatible uniquement avec les plateformes Android et iOS.
  • Le SDK v1.x est compatible avec Dart 2.x. Pour le SDK v2.x, vous devez mettre à jour votre version de Dart à 3.x ou supérieure.

Prérequis

Installation

Vous pouvez installer le logto_dart_sdk package directement en utilisant le gestionnaire de packages pub. Exécutez la commande suivante à la racine de votre projet :

flutter pub get logto_dart_sdk

Modules

Le logto_dart_sdk comprend deux modules principaux :

  • logto_core.dart Ce module de base fournit les fonctions et interfaces de base pour le SDK Logto.

  • logto_client.dart Ce module client offre une classe client Logto de haut niveau pour interagir avec le serveur Logto.

Dépendances et configurations

Ce SDK a les dépendances suivantes, certaines nécessitent des configurations supplémentaires :

flutter_secure_storage

Nous utilisons flutter_secure_storage pour implémenter le stockage sécurisé persistant de jetons multiplateforme.

  • Keychain est utilisé pour iOS
  • Le chiffrement AES est utilisé pour Android.

Configurer la version Android

Définissez android:minSdkVersion à 18 dans le fichier android/app/build.gradle de votre projet.

build.gradle
  android {
...

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

Désactiver la sauvegarde automatique

Par défaut, Android peut sauvegarder automatiquement les données sur Google Drive. Cela peut provoquer l'exception java.security.InvalidKeyException:Failed to unwrap key.

Pour éviter cela, vous pouvez désactiver la sauvegarde automatique pour votre application ou exclure sharedprefs de FlutterSecureStorage.

  1. Pour désactiver la sauvegarde automatique, allez dans le fichier manifeste de votre application et définissez les attributs android:allowBackup et android:fullBackupContent sur false.

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

  2. Exclure sharedprefs de FlutterSecureStorage.

    Si vous devez conserver android:fullBackupContent pour votre application plutôt que de le désactiver, vous pouvez exclure le répertoire sharedprefs de la sauvegarde. Voir plus de détails dans la documentation Android.

    Dans votre fichier AndroidManifest.xml, ajoutez l'attribut android:fullBackupContent à l'élément <application>, comme indiqué dans l'exemple suivant. Cet attribut pointe vers un fichier XML contenant des règles de sauvegarde.

    AndroidManifest.xml
    <application ...
    android:fullBackupContent="@xml/backup_rules">
    </application>

    Créez un fichier XML appelé @xml/backup_rules dans le répertoire res/xml/. Dans ce fichier, ajoutez des règles avec les éléments <include> et <exclude>. L'exemple suivant sauvegarde toutes les préférences partagées sauf device.xml :

    @xml/backup_rules
    <?xml version="1.0" encoding="utf-8"?>
    <full-backup-content>
    <exclude domain="sharedpref" path="FlutterSecureStorage"/>
    </full-backup-content>

Veuillez consulter flutter_secure_storage pour plus de détails.

flutter_web_auth

flutter_web_auth est utilisé derrière le SDK flutter de Logto. Nous nous appuyons sur son interface d'interaction basée sur webview pour authentifier les utilisateurs.

remarque

Ce plugin utilise ASWebAuthenticationSession sur iOS 12+ et macOS 10.15+, SFAuthenticationSession sur iOS 11, Chrome Custom Tabs sur Android et ouvre une nouvelle fenêtre sur le Web.

Enregistrer l'URL de rappel sur Android

Afin de capturer l'URL de rappel depuis la page de connexion de Logto, vous devrez enregistrer votre redirectUri de connexion dans votre fichier 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

Étant donné que le SDK doit effectuer des requêtes réseau, vous devrez passer un client HTTP au SDK. Vous pouvez utiliser le http.Client par défaut de http.dart ou créer votre propre http.Client avec des configurations personnalisées.


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

Intégration

Initialiser LogtoClient

Importez le package logto_dart_sdk et initialisez l'instance LogtoClient à la racine de votre application.

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);


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;


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

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

void render() {
// changement d'état
}

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

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


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

// ...
}

Implémenter la connexion

Avant de plonger dans les détails, voici un aperçu rapide de l'Expérience utilisateur. Le processus de connexion peut être simplifié comme suit :

  1. Votre application lance la méthode de connexion.
  2. L'utilisateur est redirigé vers la page de connexion Logto. Pour les applications natives, le navigateur système est ouvert.
  3. L'utilisateur se connecte et est redirigé vers votre application (configurée comme l'URI de redirection).
Concernant la connexion basée sur la redirection
  1. Ce processus d'authentification (Authentication) suit le protocole OpenID Connect (OIDC), et Logto applique des mesures de sécurité strictes pour protéger la connexion utilisateur.
  2. Si vous avez plusieurs applications, vous pouvez utiliser le même fournisseur d’identité (Logto). Une fois que l'utilisateur se connecte à une application, Logto complétera automatiquement le processus de connexion lorsque l'utilisateur accède à une autre application.

Pour en savoir plus sur la logique et les avantages de la connexion basée sur la redirection, consultez Expérience de connexion Logto expliquée.


Avant de commencer, vous devez ajouter un URI de redirection dans la console d'administration pour votre application.

Passons à la page des détails de l'application de Logto Console. Ajoutez une URI de redirection io.logto://callback et cliquez sur "Enregistrer les modifications".

URI de redirection dans Logto Console
  • Pour iOS, le schéma de l'URI de redirection n'a pas vraiment d'importance puisque la classe ASWebAuthenticationSession écoutera l'URI de redirection, qu'il soit enregistré ou non.
  • Pour Android, le schéma de l'URI de redirection doit être enregistré dans le fichier AndroidManifest.xml.

Une fois l'URI de redirection configuré, nous ajoutons un bouton de connexion à votre page, qui appellera l'API logtoClient.signIn pour invoquer le flux de connexion Logto :

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


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,
],
),
),
);
}
}

Implémenter la déconnexion

Ajoutons maintenant un bouton de déconnexion sur la page principale pour que les utilisateurs puissent se déconnecter de votre application.

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


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,
],
),
),
);
}
}

Gérer le statut d'authentification

Le SDK Logto fournit une méthode asynchrone pour vérifier le statut d'authentification. La méthode est logtoClient.isAuthenticated. La méthode retourne une valeur booléenne, true si l'utilisateur est authentifié, sinon false.

Dans l'exemple, nous rendons conditionnellement les boutons de connexion et de déconnexion en fonction du statut d'authentification. Mettons maintenant à jour la méthode render dans notre Widget pour gérer le changement d'état :

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

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


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,
],
),
),
);
}
}

Point de contrôle : Testez votre application

Maintenant, vous pouvez tester votre application :

  1. Exécutez votre application, vous verrez le bouton de connexion.
  2. Cliquez sur le bouton de connexion, le SDK initiera le processus de connexion et vous redirigera vers la page de connexion Logto.
  3. Après vous être connecté, vous serez redirigé vers votre application et verrez le bouton de déconnexion.
  4. Cliquez sur le bouton de déconnexion pour effacer le stockage local et vous déconnecter.

Obtenir des informations utilisateur

Afficher les informations de l'utilisateur

Pour afficher les informations de l'utilisateur, vous pouvez utiliser le getter logtoClient.idTokenClaims. Par exemple, dans une application Flutter :

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


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

Widget getUserInfoButton = TextButton(
onPressed: () async {
final userClaims = await logtoClient.idTokenClaims;
print(userInfo);
},
child: const Text('Obtenir les informations de l’utilisateur'),
);

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

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par client.idTokenClaims. Cela est dû au fait que OAuth 2.0 et OpenID Connect (OIDC) sont conçus pour suivre le principe du moindre privilège (PoLP), et Logto est construit sur ces normes.

Par défaut, des revendications limitées sont retournées. Si vous avez besoin de plus d'informations, vous pouvez demander des portées supplémentaires pour accéder à plus de revendications.

info

Une "revendication" est une assertion faite à propos d'un sujet ; une "portée" est un groupe de revendications. Dans le cas actuel, une revendication est une information sur l'utilisateur.

Voici un exemple non normatif de la relation portée - revendication :

astuce

La revendication "sub" signifie "sujet", qui est l'identifiant unique de l'utilisateur (c'est-à-dire l'ID utilisateur).

Le SDK Logto demandera toujours trois portées : openid, profile et offline_access.

Pour demander des portées supplémentaires, vous pouvez passer les portées à l'objet LogtoConfig. Par exemple :

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

Nous fournissons également une énumération intégrée LogtoUserScope dans le package SDK pour vous aider à utiliser les portées prédéfinies.

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

Revendications nécessitant des requêtes réseau

Pour éviter de surcharger le jeton d’identifiant (ID token), certaines revendications nécessitent des requêtes réseau pour être récupérées. Par exemple, la revendication custom_data n'est pas incluse dans l'objet utilisateur même si elle est demandée dans les portées. Pour accéder à ces revendications, vous pouvez utiliser la méthode logtoClient.getUserInfo() :

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


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

Widget getUserInfoButton = TextButton(
onPressed: () async {
final userInfo = await logtoClient.getUserInfo();
print(userInfo);
},
child: const Text('Obtenir les informations de l’utilisateur'),
);

return Scaffold(
appBar: AppBar(
title: Text(widget.title),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
SelectableText('Mon application de démonstration'),
isAuthenticated == true ? signOutButton : signInButton,
isAuthenticated == true ? getUserInfoButton : const SizedBox.shrink(),
],
),
),
);
}
}
Cette méthode récupérera les informations de l'utilisateur en faisant une requête à l' point de terminaison userinfo. Pour en savoir plus sur les portées et revendications disponibles, consultez la section Portées et revendications.

Portées et revendications

Logto utilise les conventions de portées et revendications OIDC pour définir les Portées et Revendications pour récupérer les informations utilisateur à partir du Jeton d’identifiant et du point de terminaison OIDC userinfo. Les termes "Portée" et "Revendication" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).

Voici la liste des Portées (Scopes) prises en charge et les Revendications (Claims) correspondantes :

openid

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
substringL'identifiant unique de l'utilisateurNon

profile

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
namestringLe nom complet de l'utilisateurNon
usernamestringLe nom d'utilisateur de l'utilisateurNon
picturestringURL de la photo de profil de l'utilisateur final. Cette URL DOIT faire référence à un fichier image (par exemple, un fichier image PNG, JPEG ou GIF), plutôt qu'à une page Web contenant une image. Notez que cette URL DOIT spécifiquement référencer une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, plutôt qu'une photo arbitraire prise par l'utilisateur final.Non
created_atnumberHeure à laquelle l'utilisateur final a été créé. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).Non
updated_atnumberHeure à laquelle les informations de l'utilisateur final ont été mises à jour pour la dernière fois. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).Non

D'autres revendications standard incluent family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, et locale seront également incluses dans la portée profile sans avoir besoin de demander le point de terminaison userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront renvoyées que lorsque leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus renverront null si les valeurs sont vides.

remarque

Contrairement aux revendications standard, les revendications created_at et updated_at utilisent des millisecondes au lieu de secondes.

email

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
emailstringL'adresse e-mail de l'utilisateurNon
email_verifiedbooleanSi l'adresse e-mail a été vérifiéeNon

phone

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
phone_numberstringLe numéro de téléphone de l'utilisateurNon
phone_number_verifiedbooleanSi le numéro de téléphone a été vérifiéNon

address

Veuillez vous référer à OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.

custom_data

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
custom_dataobjectLes données personnalisées de l'utilisateurOui

identities

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
identitiesobjectLes identités liées de l'utilisateurOui
sso_identitiesarrayLes identités SSO liées de l'utilisateurOui

urn:logto:scope:organizations

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
organizationsstring[]Les identifiants d'organisation auxquels l'utilisateur appartientNon
organization_dataobject[]Les données d'organisation auxquelles l'utilisateur appartientOui

urn:logto:scope:organization_roles

Nom de la revendicationTypeDescriptionBesoin d'userinfo ?
organization_rolesstring[]Les rôles d'organisation auxquels l'utilisateur appartient avec le format <organization_id>:<role_name>Non

En considérant la performance et la taille des données, si "Besoin d'userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le Jeton d’identifiant (ID token), mais sera renvoyée dans la réponse du point de terminaison userinfo.

Ressources API et organisations

Nous vous recommandons de lire d'abord 🔐 Contrôle d’accès basé sur les rôles (RBAC) pour comprendre les concepts de base de Logto RBAC et comment configurer correctement les ressources API.

Configurer le client Logto

Une fois que vous avez configuré les ressources API, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

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

Chaque ressource API a ses propres permissions (portées).

Par exemple, la ressource https://shopping.your-app.com/api a les permissions shopping:read et shopping:write, et la ressource https://store.your-app.com/api a les permissions store:read et store:write.

Pour demander ces permissions, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

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"],
// Ajoutez les portées de vos ressources API
scopes: ["shopping:read", "shopping:write", "store:read", "store:write"]
);

Vous pouvez remarquer que les portées sont définies séparément des ressources API. Cela est dû au fait que les Indicateurs de ressource pour OAuth 2.0 spécifient que les portées finales pour la requête seront le produit cartésien de toutes les portées de tous les services cibles.

Ainsi, dans le cas ci-dessus, les portées peuvent être simplifiées à partir de la définition dans Logto, les deux ressources API peuvent avoir les portées read et write sans le préfixe. Ensuite, dans la configuration 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"],
// Portées partagées par toutes les ressources
scopes: ["read", "write"]
);

Pour chaque ressource API, il demandera à la fois les portées read et write.

remarque

Il est acceptable de demander des portées qui ne sont pas définies dans les ressources API. Par exemple, vous pouvez demander la portée email même si les ressources API n'ont pas la portée email disponible. Les portées non disponibles seront ignorées en toute sécurité.

Après une connexion réussie, Logto émettra les portées appropriées aux ressources API en fonction des rôles de l'utilisateur.

Récupérer le jeton d’accès pour la ressource API

Pour récupérer le jeton d’accès pour une ressource API spécifique, vous pouvez utiliser la méthode getAccessToken :

lib/main.dart
Future<Jeton d’accès?> getAccessToken(String resource) async {
var token = await logtoClient.getAccessToken(resource: resource);

return token;
}

Cette méthode renverra un jeton d’accès JWT qui peut être utilisé pour accéder à la ressource API lorsque l’utilisateur a les Permissions associées. Si le jeton d’accès mis en cache actuel a expiré, cette méthode essaiera automatiquement d’utiliser un jeton de rafraîchissement pour obtenir un nouveau jeton d’accès.

Récupérer un jeton d’accès pour les organisations

Tout comme les ressources API, vous pouvez également demander un jeton d’accès pour les organisations. Cela est utile lorsque vous devez accéder à des ressources définies en utilisant la portée d’organisation au lieu de la portée de ressource API.

Si l'Organisation est nouvelle pour vous, veuillez lire 🏢 Organisations (Multi-tenancy) pour commencer.

Vous devez ajouter la portée LogtoUserScope.Organizations lors de la configuration du client Logto :

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

Une fois l'utilisateur connecté, vous pouvez récupérer le jeton d’organisation pour l'utilisateur :

// Les identifiants d’ organisation valides pour l’utilisateur peuvent être trouvés dans la revendication de jeton d’identifiant `organizations`.
Future<AccessToken?> getOrganizationAccessToken(String organizationId) async {
var token = await logtoClient.getOrganizationToken(organizationId);

return token;
}

Lectures complémentaires

Flux utilisateur final : flux d'authentification, flux de compte et flux d'organisation Configurer les connecteurs Protéger votre API