Ajoutez l’authentification à votre application Android (Kotlin/Java)

Ce guide vous montrera comment intégrer Logto dans votre application Android.

astuce:

L'exemple est basé sur le système View et le modèle View, mais les concepts sont les mêmes lors de l'utilisation de Jetpack Compose.
L'exemple est écrit en Kotlin, mais les concepts sont les mêmes pour Java.
Les projets d'exemple en Kotlin et en Java sont disponibles sur notre répertoire SDK.
La vidéo tutorielle est disponible sur notre chaîne YouTube.

Prérequis

Un compte Logto Cloud ou un Logto auto-hébergé.
Une application native Logto créée.
Un projet d'application Android Kotlin.

Installation

remarque:

Le niveau API Android minimal pris en charge par Logto Android SDK est le niveau 24.

Avant d'installer Logto Android SDK, assurez-vous que mavenCentral() est ajouté à votre configuration de dépôt dans le fichier de construction du projet Gradle :

settings.gradle.kts
dependencyResolutionManagement {
  repositories {
    mavenCentral()
  }
}

Ajoutez Logto Android SDK à vos dépendances :

Kotlin
Groovy

build.gradle.kts
dependencies {
  implementation("io.logto.sdk:android:1.1.3")
}

build.gradle
dependencies {
  implementation 'io.logto.sdk:android:1.1.3'
}

Étant donné que le SDK nécessite un accès à Internet, vous devez ajouter la permission suivante à votre fichier AndroidManifest.xml :

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools">

  <!-- ajouter la permission internet -->
  <uses-permission android:name="android.permission.INTERNET" />

  <!-- autres configurations... -->
</manifest>

Intégration

Init LogtoClient

Créez un LogtoViewModel.kt et initialisez LogtoClient dans ce modèle de vue :

LogtoViewModel.kt
//...avec d'autres imports
import io.logto.sdk.android.LogtoClient
import io.logto.sdk.android.type.LogtoConfig

class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    private val logtoConfig = LogtoConfig(
          endpoint = "<votre-point-de-terminaison-logto>",
          appId = "<votre-id-app>",
          scopes = null,
          resources = null,
          usingPersistStorage = true,
    )

    private val logtoClient = LogtoClient(logtoConfig, application)

    companion object {
        val Factory: ViewModelProvider.Factory = object : ViewModelProvider.Factory {
            @Suppress("UNCHECKED_CAST")
            override fun <T : ViewModel> create(
                modelClass: Class<T>,
                extras: CreationExtras
            ): T {
                // Obtenez l'objet Application à partir des extras
                val application = checkNotNull(extras[APPLICATION_KEY])
                return LogtoViewModel(application) as T
            }
        }
    }
}

ensuite, créez un LogtoViewModel pour votre MainActivity.kt :

MainActivity.kt
//...avec d'autres imports
class MainActivity : AppCompatActivity() {
    private val logtoViewModel: LogtoViewModel by viewModels { LogtoViewModel.Factory }
    //...autres codes
}

Configurer l'URI de redirection

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

Votre application lance la méthode de connexion.
L’utilisateur est redirigé vers la page de connexion Logto. Pour les applications natives, le navigateur système est ouvert.
L’utilisateur se connecte et est redirigé vers votre application (configurée comme l’URI de redirection).

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.
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.

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

Dans Android, l'URI de redirection suit le modèle : $(LOGTO_REDIRECT_SCHEME)://$(YOUR_APP_PACKAGE)/callback :

Le LOGTO_REDIRECT_SCHEME doit être un schéma personnalisé au format de domaine inversé.
Le YOUR_APP_PACKAGE est le nom de votre package d'application.

En supposant que vous traitiez io.logto.android comme le LOGTO_REDIRECT_SCHEME personnalisé, et io.logto.sample comme le nom de votre package d'application, l'URI de redirection devrait être io.logto.android://io.logto.sample/callback.

remarque:

Avant d'appeler logtoClient.signIn, assurez-vous d'avoir correctement configuré l'URI de redirection dans la console d'administration.

Vous pouvez utiliser logtoClient.signIn pour connecter l'utilisateur et logtoClient.signOut pour déconnecter l'utilisateur.

Par exemple, dans une application Android :

LogtoModelView.kt
//...avec d'autres imports
class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    // ...autres codes

    // Ajouter une donnée en direct pour observer le statut d'authentification
    private val _authenticated = MutableLiveData(logtoClient.isAuthenticated)
    val authenticated: LiveData<Boolean>
        get() = _authenticated

    fun signIn(context: Activity) {
        logtoClient.signIn(context, "io.logto.android://io.logto.sample/callback") { logtoException ->
            logtoException?.let { println(it) }
            // Mettre à jour la donnée en direct
            _authenticated.postValue(logtoClient.isAuthenticated)
        }
    }

    fun signOut() {
        logtoClient.signOut { logtoException ->
            logtoException?.let { println(it) }
            // Mettre à jour la donnée en direct
            _authenticated.postValue(logtoClient.isAuthenticated)
        }
    }
}

Ensuite, appelez les méthodes signIn et signOut dans votre activité :

MainActivity.kt
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        //...autres codes

        // Supposons que vous ayez un bouton avec l'identifiant "sign_in_button" dans votre mise en page
        val signInButton = findViewById<Button>(R.id.sign_in_button)
        signInButton.setOnClickListener {
            logtoViewModel.signIn(this)
        }

        // Supposons que vous ayez un bouton avec l'identifiant "sign_out_button" dans votre mise en page
        val signOutButton = findViewById<Button>(R.id.sign_out_button)
        signOutButton.setOnClickListener {
            if (logtoViewModel.authenticated) { // Vérifiez si l'utilisateur est authentifié
                logtoViewModel.signOut()
            }
        }

        // Observez le statut d'authentification pour mettre à jour l'interface utilisateur
        logtoViewModel.authenticated.observe(this) { authenticated ->
            if (authenticated) {
                // L'utilisateur est authentifié
                signInButton.visibility = View.GONE
                signOutButton.visibility = View.VISIBLE
            } else {
                // L'utilisateur n'est pas authentifié
                signInButton.visibility = View.VISIBLE
                signOutButton.visibility = View.GONE
            }
        }

    }
}

Point de contrôle : Testez votre application

Maintenant, vous pouvez tester votre application :

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

Obtenir les informations de l'utilisateur

Afficher les informations de l'utilisateur

Pour afficher les informations de l'utilisateur, vous pouvez utiliser la méthode logtoClient.getIdTokenClaims(). Par exemple, vous pouvez obtenir les informations de l'utilisateur dans un ViewModel, puis les afficher dans votre activité :

LogtoModelView.kt
class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    // ...autres codes

    // Ajouter une donnée en direct pour observer les revendications du jeton d'identifiant
    private val _idTokenClaims = MutableLiveData<IdTokenClaims>()
    val idTokenClaims: LiveData<IdTokenClaims>
        get() = _idTokenClaims

    fun getIdTokenClaims() {
        logtoClient.getIdTokenClaims { logtoException, idTokenClaims ->
            logtoException?.let { _logtoException.postValue(it) } ?: _idTokenClaims.postValue(idTokenClaims)
        }
    }
}

MainActivity.kt
//...avec d'autres imports
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        //...autres codes

        // Supposons que vous ayez une vue de texte avec l'identifiant `user_info_text_view` dans votre mise en page
        val userInfoResponseTextView: TextView = findViewById(R.id.user_info_text_view)
        logtoViewModel.userInfoResponse.observe(this) { userInfoResponse ->
            userInfoResponseTextView.text = if (userInfoResponse !== null) {
                val json = Gson().toJson(userInfoResponse, UserInfoResponse::class.java)
                JSONObject(json).toString(2)
            } else {
                ""
            }
        }
    }
}

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par logtoClient.getIdTokenClaims(). 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 affirmation 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 :

LogtoViewModel.kt
private val logtoConfig = LogtoConfig(
    // ...autres configurations
    scopes = listOf("email", "phone"), // ou `listOf(UserScope.EMAIL, UserScope.PHONE)`
)

Ensuite, vous pouvez accéder aux revendications supplémentaires dans la valeur de retour de logtoClient.getIdTokenClaims() :

logtoClient.getIdTokenClaims { logtoException, idTokenClaims ->
    println("IdTokenClaims:$idTokenClaims")
}
// Vous pouvez maintenant accéder aux revendications supplémentaires `claims.email`, `claims.phone`, etc.

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.fetchUserInfo() :

LogtoViewModel.kt
logtoClient.fetchUserInfo {_, userInfoResponse ->
  println("UserInfoResponse:$userInfoResponse")
}
// Vous pouvez maintenant accéder à la revendication `userInfo.custom_data`

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 OIDC sur les portées (scopes) et revendications (claims) pour définir les portées et revendications permettant de récupérer les informations utilisateur depuis le jeton d’identifiant (ID token) et le point de terminaison OIDC userinfo. Les termes "portée (Scope)" et "revendication (Claim)" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).

Pour les revendications OIDC standard, leur inclusion dans le jeton d’identifiant est strictement déterminée par les portées demandées. Les revendications étendues (telles que custom_data et organizations) peuvent être configurées en plus pour apparaître dans le jeton d’identifiant via les paramètres Jeton d’identifiant personnalisé.

Voici la liste des portées prises en charge et les revendications correspondantes :

Portées OIDC standard

openid (par défaut)

Nom de la revendication	Type	Description
sub	`string`	L'identifiant unique de l'utilisateur

profile (par défaut)

Nom de la revendication	Type	Description
name	`string`	Le nom complet de l'utilisateur
username	`string`	Le nom d'utilisateur de l'utilisateur
picture	`string`	URL de la photo de profil de l'utilisateur final. Cette URL DOIT référencer un fichier image (par exemple, un fichier PNG, JPEG ou GIF), plutôt qu'une page Web contenant une image. Notez que cette URL DOIT référencer spécifiquement une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, et non une photo quelconque prise par l'utilisateur final.
created_at	`number`	Date de création de l'utilisateur final. Le temps est représenté par le nombre de millisecondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z).
updated_at	`number`	Date de la dernière mise à jour des informations de l'utilisateur final. Le temps est représenté par le nombre de millisecondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z).

D'autres revendications standard telles que 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 l'endpoint userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront retournées que si leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus retourneront null si les valeurs sont vides.

remarque:

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

email

Nom de la revendication	Type	Description
email	`string`	L'adresse e-mail de l'utilisateur
email_verified	`boolean`	Si l'adresse e-mail a été vérifiée

phone

Nom de la revendication	Type	Description
phone_number	`string`	Le numéro de téléphone de l'utilisateur
phone_number_verified	`boolean`	Si le numéro de téléphone a été vérifié

address

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

info:

Les portées marquées (par défaut) sont toujours demandées par le SDK Logto. Les revendications sous les portées OIDC standard sont toujours incluses dans le jeton d’identifiant lorsque la portée correspondante est demandée — elles ne peuvent pas être désactivées.

Portées étendues

Les portées suivantes sont étendues par Logto et retourneront des revendications via l’endpoint userinfo. Ces revendications peuvent également être configurées pour être incluses directement dans le jeton d’identifiant via Console > JWT personnalisé. Voir Jeton d’identifiant personnalisé pour plus de détails.

custom_data

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
custom_data	`object`	Les données personnalisées de l'utilisateur

identities

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
identities	`object`	Les identités liées de l'utilisateur
sso_identities	`array`	Les identités SSO liées de l'utilisateur

roles

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
roles	`string[]`	Les rôles de l'utilisateur	✅

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
organizations	`string[]`	Les identifiants d’organisation auxquels l'utilisateur appartient	✅
organization_data	`object[]`	Les données d’organisation auxquelles l'utilisateur appartient

remarque:

Ces revendications d’organisation peuvent également être récupérées via l’endpoint userinfo lors de l’utilisation d’un jeton opaque. Cependant, les jetons opaques ne peuvent pas être utilisés comme jetons d’organisation pour accéder à des ressources spécifiques à une organisation. Voir Jeton opaque et organisations pour plus de détails.

urn:logto:scope:organization_roles

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
organization_roles	`string[]`	Les rôles d’organisation auxquels l'utilisateur appartient au format `<organization_id>:<role_name>`	✅

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 :

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    //...other configs
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"), // Ajouter des ressources 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 :

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    // ..other configs
    scopes = listOf("shopping:read", "shopping:write", "store:read", "store:write"),
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"),
)

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 :

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf("read", "write"),
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"),
)

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 :

LogtoViewModel.kt
logtoClient.getAccessToken("https://shopping.your-app.com/api") { logtoException, jetonD’accès ->
    logtoException?.let { println(it) }
    jetonD’accès?.let { println(it) }
}

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 les jetons d’organisation

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

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

LogtoViewModel.kt
val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf(UserScope.Organisations),
)

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

LogtoViewModel.kt
// Remplacez le paramètre par un ID d’organisation valide.
// Les ID d’organisations valides pour l’utilisateur peuvent être trouvés dans la revendication de jeton d’identifiant `organizations`.
logtoClient.getOrganizationToken("organization-id") { logtoException, organizationToken ->
    logtoException?.let { println(it) }
    organizationToken?.let { println(it) }
}

// ou
logtoClient.getOrganizationTokenClaims("organization-id") { logtoException, claims ->
    logtoException?.let { println(it) }
    claims?.let { println(it) }
}

Ressources API d’organisation

Pour récupérer un jeton d’accès (Access token) pour une ressource API dans une organisation, vous pouvez utiliser la méthode getAccessToken avec à la fois la ressource API et l’ID de l’organisation comme paramètres :

LogtoViewModel.kt
logtoClient.getAccessToken(
  'https://shopping.your-app.com/api',
  organizationId
) { logtoException, accessToken ->
    println("AccessToken:$accessToken")
}

Lectures complémentaires

Parcours utilisateur final : flux d’authentification, flux de compte et flux d’organisation Configurer les connecteurs Autorisation (Authorization)

Prérequis​

Installation​

Intégration​

Init LogtoClient​

Configurer l'URI de redirection​

Concernant la connexion basée sur la redirection​

Implémenter la connexion et la déconnexion​

Point de contrôle : Testez votre application​

Obtenir les informations de l'utilisateur​

Afficher les informations de l'utilisateur​

Demander des revendications supplémentaires​

Revendications nécessitant des requêtes réseau​

Portées et revendications​

Portées OIDC standard​

Portées étendues​

Ressources API et organisations​

Configurer le client Logto​

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

Récupérer les jetons d’organisation​

Ressources API d’organisation​

Lectures complémentaires​

Prérequis

Installation

Intégration

Init LogtoClient

Configurer l'URI de redirection

Concernant la connexion basée sur la redirection

Implémenter la connexion et la déconnexion

Point de contrôle : Testez votre application

Obtenir les informations de l'utilisateur

Afficher les informations de l'utilisateur

Demander des revendications supplémentaires

Revendications nécessitant des requêtes réseau

Portées et revendications

Portées OIDC standard

Portées étendues

Ressources API et organisations

Configurer le client Logto

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

Récupérer les jetons d’organisation

Ressources API d’organisation

Lectures complémentaires