Ajoutez l’authentification à votre application iOS (Swift)

remarque:

Ce guide suppose que vous avez créé une Application de type "Native app" dans la Console d'administration.

Installation

Utilisez l'URL suivante pour ajouter Logto SDK comme dépendance dans Swift Package Manager.

https://github.com/logto-io/swift.git

Depuis Xcode 11, vous pouvez importer directement un package Swift sans aucun outil supplémentaire.

Nous ne prenons pas en charge Carthage et CocoaPods pour le moment en raison de certains problèmes techniques.

Carthage

Carthage nécessite un fichier xcodeproj pour construire, mais swift package generate-xcodeproj signalera un échec car nous utilisons des cibles binaires pour les plugins sociaux natifs. Nous essaierons de trouver une solution plus tard.

CocoaPods

CocoaPods ne prend pas en charge la dépendance locale et le monorepo, il est donc difficile de créer un .podspec pour ce dépôt.

Intégration

Init `LogtoClient`

Initialisez le client en créant une instance LogtoClient avec un objet LogtoConfig.

ContentView.swift
import Logto
import LogtoClient

let config = try? LogtoConfig(
  endpoint: "<your-logto-endpoint>", // Par exemple, http://localhost:3001
  appId: "<your-app-id>"
)
let client = LogtoClient(useConfig: config)

info:

Par défaut, nous stockons les informations d'identification comme le Jeton d’identifiant (ID token) et le Jeton de rafraîchissement (Refresh token) dans le Trousseau. Ainsi, l'utilisateur n'a pas besoin de se reconnecter lorsqu'il revient.

Pour désactiver ce comportement, définissez usingPersistStorage sur false :

let config = try? LogtoConfig(
  // ...
  usingPersistStorage: false
)

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.

Configurer l'URI de redirection

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

info:

L'URI de redirection dans le SDK iOS est uniquement pour un usage interne. Il n'y a PAS BESOIN d'ajouter un schéma d'URL personnalisé jusqu'à ce qu'un connecteur le demande.

remarque:

Avant d'appeler .signInWithBrowser(redirectUri:), assurez-vous d'avoir correctement configuré l'URI de redirection dans la console d'administration.

Vous pouvez utiliser client.signInWithBrowser(redirectUri:) pour connecter l'utilisateur et client.signOut() pour déconnecter l'utilisateur.

Par exemple, dans une application SwiftUI :

ContentView.swift
struct ContentView: View {
  @State var isAuthenticated: Bool

  init() {
    isAuthenticated = client.isAuthenticated
  }

  var body: some View {
    VStack {
      if isAuthenticated {
        Button("Déconnexion") {
          Task { [self] in
            await client.signOut()
            isAuthenticated = false
          }
        }
      } else {
        Button("Connexion") {
          Task { [self] in
            do {
              try await client.signInWithBrowser(redirectUri: "${
                props.redirectUris[0] ?? 'io.logto://callback'
              }")
              isAuthenticated = true
            } catch let error as LogtoClientErrors.SignIn {
              // erreur survenue lors de la connexion
            } catch {
              // autres erreurs
            }
          }
        }
      }
    }
  }
}

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 des informations sur l'utilisateur

Afficher les informations de l'utilisateur

Pour afficher les informations de l'utilisateur, vous pouvez utiliser la méthode client.getIdTokenClaims(). Par exemple, dans une application SwiftUI :

ContentView.swift
struct ContentView: View {
  @State var isAuthenticated: Bool
  @State var name: String?

  init() {
    isAuthenticated = client.isAuthenticated
    name = try? client.getIdTokenClaims().name
  }

  var body: some View {
    VStack {
      if isAuthenticated {
        Text("Bienvenue, \(name)")
      } else {
        Text("Veuillez vous connecter")
      }
    }
  }
}

Demander des revendications supplémentaires

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

ContentView.swift
let config = try? LogtoConfig(
  endpoint: "<your-logto-endpoint>", // Par exemple http://localhost:3001
  appId: "<your-app-id>",
  scopes: [
    UserScope.Email.rawValue,
    UserScope.Phone.rawValue,
  ]
)

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

let claims = try? client.getIdTokenClaims()
// 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 client.fetchUserInfo() :

let userInfo = try? client.fetchUserInfo()
// 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

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 :

ContentView.swift
let config = try? LogtoConfig(
  endpoint: "<your-logto-endpoint>", // E.g. http://localhost:3001
  appId: "<your-app-id>",
  resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"], // Ajouter des ressources API
)
let client = LogtoClient(useConfig: config)

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 :

ContentView.swift
let config = try? LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  scopes: ["shopping:read", "shopping:write", "store:read", "store:write"],
  resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
)
let client = LogtoClient(useConfig: config)

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 :

ContentView.swift
let config = try? LogtoConfig(
  endpoint: "<your-logto-endpoint>",
  appId: "<your-app-id>",
  scopes: ["read", "write"],
  resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
)
let client = LogtoClient(useConfig: config)

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 :

ContentView.swift
let accessToken = try await client.getAccessToken(for: "https://shopping.your-app.com/api")

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.

Attacher le jeton d’accès aux en-têtes de requête

Placez le jeton dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN), et vous êtes prêt.

remarque:

Le flux d'intégration du jeton Bearer peut varier en fonction du framework ou du demandeur que vous utilisez. Choisissez votre propre méthode pour appliquer l'en-tête de requête Authorization.

await LogtoRequest.get(
  useSession: session,
  endpoint: userInfoEndpoint,
  headers: ["Authorization": "Bearer \(accessToken)"]
)

Lectures complémentaires

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

Installation​

Carthage​

CocoaPods​

Intégration​

Init LogtoClient​

Implémenter la connexion et la déconnexion​

Concernant la connexion basée sur la redirection​

Configurer l'URI de redirection​

Connexion et déconnexion​

Point de contrôle : Testez votre application​

Obtenir des informations sur 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​

Configurer le client Logto​

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

Attacher le jeton d’accès aux en-têtes de requête​

Lectures complémentaires​

Installation

Carthage

CocoaPods

Intégration

Init `LogtoClient`

Implémenter la connexion et la déconnexion

Concernant la connexion basée sur la redirection

Configurer l'URI de redirection

Connexion et déconnexion

Point de contrôle : Testez votre application

Obtenir des informations sur 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

Configurer le client Logto

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

Attacher le jeton d’accès aux en-têtes de requête

Lectures complémentaires