## Introduction [Logto](https://logto.io/) offre à nos développeurs et groupes commerciaux une solution complète de gestion des identités et des accès des clients (CIAM). Nous proposons une large gamme de SDK prêts à l'emploi pour différentes plateformes et cadres d'application. Combiné à notre service cloud Logto, vous pouvez établir sans effort un flux d'autorisation d'utilisateur hautement sécurisé pour votre application en quelques minutes. En tant qu'entreprise née de la communauté des développeurs, Logto embrasse et valorise notre engagement communautaire. En plus de ces SDK officiellement développés par Logto, nous encourageons continuellement et accueillons chaleureusement les développeurs de la communauté à apporter leur expertise en créant des SDK plus diversifiés et conviviaux, répondant aux besoins uniques de diverses plateformes et cadres. Dans cet article, nous allons brièvement montrer comment implémenter un SDK d'authentification standard OIDC étape par étape. Créez votre application dans Logto ## Contexte Le flux OpenID Connect (OIDC) est un protocole d'authentification qui s'appuie sur le cadre OAuth 2.0 pour fournir une vérification d'identité et des capacités de connexion unique. Il permet aux utilisateurs de s'authentifier eux-mêmes auprès d'une application et d'obtenir une autorisation pour un accès ultérieur à toute ressource privée de manière sécurisée. Veuillez vous référer aux spécifications OIDC pour plus de détails. ### Workflow Un flux de code d'autorisation standard comprend les étapes suivantes : ```mermaid sequenceDiagram actor user as Utilisateur final participant app as Application Client participant server as Serveur d'Autorisation participant resource as Ressources Privées user ->> app: visiteur anonyme se connecte app ->> server: envoyer la demande d'authentification server -->> user: rediriger vers la page de connexion de l'utilisateur user ->> server: se connecter avec les identifiants server -->> app: rediriger de nouveau vers l'application client avec le code d'autorisation app ->> server: demande d'échange de jetons avec le code d'autorisation server ->> app: accorder id_token, access_token et refresh_token app -->> user: authentifié app ->> resource: demande d'API privée avec access_token resource --> server: sync signing key resource -->> resource: validation du jeton resource ->> app: 200 OK ``` #### Flow d'authentification 1. **L'utilisateur déclenche la demande de connexion :** Un utilisateur anonyme arrive sur votre application depuis une entrée publique. Il tente de s'authentifier et peut-être de demander l'accès à une ressource protégée sur une application ou un service tiers. 2. **Authentification de l'utilisateur :** L'application cliente génère un URI d'authentification et envoie une demande au serveur d'autorisation, qui redirige l'utilisateur vers sa page de connexion. L'utilisateur interagit avec la page de connexion en utilisant un large éventail de méthodes de connexion et est authentifié par le serveur d'autorisation. 3. **Gérer la redirection de connexion :** Suite à une authentification réussie, l'utilisateur sera redirigé vers votre application avec un `code d'autorisation` accordé. Ce `code d'autorisation` contient toutes les permissions pertinentes liées au statut d'authentification et aux données d'autorisation demandées. 4. **Echange de jetons :** Demande d'échange de jetons en utilisant le `code d'autorisation` extrait de l'adresse de redirection ci-dessus. En retour : - `id_token` : Un JWT signé numériquement qui contient des informations d'identité sur l'utilisateur authentifié. - `access_token` : Un `access_token` opaque qui peut être utilisé pour accéder au point de terminaison des informations de base de l'utilisateur. - `refresh_token` : Jeton d'identification permettant à l'utilisateur de maintenir un échange continu pour un `access_token` #### Flux d'autorisation 1. **Accès aux informations de l'utilisateur** : Pour accéder à plus d'informations sur l'utilisateur, l'application peut faire des requêtes supplémentaires au point de terminaison UserInfo, en utilisant l'`access_token` opaque obtenu à partir du flux initial d'échange de jetons. Cela permet de récupérer des détails supplémentaires sur l'utilisateur, tels que son adresse électronique ou sa photo de profil. 2. **Octroi d'accès à la ressource protégée** : Si nécessaire, l'application peut faire des requêtes supplémentaires au point de terminaison d'échange de jetons, en utilisant le `refresh_token` combiné avec les paramètres `resource` et `scope`, pour obtenir un `access_token` dédié pour que l'utilisateur accède à la ressource cible. Ce processus aboutit à l'émission d'un `access_token` au format JWT contenant toutes les informations d'autorisation nécessaires pour accéder à la ressource protégée. ## Implémentation Nous allons suivre certaines stratégies de conception au sein de notre SDK JavaScript @logto/client pour démontrer le processus d'implémentation d'un SDK simple pour votre propre application client. Notez que la structure de code détaillée peut varier en fonction du cadre client avec lequel vous travaillez. N'hésitez pas à choisir l'un des SDK officiels de Logto comme exemple pour votre propre projet de SDK. ### Aperçu ```ts class LogtoClient { protected readonly logtoConfig: LogtoConfig; protected readonly storage: Storage; protected oidcConfig: OidcConfig; protected accessTokenMap: Map constructor(logtoConfig: LogtoConfig) {} get async idToken(){} private async getOidcConfig(){} private async getJwksFunction() {} private async verifyIdToken() {} private async saveTokens() {} private async setSignInSession() {} private async getSignInSession() {} private async getAccessTokenByRefreshToken() {} async signIn(redirectUri: string) {} async handlerSignInCallback (callbackUri: string) {} async getUserInfo() {} async getAccessToken(resource?: string, scopes?: string[]) {} } ``` ### Constructeur Le constructeur doit prendre un [logtoConfig](#logto-config) en entrée. Cela fournit toutes les configurations nécessaires dont vous aurez besoin pour établir une connexion d'authentification à travers ce SDK. En fonction de la plateforme ou du cadre que vous utilisez pour le SDK, vous pouvez passer une instance de stockage local persistante au constructeur. Cette instance de stockage sera utilisée pour stocker tous les jetons et secrets d'autorisation. ```ts class LogtoClient { constructor(logtoConfig: LogtoConfig, storage: Storage) {} } ``` ### Init de l'authentification utilisateur Avant de générer un URL de demande d'authentification, il est essentiel de compléter plusieurs étapes de préparation pour garantir un processus sécurisé. #### Obtention des configurations OIDC du serveur d'autorisation Définissez une méthode privée `getOidcConfigs` pour récupérer les configurations OIDC du point de terminaison de la découverte du serveur d'autorisation. La réponse aux configurations OIDC contient toutes les informations de métadonnées que le client peut utiliser pour interagir avec le serveur d'autorisation, y compris les emplacements de ses points de terminaison et les capacités du serveur. (Veuillez vous référer à [OAuth OAuth Authorization Server Metadata Specs](https://datatracker.ietf.org/doc/html/rfc8414) pour plus de détails.) ```ts const discoveryPath = "/oidc/.well-known/openid-configuration"; private async getOidcConfigs() { if (this.oidcConfig) { return this.oidcConfig; } const response = await fetch(`${this.logtoConfig.endpoint}${discoveryPath}`) this.oidcConfig = await response.json(); return this.oidcConfig; } ``` #### Générateur PKCE Un [PKCE(Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636) flux de validation est essentiel pour tous les flux publics d'échange de code d'autorisation. Il atténue le risque d'attaque d'interception du code d'autorisation. Ainsi, un `code_challenge` et `code_verifier` est nécessaire pour toutes les demandes d'autorisation des applications client publics (par exemple, application native et SPA). Les méthodes d'implémentation peuvent varier en fonction des langages et des cadres que vous utilisez. Veuillez vous référer à la spécification [code_challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) et [code_verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) pour les définitions détaillées. Si vous travaillez sur un client confidentiel ou des applications web rendues par serveur comme express ou nextjs, passez directement à l'étape suivante. Pour plus d'informations sur le PKCE et la différence entre les clients publics et confidentiels, consultez notre récapitulatif sur la sécurité de [OAuth](https://blog.logto.io/oauth-security-recap). ```ts class PKCE { readonly codeVerifier: string; readonly codeChallenge: string; constructor() { this.codeVerifier = this.generateCodeVerifier(); this.codeChallenge = this.generateCodeChallenge(this.codeVerifier); } /** * Génère un vérificateur de code * * @link [Client Creates a Code Verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) */ private generateCodeVerifier() { return generateRandomString(); } /** * Calcule le défi de code PKCE S256 pour un vérificateur de code arbitraire et l'encode en base64 sûr pour les URL * * @param {String} codeVerifier Code verifier pour calculer le défi de code S256 pour * @link [Client Creates the Code Challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) */ private async generateCodeChallenge(codeVerifier: string) { const encodedCodeVerifier = new TextEncoder().encode(codeVerifier); const codeChallenge = new Uint8Array( await crypto.subtle.digest('SHA-256', encodedCodeVerifier) ); } } ``` #### Générer le paramètre d'état Dans le flux d'autorisation, le [paramètre d'état](https://blog.logto.io/oauth-security-recap/#state) est une valeur générée aléatoirement qui est incluse dans la demande d'autorisation envoyée par le client. Il agit comme une mesure de sécurité pour prévenir les attaques par requête forgée intersites (CSRF). ```ts const state = generateRandomString(); ``` #### Stocker les infos de session intermédiaire Il y a plusieurs paramètres qui doivent être préservés dans le stockage pour la validation après que l'utilisateur s'est authentifié et a été redirigé vers le côté client. Nous allons implémenter une méthode pour mettre ces paramètres intermédiaires dans le stockage. ```ts protected async setSignInSession (data: { codeVerifier: string; redirectUri: string; state: string; }) { await this.storage.setItem('signInSession', data); } ``` #### Sign-in Enfin, prenons tout ce que nous avons implémenté ci-dessus, définissons une méthode générant une URL de connexion de l'utilisateur et redirigeons l'utilisateur vers le serveur d'autorisation pour qu'il s'authentifie. ```ts async signIn(redirectUri: string) { const { appId, resources, scopes } = this.logtoConfig; const { authorizationEndpoint } = await this.getOidcConfig(); // Pour les applications client publics uniquement const pkce = new PKCE(); const state = generateRandomString(); const queryParameters = new URLSearchParams({ client_id: appId, redirect_uri: redirectUri, code_challenge: pkce.codeChallenge, code_challenge_method: 'S256', state, response_type: 'code', prompt: 'consent', scopes: [...reservedScopes, scopes], }); // Ajouter tous les indicateurs de ressource si nécessaire for (const resource of resources ?? []) { urlSearchParameters.append('resource', resource); } const signInUrl = new URL(`${authorizationEndpoint}?${urlSearchParameters.toString()}`); await this.setSignInSession({ redirectUri, state, codeVerifier: pkce.codeVerifier }); navigate(signInUrl); } ``` ### Gérer le callback de connexion de l'utilisateur Dans la section précédente, nous avons créé une méthode de connexion qui génère une URL pour l'authentification de l'utilisateur. Cette URL contient tous les paramètres nécessaires pour initier un flux d'authentification à partir d'une application client. La méthode redirige l'utilisateur vers la page de connexion du serveur d'autorisation pour l'authentification. Après une connexion réussie, l'utilisateur final sera redirigé vers l'emplacement redirect_uri fourni ci-dessus. Tous les paramètres nécessaires seront transportés dans l'URI de redirection pour compléter les flux d'échange de jetons suivants. #### Extraire et vérifier l'URL du callback Cette étape de validation est extrêmement importante pour prévenir toute forme d'attaques de faux callbacks d'autorisation. L'URL de callback **DOIT** être soigneusement vérifiée avant d'envoyer une demande d'échange de code supplémentaire au serveur d'autorisation. Tout d'abord, nous devons récupérer les données de la session de connexion que nous avons stockées dans le stockage de l'application. ```ts protected async getSignInSession () { session = await this.storage.getItem('signInSession', data); if (!session) { throw Error('Session not found'); } } ``` Ensuite, vérifiez les paramètres de l'URL du callback avant d'envoyer la demande d'échange de jeton. - Utilisez le `redirectUri` précédemment stocké pour vérifier si le `callbackUri` est le même que celui que nous avons envoyé au serveur d'autorisation. - Utilisez le `state` précédemment stocké pour vérifier si l'état renvoyé est le même que celui que nous avons envoyé au serveur d'autorisation. - Vérifiez si une erreur est renvoyée par le serveur d'autorisation - Vérifiez l'existence du `code d'autorisation` renvoyé ```ts verifyAndParseCodeFromCallbackUri(callbackUri: string, redirectUri: string, state: string) { const url = new URL(callbackUri) const parameters = url.searchParams; if (!callbackUri.startWith(redirectUri)) { throw new Error('redirect_uri_mismatched') } //Vérifiez le message d'erreur. // Si l'authentification échoue, l'utilisateur sera redirigé avec des paramètres d'erreur attachés const error = parameters.get('error'); const errorDescription = parameters.get('error_description'); if (error || errorDescription) { throw new Error(`${error}:${errorDescription}`) } // Vérification de l'état const callbackState = parameter.get('state'); if (callbackState !== state) { throw new Error('state_mismatch'); } // Extraction du code d'autorisation const code = parameters.get('code'); if (!code) { throw new Error('authorization_code_not_found') } return code; } ``` #### Envoyer la demande d'échange de code En tant que dernière étape du flux d'authentification de l'utilisateur, nous utiliserons le `code d'autorisation` pour envoyer une demande d'échange de jetons et obtenir les jetons d'autorisation nécessaires. Pour plus de détails sur les définitions des paramètres de la demande, veuillez vous référer à la spécification d'échange de jetons [token exchange specification](https://datatracker.ietf.org/doc/html/rfc8693#section-2). - code : le `code d'autorisation` que nous avons reçu de l'URI de callback - clientId : l'ID de l'application - redirectUri : La même valeur est utilisée lors de la génération de l'URL de connexion pour l'utilisateur. - codeVerifier : vérificateur de code PKCE. De la même manière que le redirectUri, le serveur d'autorisation comparera cette valeur à celle que nous avions précédemment envoyée, assurant la validation de la demande d'échange de jetons entrante. ```ts const getTokenByAuthorizationCode = async (payload: { code: string; clientId: string; tokenEndpoint: string; redirectUri: string; codeVerifier: string; }) => { const parameters = new URLSearchParams({ client_id: payload.clientId, code: payload.code, code_verifier: payload.codeVerifier, redirect_uri: payload.redirectUri, grant_type: 'authorization_code', }); return fetch(tokenEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' } body: parameters, }); } ``` #### Gérer le callback de connexion Faisons le point sur tout ce que nous avons. Construisons la méthode de gestion du callback de connexion : ```ts private async saveTokens({refreshToken, idToken, accessToken}) { this.storage.setItem('refreshToken', refreshToken); this.storage.setItem('idToken', idToken); // jeton d'accès opaque sans spécification d'indicateur de ressource this.accessTokenMap.setItem('', accessToken) } async handleSignInCallback(callbackUri: string){ const signInSession = await this.getSignInSession(); if (!signInSession) { throw new Error('sign_in_session.not_found'); } const { redirectUri, state, codeVerifier } = signInSession; const code = verifyAndParseCodeFromCallbackUri(callbackUri, redirectUri, state); const { appId } = this.logtoConfig; const { tokenEndpoint } = await this.getOidcConfig(); const response = await getTokenByAuthorizationCode({ code, clientId: appId, tokenEndpoint, redirectUri, codeVerifier, }); await this.saveTokens(response); } ``` En conséquence, la demande d'échange de jetons renverra les jetons suivants : - `id_token` : idToken OIDC, un Jeton Web JSON (JWT) qui contient des informations d'identité sur l'utilisateur authentifié. L'id_token peut également être utilisé comme Source Unique de Vérité(SSOT) du statut d'authentification d'un utilisateur. - `access_token` : Le code d'autorisation par défaut renvoyé par le serveur d'autorisation. Peut être utilisé pour appeler le point de terminaison des informations de l'utilisateur et récupérer les informations de l'utilisateur authentifié. - `refresh_token` : (si la portée offline_access est présente dans la demande d'autorisation) : Ce jeton de rafraîchissement permet à l'application client d'obtenir un nouvel access_token sans que l'utilisateur ait besoin de se ré-authentifier, accordant un accès à plus long terme aux ressources. - `expires_in` : La durée en secondes pendant laquelle l'access_token est valide avant son expiration. ### Vérification du jeton d'identification La vérification et l'extraction des claims du `id_token` sont une étape cruciale du processus d'authentification pour garantir l'authenticité et l'intégrité du jeton. Voici les étapes clés impliquées dans la vérification d'un `idToken`. - Vérification de la signature : Le `id_token` est numériquement signé par le serveur d'autorisation en utilisant sa clé privée. L'application client doit valider la signature en utilisant la clé publique du serveur d'autorisation. Ceci assure que le jeton n'a pas été altéré et a bien été émis par le serveur d'autorisation légitime. - Vérification de l'émetteur**:** Vérifiez que la claim "iss" (issuer) dans le `id_token` correspond à la valeur attendue, indiquant que le jeton a été émis par le bon serveur d'autorisation. - Vérification de l'audience : Assurez-vous que la claim "aud" (audience) dans le `id_token` correspond à l'ID du client de l'application client, assurant que le jeton est destiné au client. - Vérification de l'expiration : Vérifiez que la claim "iat" (emis à) dans le `id_token` n'a pas dépassé l'heure actuelle, assurant que le jeton est toujours valide. Comme il y a des coûts de transaction de réseau, nous devons définir une tolérance de temps émis lors de la validation de la claim iat du jeton reçu. Le `id_token` renvoyé est un Jeton Web JSON (JWT) standard. Selon le cadre que vous utilisez, vous pouvez trouver divers plugins de validation de jetons JWT pratiques pour vous aider à déchiffrer et valider le jeton. Pour cet exemple, nous utiliserons [jose](https://www.npmjs.com/package/jose) dans notre SDK JavaScript pour faciliter la validation et le décodage du jeton. ```sh npm install jose ``` ```ts import {createRemoteJWKSet, jwtVerify} from 'jose'; private async getJwksFunction() { const { jwksUri } = await this.getOidcConfig(); return createRemoteJWKSet(new URL(jwksUri))(); } private async verifyIdToken( idToken: string, clientId: string, issuer: string, ) { const jwks = await this.getJwksFunction(); const result = await jwtVerify(idToken, jwks, { audience: clientId, issuer }); if (Math.abs((result.payload.iat ?? 0) - Date.now() / 1000) > issuedAtTimeTolerance) { throw new Error('id_token.invalid_iat'); } return result; }; ``` ### Obtenir des informations utilisateur Après une authentification réussie, des informations utilisateur de base peuvent être récupérées à partir de l'`id_token` OIDC délivré par le serveur d'autorisation. Cependant, en raison de considérations de performance, le contenu du jeton JWT est limité. Pour obtenir des informations de profil utilisateur plus détaillées, les serveurs d'autorisation conformes à OIDC offrent un point de terminaison d'information d'utilisateur clé en main. Ce point de terminaison vous permet de récupérer des données de profil d'utilisateur supplémentaires en demandant des scopes de profil d'utilisateur spécifiques. Lors de l'appel à un point de terminaison d'échange de jetons sans indiquer une ressource API spécifique, le serveur d'autorisation délivrera par défaut un `access_token` de type opaque. Cet `access_token` ne peut être utilisé que pour accéder au point de terminaison des informations utilisateur, permettant la récupération des données de profil utilisateur de base. ```ts async getUserInfo() { const { userinfoEndpoint } = await this.getOidcConfig(); const accessToken = await this.getAccessToken(); return fetch(userinfoEndpoint, { headers: { Authorization: `Bearer ${accessToken}` } }); } ``` ### Obtenir un access_token pour l'autorisation de la ressource protégée Dans la plupart des cas, une application client nécessite non seulement l'authentification de l'utilisateur, mais aussi son autorisation pour accéder à certaines ressources protégées ou points de terminaison API. Ici, nous allons utiliser le `refresh_token` obtenu lors de la connexion pour obtenir des `access_tokens` spécifiquement accordés pour gérer des ressources particulières. Cela nous permet d'obtenir l'accès à ces APIs protégées. Pendant la connexion de l'utilisateur, il est crucial de fournir tous les indicateurs de ressource API au serveur d'autorisation. Après une authentification réussie, nous ne pouvons récupérer que les `access_tokens` pour les ressources spécifiées préconfigurées. Pour ce faire, préconfigurez tous les indicateurs de ressource API requis dans les paramètres de configuration de l'application client avant de générer l'URL de connexion. ```ts private async getAccessTokenByRefreshToken(resource?:string, scopes?: string[]){ const { appId } = this.logtoConfig; const { tokenEndpoint } = await this.getOidcConfig(); const { refreshToken } = await this.storage.getItem('refreshToken'); const parameters = new URLSearchParams({ 'grant_type': 'refresh_token', 'client_id': appId, 'refresh_token': }); if (resource) { parameters.append('resource', resource); } if (scopes?.length) { parameters.append('scope', scopes.join(' ')); } const response = await fetch(tokenEndpoint, { method: 'POST', grant_type: 'authorization_code', body: parameters, }); // sauvegarder et remplacer le refreshToken renvoyé le plus récemment await this.storage.setItem('refreshToken', response.refreshToken); await this.accessTokenMap.setItem(`${resource}:${scopes.join(_)}`, response.accessToken); return response.accessToken; } async getAccessToken(resource?:string, scopes?: string[]) { if (!this.idToken) { throw new Error('Utilisateur non authentifié'); } const accessTokenInStorage = this.accessTokenMap.getItem(`${resource}:${scopes.join(_)}`); if (accessTokenInStorage && accessTokenInStorage.expiresAt > Date.now() / 1000) { return accessToken.token; } return await this.getAccessTokenByRefreshToken(resource, scopes); } ``` ## Résumé Nous avons fourni des implémentations de méthodes essentielles pour le processus d'authentification et d'autorisation des utilisateurs de l'application côté client. Selon votre scénario spécifique, vous pouvez organiser et optimiser la logique du SDK en conséquence. Notez que des variations peuvent exister en raison des différentes plateformes et cadres. Pour plus de détails, explorez les packages de SDK offerts par Logto. Nous encourageons plus d'utilisateurs à se joindre au développement et à participer aux discussions avec nous. Vos commentaires et contributions sont très appréciés alors que nous continuons à améliorer et à étendre les capacités du SDK. ## Annexe ### Portées réservées Portées réservées de Logto dont vous aurez besoin pour passer lors de la première demande d'autorisation. Ces portées sont soit des portées fondamentales réservées à OIDC, soit réservées à Logto pour compléter un flux d'autorisation réussi. | Nom de la portée | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | openid | Requis pour accorder `id_token` après une authentification réussie. | | offline-access | Requis pour accorder un `refresh_token` qui permet à votre application cliente d'échanger et de renouveler un access_token hors écran. | | profile | Requis pour obtenir un accès aux informations de base de l'utilisateur | ### Logto Config | Nom de la propriété | Type | Requis | Description | Valeur par défaut | | ------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | appId | string | true | L'identifiant unique de l'application. Généré par le serveur d'autorisation pour identifier l'application cliente. | | | appSecret | string | | Le secret de l'application est utilisé, en conjonction avec l'ID de l'application, pour vérifier l'identité du demandeur. Il est requis pour les clients confidentiels comme les applications web Go ou Next.js, et facultatif pour les clients publics comme les applications natives or single-page applications (SPAs) | | | endpoint | string | true | Votre point de terminaison racine du serveur d'autorisation. Cette propriété sera largement utilisée pour générer des demandes d'autorisation. | | | scopes | liste de string | | Indique toutes les portées de ressources nécessaires que l'utilisateur peut devoir être accordées pour accéder à toute ressource protégée donnée. | [reservedScopes] | | resources | liste de string | | Tous les indicateurs de ressource protégée auxquels l'utilisateur peut demander l'accès | | ### Méthodes utilitaires #### generateRandomString ```ts const generateRandomString = (length = 64) => fromUint8Array(crypto.getRandomValues(new Uint8Array(length)), true); ``` Essayez Logto Cloud aujourd'hui