## Introducción [Logto](https://logto.io/) proporciona a nuestros desarrolladores y grupos empresariales una solución integral de Identidad de Cliente y Gestión de Acceso (CIAM). Ofrecemos una amplia gama de SDKs listos para usar para diferentes plataformas y marcos de aplicación. Combinado con nuestro servicio en la nube de Logto, puedes establecer sin esfuerzo un flujo de autorización de usuario altamente seguro para tu aplicación en cuestión de minutos. Como una empresa que nació de la comunidad de desarrolladores, Logto acoge y valora nuestro compromiso con la comunidad. Además de los SDKs de Logto oficialmente desarrollados, continuamente alentamos y damos una cálida bienvenida a los desarrolladores de la comunidad a contribuir con su experiencia creando SDKs más diversos y fáciles de usar, satisfaciendo las necesidades únicas de diversas plataformas y marcos. En este artículo, demostraremos brevemente cómo implementar un SDK de autenticación estándar OIDC paso a paso. Crea tu aplicación en Logto ## Contexto El flujo de Conexión Abierta (OIDC) es un protocolo de autenticación que se basa en el marco de trabajo OAuth 2.0 para proporcionar verificación de identidad y capacidades de inicio de sesión único. Permite a los usuarios autenticarse con una aplicación y obtener autorización para acceder de forma segura a cualquier recurso privado. Por favor, consulta las especificaciones de OIDC para más detalles. ### Flujo de trabajo Un flujo de código de autorización estándar incluye los siguientes pasos: ```mermaid sequenceDiagram actor user as End User participant app as Client App participant server as Authorization Server participant resource as Private Resources user ->> app: anonymous visitor sign-in app ->> server: send authentication request server -->> user: redirect to the user sign-in page user ->> server: sign-in with credentials server -->> app: redirect back to the client app with authorization_code app ->> server: token exchange request with the authorization_code server ->> app: grant id_token, access_token and refresh_token app -->> user: authenticated app ->> resource: private api request with access_token resource --> server: sync signing key resource -->> resource: token validation resource ->> app: 200 OK ``` #### Flujo de autenticación 1. **El usuario inicia la petición de inicio de sesión:** Un usuario anónimo llega a su aplicación a través de una entrada pública. Intenta autenticarse y tal vez solicitar el acceso a un recurso protegido en una aplicación o servicio de terceros. 2. **Autenticación del usuario:** La aplicación cliente genera una URI de autenticación y envía una petición al servidor de autorización, que redirige al usuario a su página de inicio de sesión. El usuario interactúa con la página de inicio de sesión utilizando una amplia gama de métodos de inicio de sesión y se autentica en el servidor de autorización. 3. **Manejar el retorno de inicio de sesión**: Tras una autenticación exitosa, el usuario será redirigido de vuelta a tu aplicación con un `authorization_code` concedido. Este `authorization_code` contiene todos los permisos relevantes vinculados al estado de la autenticación y los datos de autorización solicitados. 4. **Intercambio de tokens**: Solicitar el intercambio de tokens usando el `authorization_code` extraído de la dirección de redirección anterior. A cambio: - `id_token`: Un JWT firmado digitalmente que contiene información de identidad sobre el usuario autenticado. - `access_token`: Un `access_token` opaco que puede ser utilizado para acceder al punto final de información básica del usuario. - `refresh_token`: Token de credenciales que permite al usuario mantener un intercambio continuo para un `access_token` #### Flujo de autorización 1. **Acceder a la información del usuario**: Para acceder a más información del usuario, la aplicación puede hacer solicitudes adicionales al punto final de UserInfo, utilizando el `access_token` opaco obtenido del flujo inicial de intercambio de tokens. Esto permite la recuperación de detalles adicionales sobre el usuario, como su dirección de correo electrónico o foto de perfil. 2. **Conceder acceso al recurso protegido**: Si es necesario, la aplicación puede hacer solicitudes adicionales al punto final de intercambio de tokens, utilizando el `refresh_token` combinado con los parámetros `resource` y `scope`, para obtener un `access_token` dedicado para que el usuario acceda al recurso objetivo. Este proceso resulta en la emisión de un `access_token` en formato JWT que contiene toda la información de autorización necesaria para acceder al recurso protegido. ## Implementación Seguiremos algunas estrategias de diseño dentro de nuestro SDK JavaScript @logto/client para demostrar el proceso de implementación de un SDK sencillo para tu propia aplicación cliente. Por favor, ten en cuenta que la estructura de código detallada puede variar dependiendo del marco de trabajo cliente con el que estás trabajando. Siéntete libre de elegir cualquiera de los SDKs oficiales de Logto como ejemplo para tu propio proyecto de SDK. ### Vista previa ```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[]) {} } ``` ### Constructor El constructor debe tomar un [logtoConfig](#logto-config) como su entrada. Esto proporciona todas las configuraciones necesarias que necesitarás para establecer una conexión de autenticación a través de este SDK. Dependiendo de la plataforma o marco de trabajo que estés utilizando para el SDK, puedes pasar una instancia de almacenamiento local persistente al constructor. Esta instancia de almacenamiento se utilizará para almacenar todos los tokens y secretos relacionados con la autorización. ```ts class LogtoClient { constructor(logtoConfig: LogtoConfig, storage: Storage) {} } ``` ### Iniciar la autenticación del usuario Antes de generar una URL de petición de autenticación, es esencial completar varios pasos de preparación para asegurar un proceso seguro. #### Obtener las configuraciones OIDC del servidor de autorización Define un método privado `getOidcConfigs` para obtener las configuraciones OIDC del punto final de descubrimiento del servidor de autorización. La respuesta de las configuraciones OIDC contiene toda la información de metadatos que el cliente puede usar para interactuar con el servidor de autorización, incluyendo sus ubicaciones de punto final y las capacidades del servidor. (Por favor, consulta las especificaciones de metadatos del servidor de autorización OAuth OAuth para más detalles.) ```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; } ``` #### Generador PKCE Un flujo de validación [PKCE(Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636) es esencial para todos los flujos de intercambio de código de autorización del cliente público. Mitiga el riesgo del ataque de intercepción del código de autorización. Por lo tanto, un `code_challenge` y un `code_verifier` es requerido para todas las peticiones de autorización de las aplicaciones cliente públicas (por ejemplo, aplicación nativa y SPA). Los métodos de implementación pueden variar dependiendo de los lenguajes y marcos de trabajo que estés utilizando. Por favor, consulta la especificación de [code_challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) y [code_verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) para las definiciones detalladas. Si estás trabajando en un cliente confidencial o aplicaciones web renderizadas por el servidor como express o nextjs, salta directamente al siguiente paso. Para más información sobre PKCE y la diferencia entre clientes públicos y clientes confidenciales por favor consulta nuestro [resumen de seguridad 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); } /** * Genera el verificador de código * * @link [El cliente crea un verificador de código](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) */ private generateCodeVerifier() { return generateRandomString(); } /** * Calcula el desafío de código S256 PKCE para un verificador de código arbitrario y lo codifica en base64 seguro para URL * * @param {String} codeVerifier Verificador de código para calcular el desafío de código S256 para * @link [El cliente crea el desafío de código](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) ); } } ``` #### Generar parámetro de estado En el flujo de autorización, el parámetro de estado es un valor generado aleatoriamente que se incluye en la petición de autorización enviada por el cliente. Actúa como una medida de seguridad para prevenir ataques de falsificación de peticiones en sitios cruzados (CSRF). ```ts const state = generateRandomString(); ``` #### Almacenar información de sesión intermedia Hay varios parámetros que necesitan ser preservados en el almacenamiento para la validación después de que el usuario se autentique y sea redirigido de vuelta al lado del cliente. Vamos a implementar un método para establecer esos parámetros intermedios en el almacenamiento. ```ts protected async setSignInSession (data: { codeVerifier: string; redirectUri: string; state: string; }) { await this.storage.setItem('signInSession', data); } ``` #### Iniciar sesión Vamos a juntar todo lo que implementamos anteriormente, definamos un método que genere una URL de inicio de sesión para el usuario y redirija al usuario al servidor de autorización para autenticarse. ```ts async signIn(redirectUri: string) { const { appId, resources, scopes } = this.logtoConfig; const { authorizationEndpoint } = await this.getOidcConfig(); // Solo para aplicaciones cliente públicas 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], }); // Añade todos los indicadores de recurso si los hay 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); } ``` ### Manejar el retorno de inicio de sesión del usuario En la sección anterior, creamos un método de inicio de sesión que genera una URL para la autenticación del usuario. Esta URL contiene todos los parámetros requeridos necesarios para iniciar un flujo de autenticación desde una aplicación cliente. El método redirige al usuario a la página de inicio de sesión del servidor de autorización para autenticarse. Después de un inicio de sesión exitoso, el usuario final será redirigido de vuelta a la ubicación de redirect_uri proporcionada anteriormente. Todos los parámetros necesarios serán llevados en la redirect_uri para completar los siguientes flujos de intercambio de tokens. #### Extraer y verificar la URL de devolución de llamada Este paso de validación es extremadamente importante para prevenir cualquier forma de ataques de devolución de llamada de autorización falsificados. La URL de devolución de llamada **DEBE** ser cuidadosamente verificada antes de enviar una petición de intercambio de código adicional al servidor de autorización. Primero que todo, necesitamos recuperar los datos de signInSession que almacenamos del almacenamiento de la aplicación. ```ts protected async getSignInSession () { session = await this.storage.getItem('signInSession', data); if (!session) { throw Error('Session not found'); } } ``` Luego verifica el parámetro de la URL de devolución de llamada antes de enviar la petición de intercambio de código al servidor de autorización. - Usa el `redirectUri` previamente almacenado para verificar si el `callbackUri` es el mismo que el que enviamos al servidor de autorización. - Usa el `state` previamente almacenado para verificar si el estado devuelto es el mismo que el que enviamos al servidor de autorización. - Comprueba si el servidor de autorización devuelve algún error - Comprueba la existencia del `authorization_code` devuelto ```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') } // Verificar el mensaje de error. // Si la autenticación falla, el usuario será redirigido de vuelta con parámetros de error adjuntos const error = parameters.get('error'); const errorDescription = parameters.get('error_description'); if (error || errorDescription) { throw new Error(`${error}:${errorDescription}`) } // Verificación de estado const callbackState = parameter.get('state'); if (callbackState !== state) { throw new Error('state_mismatch'); } // Extraer el código de autorización const code = parameters.get('code'); if (!code) { throw new Error('authorization_code_not_found') } return code; } ``` #### Enviar la petición de intercambio de código Como último paso del flujo de autenticación del usuario, utilizaremos el `authorization_code` devuelto para enviar una petición de intercambio de tokens y obtener los tokens de autorización requeridos. Para obtener más detalles sobre las definiciones de los parámetros de la solicitud, por favor consulta la [especificación de intercambio de tokens](https://datatracker.ietf.org/doc/html/rfc8693#section-2). - code: el `authorization_code` que recibimos de la URI de devolución de llamada - clientId: la ID de la aplicación - redirectUri: El mismo valor se utiliza al generar la URL de inicio de sesión para el usuario. - codeVerifier: verificador de código PKCE. Igual que el redirectUri, el servidor de autorización comparará este valor con el que enviamos previamente, asegurando la validación de la petición de intercambio de tokens que entra. ```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, }); } ``` #### Manejar la devolución de llamada de inicio de sesión Recopilando todo lo que tenemos. Construyamos el método de manejo de devolución de llamada de inicio de sesión: ```ts private async saveTokens({refreshToken, idToken, accessToken}) { this.storage.setItem('refreshToken', refreshToken); this.storage.setItem('idToken', idToken); // token de acceso opaco sin especificación de indicador de recurso 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); } ``` Como resultado, la petición de intercambio de tokens devolverá los siguientes tokens: - `id_token`: ID de OIDC idToken, un JSON Web Token (JWT) que contiene información de identidad sobre el usuario autenticado. El id_token también puede ser utilizado como la Única Fuente de Verdad (SSOT) del estado de autenticación de un usuario. - `access_token`: El código de autorización predeterminado devuelto por el servidor de autorización. Puede ser utilizado para llamar al punto final de información del usuario y recuperar información autenticada del usuario. - `refresh_token`: (si el scope offline_access está presente en la petición de autorización): Este token de actualización permite a la aplicación cliente obtener un nuevo token de acceso sin requerir que el usuario vuelva a autenticarse, concediendo un acceso a largo plazo a los recursos. - `expires_in`: La duración del tiempo, en segundos, para la que el token de acceso es válido antes de que expire. ### Verificación del token ID Verificar y extraer reclamos del `id_token` es un paso crucial en el proceso de autenticación para asegurar la autenticidad e integridad del token. Aquí están los pasos clave involucrados en la verificación de un `idToken`. - Verificación de la firma: El `id_token` está firmado digitalmente por el servidor de autorización utilizando su clave privada. La aplicación cliente necesita validar la firma utilizando la clave pública del servidor de autorización. Esto asegura que el token no ha sido manipulado y fue emitido por el servidor de autorización legítimo. - Verificación del emisor: Comprobar que la reclamación "iss" (emisor) en el `id_token` coincide con el valor esperado, indicando que el token fue emitido por el servidor de autorización correcto. - Verificación de la audiencia: Asegurarse de que la reclamación "aud" (audiencia) en el `id_token` coincide con la ID del cliente de la aplicación cliente, asegurando que el token está destinado al cliente. - Comprobar la expiración: Verificar que la reclamación "iat" (emitida en) en el `id_token` no haya pasado la hora actual, asegurando que el token aún es válido. Dado que hay costos de transacción de red necesitamos establecer una tolerancia de tiempo emitida al validar la reclamación iat del token recibido. El id_token devuelto es un token web JSON (JWT) estándar. Dependiendo del marco de trabajo que estés utilizando, puedes encontrar varios plugins de validación de tokens JWT convenientes para ayudar en la decodificación y validación del token. Para este ejemplo, utilizaremos [jose](https://www.npmjs.com/package/jose) en nuestro SDK de JavaScript para facilitar la validación y decodificación del token. ```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; }; ``` ### Obtener la información del usuario Después de una autenticación de usuario exitosa, la información básica del usuario puede ser recuperada del `id_token` OIDC emitido por el servidor de autorización. Sin embargo, debido a consideraciones de rendimiento, el contenido del token JWT es limitado. Para obtener más información detallada del perfil del usuario, los servidores de autorización compatibles con OIDC ofrecen un punto final de información de usuario fuera de la caja. Este punto final te permite recuperar datos adicionales del perfil del usuario solicitando scopes específicos del perfil del usuario. Al llamar a un punto final de intercambio de tokens sin indicar un recurso API específico, el servidor de autorización emitirá por defecto un `access_token` de tipo opaco. Este `access_token` sólo puede ser utilizado para acceder al punto final de información del usuario, permitiendo la recuperación de datos básicos del perfil del usuario. ```ts async getUserInfo() { const { userinfoEndpoint } = await this.getOidcConfig(); const accessToken = await this.getAccessToken(); return fetch(userinfoEndpoint, { headers: { Authorization: `Bearer ${accessToken}` } }); } ``` ### Obtener token de acceso para autorización de recurso protegido En la mayoría de los casos, una aplicación cliente no sólo requiere autenticación de usuario, sino también necesita autorización de usuario para acceder a ciertos recursos protegidos o puntos finales de la API. Aquí, utilizaremos el `refresh_token` obtenido durante el inicio de sesión para adquirir `access_token(s)` específicamente concedidos para administrar recursos particulares. Esto nos permite obtener acceso a esas APIs protegidas. Durante el inicio de sesión del usuario, es crucial proporcionar todos los indicadores de recurso de la API al servidor de autorización. Después de una autenticación exitosa, sólo podemos recuperar los `access_tokens` para los recursos especificados preconfigurados. Para lograr esto, preconfigurar todos los indicadores de recurso de API requeridos en las configuraciones de la aplicación cliente antes de generar la URL de inicio de sesión. ```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, }); // guardar y reemplazar el refreshToken devuelto más reciente 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('User not authenticated'); } const accessTokenInStorage = this.accessTokenMap.getItem(`${resource}:${scopes.join(_)}`); if (accessTokenInStorage && accessTokenInStorage.expiresAt > Date.now() / 1000) { return accessToken.token; } return await this. getAccessTokenByRefreshToken(resource, scopes); } ``` ## Resumen Hemos proporcionado las implementaciones de métodos esenciales para el proceso de autenticación y autorización del usuario de la aplicación del lado cliente. Dependiendo de tu escenario específico, puedes organizar y optimizar la lógica del SDK en consecuencia. Ten en cuenta que pueden existir variaciones debido a diferentes plataformas y marcos de trabajo. Para obtener detalles adicionales, explora los paquetes de SDK ofrecidos por Logto. Alentamos a más usuarios a unirse al desarrollo y participar en discusiones con nosotros. Sus comentarios y contribuciones son altamente valorados ya que continuamos mejorando y ampliando las capacidades del SDK. ## Apéndice ### Scopes reservados Scopes de Logto reservados que necesitarás pasar durante la petición de autenticación inicial. Esos scopes son ya sea OIDC-reservados o Logto-reservados scopes fundamentales para completar un flujo de autorización exitoso. | Nombre del Scope | Descripción | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | openid | Requerido para conceder `id_token` después de una autenticación exitosa. | | offline-access | Requerido para conceder un `refresh_token` que permite a tu aplicación cliente intercambiar y renovar un access_token fuera de la pantalla. | | profile | Requerido para obtener acceso a la información básica del usuario. | ### Configuración de Logto | Nombre de la Propiedad | Tipo | Obligatorio | Descripción | Valor Predeterminado | | ------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | appId | string | true | El identificador de aplicación único. Generado por el servidor de autorización para identificar la aplicación cliente. | | | appSecret | string | | El secreto de la aplicación se utiliza, junto con el ID de la aplicación, para verificar la identidad del solicitante. Se requiere para clientes confidenciales como aplicaciones web de Go o Next.js, y es opcional para clientes públicos como aplicaciones nativas o de página única (SPAs) | | | endpoint | string | true | El punto final raíz de tu servidor de autorización. Esta propiedad será utilizada ampliamente para generar peticiones de autorización. | | | scopes | lista de strings | | Indica todos los scopes de recurso necesarios que el usuario puede necesitar ser concedido para acceder a cualquier recurso protegido dado. | [reservedScopes] | | resources | lista de strings | | Todos los indicadores de recurso protegido que el usuario puede solicitar para acceder. | | ### Métodos de utilidad #### generateRandomString ```ts const generateRandomString = (length = 64) => fromUint8Array(crypto.getRandomValues(new Uint8Array(length)), true); ``` Prueba Logto Cloud hoy