"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "como-funciona-as-reivindicações-personalizadas-jwt-do-logto", "hProperties": { "id": "como-funciona-as-reivindicações-personalizadas-jwt-do-logto" } }, "depth": 2, "value": "Como funciona as reivindicações personalizadas JWT do Logto?" }, { "data": { "id": "impulsione-sua-autorização-com-reivindicações-jwt-personalizadas-um-exemplo-prático", "hProperties": { "id": "impulsione-sua-autorização-com-reivindicações-jwt-personalizadas-um-exemplo-prático" } }, "depth": 2, "value": "Impulsione sua autorização com reivindicações JWT personalizadas: um exemplo prático" }, { "data": { "id": "configuração-do-cenário", "hProperties": { "id": "configuração-do-cenário" } }, "depth": 3, "value": "Configuração do cenário" }, { "data": { "id": "configurações-do-logto", "hProperties": { "id": "configurações-do-logto" } }, "depth": 3, "value": "Configurações do Logto" }, { "data": { "id": "verifique-se-a-funcionalidade-do-jwt-personalizado-está-ativada", "hProperties": { "id": "verifique-se-a-funcionalidade-do-jwt-personalizado-está-ativada" } }, "depth": 3, "value": "Verifique se a funcionalidade do JWT personalizado está ativada" }, { "data": { "id": "atualize-a-lógica-de-autorização-do-provedor-de-serviços", "hProperties": { "id": "atualize-a-lógica-de-autorização-do-provedor-de-serviços" } }, "depth": 3, "value": "Atualize a lógica de autorização do provedor de serviços" }, { "data": { "id": "por-que-usar-reivindicações-jwt-personalizadas", "hProperties": { "id": "por-que-usar-reivindicações-jwt-personalizadas" } }, "depth": 3, "value": "Por que usar reivindicações JWT personalizadas?" }, { "data": { "id": "conclusão", "hProperties": { "id": "conclusão" } }, "depth": 2, "value": "Conclusão" }]; const readingTime = { "minutes": 9, "words": 2564, "text": "9 min read" }; const frontmatter = undefined; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", h3: "h3", li: "li", ol: "ol", p: "p", pre: "pre", span: "span", ul: "ul", ..._provideComponents(), ...props.components }, {Info, LogtoCloudButton, Note} = _components; if (!Info) _missingMdxReference("Info", true); if (!LogtoCloudButton) _missingMdxReference("LogtoCloudButton", true); if (!Note) _missingMdxReference("Note", true); return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "Em artigos anteriores, mencionamos que cada vez mais sistemas estão utilizando tokens de acesso no formato JWT para autenticação de usuários e controle de acesso. Uma das razões importantes para isso é que o JWT pode conter algumas informações úteis, como funções e permissões do usuário. Essas informações podem nos ajudar a passar informações de identidade de usuário entre o servidor e o cliente, alcançando assim a autenticação de usuários e o controle de acesso." }), "\n", _jsxs(_components.p, { children: ["Normalmente, as informações contidas no JWT são determinadas pelo servidor de autenticação. De acordo com o protocolo OAuth 2.0, o JWT geralmente contém campos como ", _jsx(_components.code, { children: "sub" }), " (sujeito), ", _jsx(_components.code, { children: "aud" }), " (audiência) e ", _jsx(_components.code, { children: "exp" }), " (tempo de expiração), que são comumente referidos como reivindicações. Essas reivindicações podem ajudar a verificar a validade do token de acesso."] }), "\n", _jsx(_components.p, { children: "No entanto, existem inúmeros cenários em que o JWT é utilizado para verificação, e as reivindicações comuns de JWT frequentemente podem não atender às necessidades do usuário. As pessoas geralmente pensam que, como o JWT pode conter algumas informações, podemos adicionar algumas informações a ele para facilitar a autorização?" }), "\n", _jsx(_components.p, { children: "A resposta é SIM, podemos adicionar reivindicações personalizadas ao JWT, como o escopo do usuário atual e o nível de assinatura. Dessa forma, podemos passar informações de identidade do usuário entre o cliente e o servidor (aqui referindo-se ao servidor que fornece vários serviços diferentes, também chamado de provedor de serviços), para alcançar a autenticação de usuários e o controle de acesso." }), "\n", _jsxs(_components.p, { children: ["Para reivindicações padrão do JWT, consulte ", _jsx(_components.a, { href: "https://datatracker.ietf.org/doc/html/rfc7519", children: "RFC7519" }), ". O Logto, como uma solução de identidade que suporta tanto autenticação quanto autorização, estendeu as reivindicações de recurso e escopo com base nisso para suportar RBAC padrão ", _jsx(_components.a, { href: "https://docs.logto.io/docs/recipes/rbac/", children: "RBAC" }), ". Embora a implementação de RBAC do Logto seja padrão, ela não é simples e flexível o suficiente para se adequar a todos os casos de uso."] }), "\n", _jsx(_components.p, { children: "Com base nisso, o Logto lançou uma nova funcionalidade de personalização de reivindicações JWT, que permite que os usuários personalizem reivindicações adicionais ao JWT, para que a autenticação de usuários e o controle de acesso possam ser implementados de forma mais flexível." }), "\n", _jsx(LogtoCloudButton, {}), "\n", _jsxs(_components.h2, { id: "como-funciona-as-reivindicações-personalizadas-jwt-do-logto", children: ["Como funciona as reivindicações personalizadas JWT do Logto?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#como-funciona-as-reivindicações-personalizadas-jwt-do-logto", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Você pode acessar a página de listagem de JWT personalizados clicando no botão \"JWT claims\" na barra lateral." }), "\n", _jsx("center", { children: _jsx("img", { alt: "custom-jwt-listing-page", src: "https://uploads.strapi.logto.io/1/custom_jwt_listing_page_f56a88c98f.webp", width: "800" }) }), "\n", _jsx(_components.p, { children: "Vamos começar adicionando reivindicações personalizadas para os usuários finais." }), "\n", _jsxs(_components.p, { children: ["No editor à esquerda, você pode personalizar sua função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), ". Este método possui três parâmetros de entrada: ", _jsx(_components.code, { children: "token" }), ", ", _jsx(_components.code, { children: "data" }), " e ", _jsx(_components.code, { children: "envVariables" }), "."] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "token" }), " é o payload bruto do token de acesso obtido com base nas credenciais do usuário final atual e na configuração do seu sistema, e as informações de acesso do usuário no Logto."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "data" }), " é toda a informação sobre o usuário no Logto, incluindo todas as funções do usuário, identidades de login social, identidades de SSO, membros de organizações, etc."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "envVariables" }), " são as variáveis de ambiente que você configurou no Logto para o cenário de uso do token de acesso do usuário final atual, como chave(s) de API dos APIs externos necessários, etc."] }), "\n"] }), "\n", _jsx("center", { children: _jsx("img", { alt: "details-page-user-data", src: "https://uploads.strapi.logto.io/1/details_page_user_data_a92388f24a.webp", width: "800" }) }), "\n", _jsx(_components.p, { children: "Os cards à direita podem ser expandidos para mostrar a introdução dos parâmetros correspondentes, e você também pode configurar as variáveis de ambiente para o cenário atual aqui." }), "\n", _jsx("center", { children: _jsx("img", { alt: "details-page-user-test", src: "https://uploads.strapi.logto.io/1/details_page_user_test_93932f6e66.webp", width: "800" }) }), "\n", _jsx(_components.p, { children: "Após ler as introduções de todos os cards à direita, você pode mudar para o modo de teste, onde poderá editar os dados de teste e usar os dados de teste editados para verificar se o comportamento do script que você escreveu no editor de código à esquerda atende às suas expectativas." }), "\n", _jsxs(_components.p, { children: ["Este é um diagrama de sequência mostrando o processo de execução da função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " quando um usuário final inicia uma solicitação de autenticação ao Logto e eventualmente obtém o token de acesso no formato JWT retornado pelo Logto."] }), "\n", _jsxs(_components.p, { children: ["Se a funcionalidade JWT personalizada não estiver ativada, a etapa 3 na figura será ignorada e a etapa 4 será executada logo após o término da etapa 2. Nesse momento, o Logto assumirá que o valor de retorno de ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " será um objeto vazio, e então continuará a passar pelas etapas subsequentes."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant U as Usuário ou agente do usuário\n participant IdP as Logto (provedor de identidade)\n participant SP as Provedor de Serviço\n\n autonumber\n U ->> IdP: Requisição de Autenticação (com credenciais)\n activate IdP\n IdP-->>IdP: Validar credenciais &
gerar payload de token de acesso bruto\n rect rgb(191, 223, 255)\n note over IdP: JWT Personalizado\n IdP->>IdP: Executar script de reivindicações JWT personalizadas (`getCustomJwtClaims`) &
obter reivindicações JWT extras\n end\n IdP-->>IdP: Mesclar payload de token de acesso bruto e reivindicações JWT extras\n IdP-->>IdP: Assinar & criptografar payload para obter token de acesso JWT\n deactivate IdP\n IdP-->>U: Emitir token de acesso no formato JWT\n par Obter serviço via API\n U->>SP: requisição de serviço (com token de acesso JWT)\n SP-->>U: resposta do serviço\n end\n" }) }), "\n", _jsx(Note, { children: _jsxs(_components.p, { children: ["Por motivos de segurança, se as reivindicações JWT retornadas pela função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " do Logto já\nexistirem no payload do token de acesso, essas reivindicações NÃO terão efeito e NÃO poderão\nsobrescrever as reivindicações existentes."] }) }), "\n", _jsxs(_components.h2, { id: "impulsione-sua-autorização-com-reivindicações-jwt-personalizadas-um-exemplo-prático", children: ["Impulsione sua autorização com reivindicações JWT personalizadas: um exemplo prático", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#impulsione-sua-autorização-com-reivindicações-jwt-personalizadas-um-exemplo-prático", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Na seção anterior, apresentamos o princípio de funcionamento do JWT personalizado do Logto. Nesta parte, vamos mostrar como usar as reivindicações JWT personalizadas do Logto para melhorar a flexibilidade da autorização e o desempenho do provedor de serviços através de um exemplo real." }), "\n", _jsxs(_components.h3, { id: "configuração-do-cenário", children: ["Configuração do cenário", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#configuração-do-cenário", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "A equipe de John desenvolveu um App Assistente de IA que permite aos usuários conversar com robôs de IA para obter vários serviços." }), "\n", _jsx(_components.p, { children: "Os serviços de robô de IA são divididos em serviços gratuitos e pagos. Os serviços gratuitos incluem recomendações especiais de tarifas aéreas, enquanto os serviços pagos incluem previsões de ações." }), "\n", _jsx(_components.p, { children: "O App Assistente de IA usa o Logto para gerenciar todos os usuários, que são divididos em três tipos: usuários gratuitos, usuários pré-pagos e usuários premium. Usuários gratuitos podem usar apenas serviços gratuitos, usuários pré-pagos podem usar todos os serviços (cobrados por uso) e usuários premium podem usar todos os serviços (mas têm limites de taxa para evitar uso malicioso)." }), "\n", _jsx(_components.p, { children: "Além disso, o App Assistente de IA usa o Stripe para gerenciar pagamentos de usuários e possui seu próprio serviço de log para registrar logs de operações dos usuários." }), "\n", _jsxs(_components.h3, { id: "configurações-do-logto", children: ["Configurações do Logto", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#configurações-do-logto", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["Primeiro, criamos recursos de API para o serviço do App Assistente de IA e criamos dois escopos, ", _jsx(_components.code, { children: "recommend:flight" }), " e ", _jsx(_components.code, { children: "predict:stock" }), "."] }), "\n", _jsx("center", { children: _jsx("img", { alt: "ai-assistant-app-resource", src: "https://uploads.strapi.logto.io/1/ai_assistant_app_resource_e3c2ee0f03.webp", width: "800" }) }), "\n", _jsxs(_components.p, { children: ["Em seguida, criamos dois ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "free-user" }), " e ", _jsx(_components.code, { children: "paid-user" }), ", e atribuimos os escopos correspondentes:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Atribua o escopo ", _jsx(_components.code, { children: "recommend:flight" }), " ao papel ", _jsx(_components.code, { children: "free-user" }), "."] }), "\n", _jsxs(_components.li, { children: ["Atribua ambos os escopos ", _jsx(_components.code, { children: "recommend:flight" }), " e ", _jsx(_components.code, { children: "predict:stock" }), " ao papel ", _jsx(_components.code, { children: "paid-user" }), "."] }), "\n"] }), "\n", _jsx("center", { children: _jsx("img", { alt: "free-user-role", src: "https://uploads.strapi.logto.io/1/free_user_role_153a0277ba.webp", width: "800" }) }), "\n", _jsx("center", { children: _jsx("img", { alt: "paid-user-role", src: "https://uploads.strapi.logto.io/1/paid_user_role_d2fa9f5db6.webp", width: "800" }) }), "\n", _jsxs(_components.p, { children: ["Finalmente, criamos três usuários, ", _jsx(_components.code, { children: "free-user" }), ", ", _jsx(_components.code, { children: "prepaid-user" }), " e ", _jsx(_components.code, { children: "premium-user" }), ", e atribuímos os papéis correspondentes:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Atribua o papel ", _jsx(_components.code, { children: "free-user" }), " ao usuário ", _jsx(_components.code, { children: "free-user" }), "."] }), "\n", _jsxs(_components.li, { children: ["Atribua o papel ", _jsx(_components.code, { children: "paid-user" }), " aos usuários ", _jsx(_components.code, { children: "prepaid-user" }), " e ", _jsx(_components.code, { children: "premium-user" }), "."] }), "\n"] }), "\n", _jsx("center", { children: _jsx("img", { alt: "assign-free-user-role", src: "https://uploads.strapi.logto.io/1/assign_free_user_role_f7d37cb5c9.webp", width: "800" }) }), "\n", _jsx("center", { children: _jsx("img", { alt: "assign-paid-user-role", src: "https://uploads.strapi.logto.io/1/assign_paid_user_role_2dbfd74d6e.webp", width: "800" }) }), "\n", _jsxs(_components.p, { children: ["Conforme mostrado na figura a seguir, para implementar as informações de autorização necessárias para o cenário descrito acima, esperamos incluir as informações de ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), " e ", _jsx(_components.code, { children: "numOfCallsToday" }), " do usuário atualmente logado no JWT. Ao verificar o token de acesso no App Assistente de IA, essas informações podem ser usadas para rapidamente realizar a verificação de permissões."] }), "\n", _jsx("center", { children: _jsx("img", { alt: "test-custom-jwt-claims", src: "https://uploads.strapi.logto.io/1/test_custom_jwt_claims_3fcd4c2004.webp", width: "800" }) }), "\n", _jsxs(_components.p, { children: ["Após configurar as ", _jsx(_components.code, { children: "envVariables" }), ", implementamos a função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " e clicamos no botão \"Run test\" para ver o resultado das reivindicações JWT extras com base nos dados de teste atuais."] }), "\n", _jsxs(_components.p, { children: ["Como não configuramos os dados de teste para ", _jsx(_components.code, { children: "data.user.roles" }), ", as ", _jsx(_components.code, { children: "roles" }), " mostradas no resultado são um array vazio."] }), "\n", _jsxs(_components.h3, { id: "verifique-se-a-funcionalidade-do-jwt-personalizado-está-ativada", children: ["Verifique se a funcionalidade do JWT personalizado está ativada", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#verifique-se-a-funcionalidade-do-jwt-personalizado-está-ativada", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["De acordo com a configuração do Logto acima, obtivemos os resultados correspondentes no teste. Em seguida, vamos usar o app de amostra fornecido pelo Logto para verificar se nosso JWT personalizado está funcionando. Encontre o SDK com o qual você está familiarizado em ", _jsx(_components.a, { href: "https://docs.logto.io/sdk/", children: "Logto SDKs" }), " e implante um app de amostra de acordo com a documentação e o repositório correspondente no GitHub."] }), "\n", _jsxs(_components.p, { children: ["Com base na configuração que descrevemos acima, levando o ", _jsx(_components.a, { href: "https://docs.logto.io/sdk/react/", children: "React SDK" }), " como exemplo, precisamos atualizar a configuração correspondente no LogtoConfig:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-ts", children: "import { LogtoProvider, LogtoConfig, UserScope } from '@logto/react';\n\nconst config: LogtoConfig = {\n appId,\n endpoint,\n scopes: [\n UserScope.Email,\n UserScope.Phone,\n UserScope.CustomData,\n UserScope.Identities,\n UserScope.Organizations,\n \"recommend:flight\",\n \"predict:stock\",\n ],\n resources: [\"https://api.aiassistant.app/v1\"]\n};\n\nconst App = () => (\n \n \n \n);\n" }) }), "\n", _jsxs(_components.p, { children: ["Após fazer o login do usuário ", _jsx(_components.code, { children: "free_user" }), " no app de amostra que simula o App Assistente de IA, podemos ver as informações de ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), ", ", _jsx(_components.code, { children: "numOfCallsToday" }), ", ", _jsx(_components.code, { children: "isPaidUser" }), " e ", _jsx(_components.code, { children: "isPremiumUser" }), " que adicionamos visualizando a parte do payload do token de acesso JWT."] }), "\n", _jsx("center", { children: _jsx("img", { alt: "sample-app-access-token-preview-free", src: "https://uploads.strapi.logto.io/1/sample_app_access_token_preview_free_117a8594c8.webp", width: "400" }) }), "\n", _jsxs(_components.p, { children: ["Os valores de ", _jsx(_components.code, { children: "balance" }), ", ", _jsx(_components.code, { children: "numOfCallsToday" }), ", ", _jsx(_components.code, { children: "isPaidUser" }), " e ", _jsx(_components.code, { children: "isPremiumUser" }), " são consistentes com o teste anterior, e ", _jsx(_components.code, { children: "roles" }), " é igual a ", _jsx(_components.code, { children: "[\"free-user\"]" }), ". Isso porque, no processo real de login do usuário final, obteremos todos os dados acessíveis do usuário e os processaremos de acordo."] }), "\n", _jsx("center", { children: _jsx("img", { alt: "sample-app-access-token-preview-premium", src: "https://uploads.strapi.logto.io/1/sample_app_access_token_preview_premium_673f6f3db1.webp", width: "400" }) }), "\n", _jsxs(_components.p, { children: ["Para usuários premium, podemos ver que ", _jsx(_components.code, { children: "roles" }), " é ", _jsx(_components.code, { children: "[\"paid-user\"]" }), " e tanto ", _jsx(_components.code, { children: "isPaidUser" }), " quanto ", _jsx(_components.code, { children: "isPremiumUser" }), " são ", _jsx(_components.code, { children: "true" }), "."] }), "\n", _jsxs(_components.h3, { id: "atualize-a-lógica-de-autorização-do-provedor-de-serviços", children: ["Atualize a lógica de autorização do provedor de serviços", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#atualize-a-lógica-de-autorização-do-provedor-de-serviços", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Nos passos anteriores, adicionamos reivindicações personalizadas com base nas necessidades de negócios ao token de acesso de usuário. Em seguida, podemos usar essas reivindicações para realizar a verificação de autorização rapidamente." }), "\n", _jsxs(Note, { children: [_jsx(_components.p, { children: "É importante notar que nós não recomendamos confiar inteiramente em reivindicações personalizadas para verificação de autorização." }), _jsx(_components.p, { children: "Como a implementação do RBAC segue o princípio do menor privilégio, para garantir a segurança, a verificação usando reivindicações personalizadas deve ser uma verificação auxiliar adicional com base no RBAC. Isso para evitar expandir o escopo das permissões de autorização do usuário devido à introdução de reivindicações personalizadas adicionais." })] }), "\n", _jsxs(_components.p, { children: ["Aqui fornecemos a lógica do Logto para verificar tokens de acesso JWT no lado da API. A implementação completa do código pode ser encontrada no ", _jsx(_components.a, { href: "https://github.com/logto-io/logto/blob/master/packages/core/src/middleware/koa-auth/index.ts", children: "repositório do GitHub" }), ":"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-ts", children: "import type { IncomingHttpHeaders } from 'node:http';\n\nimport { createLocalJWKSet, jwtVerify, type JWK } from 'jose';\n\nconst extractBearerTokenFromHeaders = (\n { authorization }: IncomingHttpHeaders\n) => {\n const bearerTokenIdentifier = 'Bearer';\n\n assertThat(\n authorization,\n new RequestError({\n code: 'auth.authorization_header_missing',\n status: 401\n })\n );\n assertThat(\n authorization.startsWith(bearerTokenIdentifier),\n new RequestError(\n { code: 'auth.authorization_token_type_not_supported', status: 401 },\n { supportedTypes: [bearerTokenIdentifier] }\n )\n );\n\n return authorization.slice(bearerTokenIdentifier.length + 1);\n};\n\nconst verifyBearerTokenFromRequest = async (\n publicJwks: JWT;\n issuer: string,\n request: Request,\n audience: Optional\n): Promise => {\n try {\n // Obtenha as JWKs públicas e o emissor.\n const [keys, issuer] = await getKeysAndIssuer();\n const { payload } = await jwtVerify(\n extractBearerTokenFromHeaders(request.headers),\n createLocalJWKSet({ keys }),\n {\n issuer,\n audience,\n }\n );\n\n const { sub, client_id: clientId, scope = '' } = payload;\n assertThat(sub,\n new RequestError({ code: 'auth.jwt_sub_missing', status: 401 }));\n\n return { sub, clientId, scopes: z.string().parse(scope).split(' ') };\n } catch (error: unknown) {\n if (error instanceof RequestError) {\n throw error;\n }\n\n throw new RequestError(\n { code: 'auth.unauthorized', status: 401 },\n error\n );\n }\n};\n" }) }), "\n", _jsxs(_components.p, { children: ["Você pode se referir à lógica da API do Logto para verificar tokens de acesso e personalizá-la de acordo com sua própria lógica de negócios. Por exemplo, para o cenário do App Assistente de IA descrito aqui, você pode adicionar a lógica de verificação para reivindicações personalizadas como ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), ", ", _jsx(_components.code, { children: "numOfCallsToday" }), ", ", _jsx(_components.code, { children: "isPaidUser" }), " e ", _jsx(_components.code, { children: "isPremiumUser" }), " na função ", _jsx(_components.code, { children: "verifyBearerTokenFromRequest" }), "."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-ts", children: "const verifyBearerTokenFromRequest = async (\n publicJwks: JWT;\n issuer: string,\n request: Request,\n audience: Optional\n): Promise => {\n try {\n // Obtenha as JWKs públicas e o emissor.\n const [keys, issuer] = await getKeysAndIssuer();\n const { payload } = await jwtVerify(\n extractBearerTokenFromHeaders(request.headers),\n createLocalJWKSet({ keys }),\n {\n issuer,\n audience,\n }\n );\n\n const {\n sub,\n client_id: clientId,\n roles,\n balance,\n numOfCallsToday,\n isPaidUser,\n isPremiumUser,\n scope = ''\n } = payload;\n assertThat(sub,\n new RequestError({ code: 'auth.jwt_sub_missing', status: 401 }));\n\n return {\n sub,\n clientId,\n scopes: z.string().parse(scope).split(' '),\n roles,\n balance,\n numOfCallsToday,\n isPaidUser,\n isPremiumUser\n };\n } catch (error: unknown) {\n if (error instanceof RequestError) {\n throw error;\n }\n\n throw new RequestError({ code: 'auth.unauthorized', status: 401 }, error);\n }\n};\n\nconst authorizeBearerTokenPayload = (\n payload: Payload,\n requiredScopes: string[],\n requiredRoles: string[]\n): void => {\n const {\n scope,\n roles,\n balance,\n numOfCallsToday,\n isPaidUser,\n isPremiumUser\n } = payload;\n const scopes: string[] = scope.split(' ');\n\n // Validação RBAC.\n /**\n * `free-user` não possui o escopo `predict:stock`, então se a API exigir\n * o escopo `predict:stock`, a solicitação será rejeitada diretamente.\n */\n assertThat(\n requiredScopes.every((scope) => payload.scopes.includes(scope)),\n new RequestError(\n { code: 'auth.insufficient_scope', status: 403 },\n { requiredScopes })\n );\n\n /** Validação sobre reivindicações extras no `payload`. */\n assertThat(\n roles.includes('paid-user') && isPaidUser,\n new RequestError({ code: 'auth.role_mismatch', status: 403 }));\n // Suponha que o limite de chamadas diárias seja 100.\n assertThat(\n numOfCallsToday < 100,\n new RequestError({ code: 'auth.rate_limit_exceeded', status: 403 }));\n // Não há necessidade de verificar o `balance` dos usuários premium.\n if (isPremiumUser) {\n return;\n }\n // Pode acessar o serviço apenas quando o saldo for positivo.\n assertThat(\n balance > 0,\n new RequestError({ code: 'auth.balance_insufficient', status: 403 }));\n /** Validação sobre reivindicações extras no `payload`. */\n};\n" }) }), "\n", _jsx(_components.p, { children: "O exemplo acima é para o cenário em que afeta o login do usuário final e a obtenção do token de acesso JWT. Se seu caso de uso for máquina a máquina (M2M), você também pode configurar reivindicações personalizadas JWT para aplicativos M2M separadamente." }), "\n", _jsx(_components.p, { children: "Configurar JWT personalizados para usuários não afetará o resultado de aplicativos M2M obtendo tokens de acesso, e vice-versa." }), "\n", _jsxs(_components.p, { children: ["Devido à generalidade das conexões M2M, o Logto atualmente não fornece a função do método ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " de aplicativos M2M para aceitar dados internos do Logto. Em outros aspectos, o método de configuração de JWT personalizados para aplicativos M2M é o mesmo que para aplicativos de usuários. Este artigo não detalhará sobre isso. Você pode usar a função de JWT personalizados do Logto para começar."] }), "\n", _jsxs(_components.h3, { id: "por-que-usar-reivindicações-jwt-personalizadas", children: ["Por que usar reivindicações JWT personalizadas?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#por-que-usar-reivindicações-jwt-personalizadas", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Fornecemos o cenário do App Assistente de IA para John e como usar a funcionalidade de JWT Personalizado do Logto para alcançar uma verificação de autorização mais flexível. Nesse processo, podemos ver as vantagens da funcionalidade JWT Personalizado:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["Sem a funcionalidade JWT Personalizado, os usuários precisam solicitar uma API externa (como o que você faz em ", _jsx(_components.code, { children: "getCustomJwtClaims" }), ") toda vez que verificam permissões. Para o provedor de serviços que fornece essa API, isso pode aumentar a carga extra. Com a funcionalidade JWT Personalizado, essas informações podem ser colocadas diretamente no JWT, reduzindo as chamadas frequentes à API externa."] }), "\n", _jsx(_components.li, { children: "Para provedores de serviços, a funcionalidade JWT Personalizado pode ajudá-los a verificar as permissões do usuário mais rapidamente, especialmente quando o cliente chama o provedor de serviços com frequência, melhorando o desempenho do serviço." }), "\n", _jsx(_components.li, { children: "A funcionalidade JWT Personalizado pode ajudá-lo a implementar rapidamente as informações adicionais de autorização exigidas pelo negócio, e as informações podem ser transmitidas entre o cliente e o provedor de serviços de maneira segura, uma vez que o JWT é auto-contido e pode ser criptografado, tornando difícil sua falsificação." }), "\n"] }), "\n", _jsx(Info, { children: _jsx(_components.p, { children: "É importante notar que, como mencionamos em um post anterior do blog, uma vez que um token de acesso JWT é\nemitido, ele não mudará durante seu período de validade. Portanto, as informações contidas nas\nreivindicações JWT personalizadas devem ser combinadas com as necessidades reais de negócios e evitar incluir informações\nque são importantes para autorização, mas que mudam drasticamente durante o período de validade do\ntoken de acesso." }) }), "\n", _jsxs(_components.p, { children: ["Ao mesmo tempo, uma vez que o ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " é executado toda vez que um usuário precisa que o Logto emita um token de acesso, é necessário evitar executar lógicas excessivamente complexas e solicitações de APIs externas com alto requisito de largura de banda. Caso contrário, pode demorar muito para os usuários finais esperarem o resultado de ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " durante o processo de login. Se o seu ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " retornar um objeto vazio, recomendamos fortemente que você exclua temporariamente este item de configuração até que você realmente precise usá-lo."] }), "\n", _jsxs(_components.h2, { id: "conclusão", children: ["Conclusão", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#conclusão", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Neste artigo, o Logto estendeu o token de acesso JWT básico e estendeu a funcionalidade de reivindicações JWT extras para permitir que os usuários coloquem informações adicionais do usuário final no token de acesso JWT de acordo com suas necessidades de negócios, para que, após o usuário se logar, as permissões do usuário possam ser verificadas rapidamente." }), "\n", _jsx(_components.p, { children: "Fornecemos o cenário do App Assistente de IA de John e demonstramos como usar a funcionalidade JWT Personalizado do Logto para alcançar uma verificação de autorização mais flexível. Também apontamos alguns pontos-chave ao usar o JWT personalizado. Em combinação com cenários de negócios reais, os usuários podem inserir várias informações relacionadas ao usuário no token de acesso JWT de acordo com suas necessidades de negócios, permitindo que o provedor de serviços verifique rapidamente as permissões do usuário." }), "\n", _jsx(LogtoCloudButton, {})] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { headings, readingTime, frontmatter, default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }