## Introdução [Logto](https://logto.io/) fornece aos nossos desenvolvedores e grupos de negócios uma solução abrangente de gerenciamento de identidade e acesso do cliente (CIAM). Oferecemos uma ampla gama de SDKs prontos para uso para diferentes plataformas e frameworks de aplicação. Combinado com nosso serviço Logto na nuvem, você pode estabelecer sem esforço um fluxo de autorização de usuário altamente seguro para sua aplicação em questão de minutos. Como uma empresa que nasceu da comunidade de desenvolvedores, a Logto abraça e valoriza nosso engajamento com a comunidade. Além dos SDKs oficialmente desenvolvidos pela Logto, nós continuamente incentivamos e recebemos calorosamente os desenvolvedores da comunidade para contribuírem com sua experiência criando SDKs mais diversos e amigáveis ao usuário, atendendo às necessidades únicas de várias plataformas e estruturas. Neste artigo, vamos demonstrar brevemente como implementar um SDK de autenticação padrão OIDC passo a passo. Crie sua aplicação em Logto ## Contexto O fluxo OpenID Connect (OIDC) é um protocolo de autenticação que se baseia no framework OAuth 2.0 para fornecer verificação de identidade e capacidades de single sign-on. Ele permite que os usuários se autentiquem com uma aplicação e obtenham autorização para acessar de forma segura quaisquer recursos privados. Por favor, consulte as especificações OIDC para mais detalhes. ### Fluxo de trabalho Um fluxo de código de autorização padrão inclui as seguintes etapas: ```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 ``` #### Fluxo de autenticação 1. **Usuário inicia a solicitação de autenticação:** Um usuário anônimo chega à sua aplicação a partir de uma entrada pública. Tenta se autenticar e talvez faça uma solicitação adicional para acessar um recurso protegido em uma aplicação ou serviço de terceiros. 2. **Autenticação do usuário:** A aplicação cliente gera uma URI de autenticação e envia uma solicitação para o servidor de autorização, que redireciona o usuário para sua página de login. O usuário interage com a página de login usando uma ampla gama de métodos de login e é autenticado pelo servidor de autorização. 3. **Tratar o retorno do login**: Após uma autenticação bem sucedida, o usuário será redirecionado de volta para sua aplicação com um `authorization_code` concedido . Este `authorization_code` contém todas as permissões relevantes ligadas ao status de autenticação e aos dados de autorização solicitados. 4. **Troca de tokens**: Solicita a troca de tokens usando o `authorization_code` extraído do endereço de redirecionamento acima. Em retorno: - `id_token`: Um JWT assinado digitalmente que contém informações de identidade sobre o usuário autenticado. - `access_token`: Um `access_token` opaco que pode ser usado para acessar o endpoint de informações básicas do usuário. - `refresh_token`: Token de credencial que permite ao usuário manter uma troca contínua por um `access_token` #### Fluxo de autorização 1. **Acessar informações do usuário**: Para acessar mais informações do usuário, a aplicação pode fazer solicitações adicionais ao endpoint UserInfo, utilizando o `access_token` opaco obtido no fluxo de troca de tokens inicial. Isso permite a recuperação de detalhes adicionais sobre o usuário, como seu endereço de email ou foto do perfil. 2. **Conceder acesso ao recurso protegido**: Se necessário, a aplicação pode fazer solicitações adicionais ao endpoint de troca de token, utilizando o `refresh_token` combinado com os parâmetros `resource` e `scope`, para obter um `access_token` dedicado para o usuário acessar o recurso alvo. Este processo resulta na emissão de um `access_token` formatado como JWT contendo todas as informações de autorização necessárias para acessar o recurso protegido. ## Implementação Seguiremos algumas estratégias de design dentro de nosso SDK JavaScript @logto/client para demonstrar o processo de implementação de um SDK simples para sua própria aplicação cliente. Por favor, tenha em mente que a estrutura de código detalhada pode variar dependendo do framework cliente com o qual você está trabalhando. Sinta-se à vontade para escolher qualquer um dos SDKs oficiais do Logto como exemplo para seu próprio projeto de SDK. ### Previsualização ```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[]) {} } ``` ### Construtor O construtor deve receber um [logtoConfig](#logto-config) como entrada. Isso fornece todas as configurações necessárias que você precisará para estabelecer uma conexão de autenticação através deste SDK. Dependendo da plataforma ou framework que você está usando para o SDK, você pode passar uma instância de armazenamento local persistente para o construtor. Esta instância de armazenamento será usada para armazenar todos os tokens e segredos relacionados à autorização. ```ts class LogtoClient { constructor(logtoConfig: LogtoConfig, storage: Storage) {} } ``` ### Iniciar autenticação do usuário Antes de gerar uma URL de solicitação de autenticação, é essencial concluir várias etapas de preparação para garantir um processo seguro. #### Obter configurações OIDC do servidor de autorização Defina um método privado `getOidcConfigs`` para buscar configurações OIDC do endpoint de descoberta do servidor de autorização. A resposta das configurações OIDC contém todas as informações de metadados que o cliente pode usar para interagir com o servidor de autorização, incluindo suas localizações de endpoint e as capacidades do servidor. (Por favor, consulte [OAuth OAuth Authorization Server Metadata Specs](https://datatracker.ietf.org/doc/html/rfc8414) para mais detalhes.) ```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; } ``` #### Gerador PKCE Um fluxo de validação [PKCE(Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636) é essencial para todos os fluxos de troca de código de autorização do cliente público. Ele mitiga o risco de ataque de interceptação de authorization_code. Assim, um `code_challenge` e `code_verifier` é necessário para todas as solicitações de autorização do cliente público(aplicações nativas e SPAs). Os métodos de implementação podem variar dependendo das linguagens e frameworks que você está usando. Por favor, consulte a especificação [code_challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) e [code_verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) para as definições detalhadas. Se você estiver trabalhando com um cliente confidencial ou aplicações web renderizadas pelo servidor como express ou nextjs, vá diretamente para a próxima etapa. Para mais informações sobre PKCE e a diferença entre clientes públicos e clientes confidenciais, verifique nosso [OAuth security recap](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); } /** * Generates code verifier * * @link [Client Creates a Code Verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) */ private generateCodeVerifier() { return generateRandomString(); } /** * Calculates the S256 PKCE code challenge for an arbitrary code verifier and encodes it in url safe base64 * * @param {String} codeVerifier Code verifier to calculate the S256 code challenge for * @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) ); } } ``` #### Gerar parâmetro state No fluxo de autorização, o [parâmetro state](https://blog.logto.io/oauth-security-recap/#state) é um valor gerado aleatoriamente que é incluído na solicitação de autorização enviada pelo cliente. Ele atua como uma medida de segurança para prevenir ataques de falsificação de solicitação entre sites (CSRF). ```ts const state = generateRandomString(); ``` #### Armazenar informações da sessão intermediária Existem vários parâmetros que precisam ser preservados no armazenamento para validação após o usuário se autenticar e ser redirecionado de volta para o lado do cliente. Vamos implementar um método para definir esses parâmetros intermediários no armazenamento. ```ts protected async setSignInSession (data: { codeVerifier: string; redirectUri: string; state: string; }) { await this.storage.setItem('signInSession', data); } ``` #### Login Vamos envolver tudo o que foi implementado acima, definir um método gerando uma URL de login do usuário e redirecionar o usuário para o servidor de autorização para se autenticar. ```ts async signIn(redirectUri: string) { const { appId, resources, scopes } = this.logtoConfig; const { authorizationEndpoint } = await this.getOidcConfig(); // For public client applications only 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], }); // Append all the resource indicators if any 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); } ``` ### Lidar com o retorno do login do usuário Na seção anterior, criamos um método de login que gera uma URL para autenticação do usuário. Esta URL contém todos os parâmetros necessários para iniciar um fluxo de autenticação a partir de uma aplicação cliente. O método redireciona o usuário para a página de login do servidor de autorização para autenticação. Após um login bem sucedido, o usuário final será redirecionado de volta para a localização de redirect_uri fornecida acima. Todos os parâmetros necessários serão transportados no redirect_uri para completar os fluxos de troca de tokens subsequentes. #### Extrair e verificar a URL de retorno Esta etapa de validação é extremamente importante para prevenir qualquer forma de ataques de retorno de autorização forjados. A URL de retorno **DEVE** ser cuidadosamente verificada antes de enviar uma solicitação de troca de código adicional ao servidor de autorização. Primeiro de tudo, precisamos recuperar os dados signInSession que armazenamos do armazenamento do aplicativo. ```ts protected async getSignInSession () { session = await this.storage.getItem('signInSession', data); if (!session) { throw Error('Session not found'); } } ``` Então verifique os parâmetros da URL de retorno antes de enviar a solicitação de troca de token. - Use o `redirectUri` armazenado anteriormente para verificar se o `callbackUri` é o mesmo que o que enviamos para o servidor de autorização. - Use o `state` armazenado anteriormente para verificar se o state retornado é o mesmo que o que enviamos para o servidor de autorização. - Verifique se há algum erro retornado pelo servidor de autorização - Verifique a existência do `authorization_code` retornado ```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') } //Check the error message. // If the authentication fails, the user will be redirected back with error parameters attached const error = parameters.get('error'); const errorDescription = parameters.get('error_description'); if (error || errorDescription) { throw new Error(`${error}:${errorDescription}`) } // State verification const callbackState = parameter.get('state'); if (callbackState !== state) { throw new Error('state_mismatch'); } // Extract authorization code const code = parameters.get('code'); if (!code) { throw new Error('authorization_code_not_found') } return code; } ``` #### Enviar a solicitação de troca de código Como a etapa final do fluxo de autenticação do usuário, utilizaremos o `authorization_code` retornado para enviar uma solicitação de troca de token e obter os tokens de autorização necessários. Para mais detalhes sobre as definições dos parâmetros da solicitação, por favor, consulte a [especificação de troca de token](https://datatracker.ietf.org/doc/html/rfc8693#section-2). - code: o `authorization_code` que recebemos da URI de retorno - clientId: o ID da aplicação - redirectUri: O mesmo valor é usado ao gerar a URL de login para o usuário. - codeVerifier: verificador de código PKCE. Similar ao redirectUri, o servidor de autorização irá comparar este valor com o que nós enviámos anteriormente, garantindo a validação da solicitação de troca de token que está chegando. ```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, }); } ``` #### Lidar com o retorno do login Envolver tudo o que temos. Vamos construir o handle método signInCallback : ```ts private async saveTokens({refreshToken, idToken, accessToken}) { this.storage.setItem('refreshToken', refreshToken); this.storage.setItem('idToken', idToken); // opaque access token without resource indicator specification 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, a solicitação de troca de token retornará os seguintes tokens: - `id_token`: OIDC idToken, um JWT (JSON Web Token) que contém informações de identidade sobre o usuário autenticado. O id_token também pode ser usado como a Fonte Única de Verdade (SSOT) do status de autenticação de um usuário. - `access_token`: O código de autorização padrão retornado pelo servidor de autorização. Pode ser usado para chamar o endpoint de info do usuário e recuperar informações do usuário autenticado. - `refresh_token`: (se o escopo offline_access estiver presente na solicitação de autorização): Este token de atualização permite que a aplicação cliente obtenha um novo access_token sem requerer que o usuário re-autentique, concedendo acesso de longo prazo aos recursos. - `expires_in`: A duração do tempo, em segundos, para qual o access_token é válido antes de expirar. ### Verificação do token ID Verificar e extrair reivindicações do `id_token` é uma etapa crucial no processo de autenticação para garantir a autenticidade e integridade do token. Aqui estão as etapas-chave envolvidas na verificação de um `idToken`. - Verificação de Assinatura: O `id_token` é assinado digitalmente pelo servidor de autorização usando sua chave privada. A aplicação cliente precisa validar a assinatura usando a chave pública do servidor de autorização. Isso garante que o token não foi adulterado e foi de fato emitido pelo servidor de autorização legítimo. - Verificação do Emitente:**:** Verifique se a reivindicação "iss" (emissor) no `id_token` corresponde ao valor esperado, indicando que o token foi emitido pelo servidor de autorização correto. - Verificação do público: Garanta que a reivindicação "aud" (público) no `id_token` corresponde ao ID do cliente da aplicação cliente, garantindo que o token é destinado ao cliente. - Checagem de expiração: Verifique se a reivindicação "iat" (emitida em) no `id_token` não passou do horário atual, garantindo que o token ainda é válido. Como há custos de transação de rede, precisamos definir uma tolerância de tempo de emissão ao validar a reivindicação iat do token recebido. O id_token retornado é um JSON Web Token (JWT) padrão. Dependendo do framework que você está usando, você pode encontrar vários plugins convenientes de validação de tokens JWT para auxiliar na decodificação e validação do token. Para este exemplo, utilizaremos [jose](https://www.npmjs.com/package/jose) em nosso SDK JavaScript para facilitar a validação e decodificação do 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; }; ``` ### Obter informações do usuário Após a autenticação bem sucedida do usuário, as informações básicas do usuário podem ser recuperadas do `id_token` OIDC emitido pelo servidor de autorização. No entanto, devido a considerações de performance, o conteúdo do token JWT é limitado. Para obter mais detalhes do perfil do usuário, os servidores de autorização compatíveis com OIDC oferecem um endpoint de info do usuário pronto para uso. Este endpoint permite que você recupere dados adicionais do perfil do usuário ao solicitar scopes específicos do perfil do usuário. Ao chamar um endpoint de troca de token sem indicar um recurso API específico, o servidor de autorização emitirá, por padrão, um `access_token` do tipo opaco. Este `access_token` só pode ser usado para acessar o endpoint de info do usuário, permitindo a recuperação de dados básicos do perfil do usuário. ```ts async getUserInfo() { const { userinfoEndpoint } = await this.getOidcConfig(); const accessToken = await this.getAccessToken(); return fetch(userinfoEndpoint, { headers: { Authorization: `Bearer ${accessToken}` } }); } ``` ### Obter token de acesso para autorização de recurso protegido Na maioria dos casos, uma aplicação cliente não só requer autenticação de usuário, mas também precisa de autorização do usuário para acessar certos recursos protegidos ou endpoints de API. Aqui, usaremos o `refresh_token` obtido durante o login para adquirir `access_token(s)` especificamente concedidos para gerenciar recursos específicos. Isso nos permite obter acesso às APIs protegidas. Durante o login do usuário, é crucial fornecer todos os indicadores de recurso de API para o servidor de autorização. Após a autenticação bem sucedida, só podemos recuperar os `access_tokens` para os recursos especificados pré-configurados. Para conseguir isso, pré-configurar todos os indicadores de recurso de API necessários nas configurações do cliente da aplicação antes de gerar a URL de login. ```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, }); // save and replace the latest returned refreshToken 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); } ``` ## Resumo Nós fornecemos implementações essenciais do método para o processo de autenticação e autorização do usuário do aplicativo do lado do cliente. Dependendo do seu cenário específico, você pode organizar e otimizar a lógica do SDK de acordo. Por favor, note que podem existir variações devido a diferentes plataformas e frameworks. Para detalhes adicionais, explore os pacotes de SDK oferecidos pela Logto. Incentivamos mais usuários a se juntar ao desenvolvimento e participar de discussões conosco. Seu feedback e contribuições são altamente valorizados à medida que continuamos aprimorar e expandir as capacidades do SDK. ## Apêndice ### Reserved scopes Os escopos reservados Logto que você precisará passar durante a solicitação de autenticação inicial. Esses escopos são fundamentais reservados pela OIDC ou Logto para completar um fluxo de autorização bem sucedido. | Nome do Escopo | Descrição | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | openid | Reqxaderido para conceder `id_token` após uma autenticação bem sucedida. | | offline-access | Requerido para conceder um `refresh_token` que permite à sua aplicação cliente trocar e renovar um access_token fora da tela. | | profile | Requerido para obter acesso às informações básicas do usuário | ### Logto Config | Nome da propriedade | Tipo | Requerido | Descrição | Valor Padrão | | ------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | appId | string | true | O identificador único da aplicação. Gerado pelo servidor de autorização para identificar a aplicação cliente. | | | appSecret | string | | O segredo da aplicação é usado, junto com o ID da aplicação, para verificar a identidade do solicitante. É requerido para clientes confidenciais como aplicações web Go ou Next.js, e opcional para clientes públicos como aplicações nativas ou aplicações de página única (SPAs) | | | endpoint | string | true | Seu endpoint raiz do servidor de autorização. Esta propriedade será amplamente usada para gerar solicitações de autorização. | | | scopes | string list | | Indica todos os escopos de recurso necessários que o usuário pode precisar para ser concedido a fim de acessar qualquer recurso protegido dado. | [reservedScopes] | | resources | string list | | Todos os indicadores de recurso protegido que o usuário pode solicitar acesso | | ### Util methods #### generateRandomString ```ts const generateRandomString = (length = 64) => fromUint8Array(crypto.getRandomValues(new Uint8Array(length)), true); ``` Tente o Logto Cloud hoje