"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "como-funciona-a-personalização-de-jwt-claims-no-logto", "hProperties": { "id": "como-funciona-a-personalização-de-jwt-claims-no-logto" } }, "depth": 2, "value": "Como funciona a personalização de JWT Claims no Logto?" }, { "data": { "id": "reforça-a-tua-autorização-com-claims-jwt-personalizadas-um-exemplo-prático", "hProperties": { "id": "reforça-a-tua-autorização-com-claims-jwt-personalizadas-um-exemplo-prático" } }, "depth": 2, "value": "Reforça a tua autorização com claims 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": "verifica-se-a-funcionalidade-jwt-personalizada-está-ativa", "hProperties": { "id": "verifica-se-a-funcionalidade-jwt-personalizada-está-ativa" } }, "depth": 3, "value": "Verifica se a funcionalidade JWT personalizada está ativa" }, { "data": { "id": "atualizar-lógica-de-autorização-do-fornecedor-de-serviços", "hProperties": { "id": "atualizar-lógica-de-autorização-do-fornecedor-de-serviços" } }, "depth": 3, "value": "Atualizar lógica de autorização do fornecedor de serviços" }, { "data": { "id": "por-que-usar-claims-jwt-personalizadas", "hProperties": { "id": "por-que-usar-claims-jwt-personalizadas" } }, "depth": 3, "value": "Por que usar claims JWT personalizadas?" }, { "data": { "id": "conclusão", "hProperties": { "id": "conclusão" } }, "depth": 2, "value": "Conclusão" }]; const readingTime = { "minutes": 9, "words": 2554, "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, mencionámos que mais e mais sistemas estão a usar tokens de acesso no formato JWT para autenticação de usuários e controlo de acesso. Uma das razões importantes para isso é que o JWT pode conter algumas informações úteis, como papéis e permissões de usuário. Estas informações podem ajudar-nos a passar informações de identidade do usuário entre o servidor e o cliente, alcançando assim a autenticação de usuários e controlo de acesso." }), "\n", _jsxs(_components.p, { children: ["Geralmente, as informações contidas no JWT são determinadas pelo servidor de autenticação. De acordo com o protocolo OAuth 2.0, o JWT costuma conter campos como ", _jsx(_components.code, { children: "sub" }), " (assunto), ", _jsx(_components.code, { children: "aud" }), " (audiência) e ", _jsx(_components.code, { children: "exp" }), " (tempo de expiração), que são frequentemente referidos como claims. Estes claims podem ajudar a verificar a validade do token de acesso."] }), "\n", _jsx(_components.p, { children: "No entanto, há inúmeros cenários onde o JWT é utilizado para verificação, e as claims comuns de JWT podem frequentemente não satisfazer as necessidades do usuário. As pessoas costumam pensar que, como o JWT pode conter algumas informações, poderíamos adicionar algumas informações nele para facilitar a autorização?" }), "\n", _jsx(_components.p, { children: "A resposta é SIM, podemos adicionar claims personalizadas ao JWT, como o escopo e o nível de subscrição do usuário atual. Dessa forma, podemos passar informações de identidade do usuário entre o cliente e o servidor (aqui refere-se ao servidor que fornece vários serviços diferentes, também chamado de fornecedor de serviços), para alcançar a autenticação do usuário e o controlo de acesso." }), "\n", _jsxs(_components.p, { children: ["Para claims padrão de JWT, por favor, consulta ", _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 como autorização, estendeu as claims de recurso e escopo com base nisso para suportar ", _jsx(_components.a, { href: "https://docs.logto.io/docs/recipes/rbac/", children: "RBAC" }), " padrão. Embora a implementação do 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 um novo recurso de personalização de claims JWT, que permite aos usuários personalizarem claims adicionais de JWT, tornando a autenticação de usuários e o controlo de acesso mais flexíveis." }), "\n", _jsx(LogtoCloudButton, {}), "\n", _jsxs(_components.h2, { id: "como-funciona-a-personalização-de-jwt-claims-no-logto", children: ["Como funciona a personalização de JWT Claims no Logto?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#como-funciona-a-personalização-de-jwt-claims-no-logto", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Podes aceder à página de listagem de JWT personalizada 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 claims personalizadas para os usuários finais." }), "\n", _jsxs(_components.p, { children: ["No editor à esquerda, podes personalizar a tua função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), ". Este método tem 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 teu sistema, e as informações do usuário relacionadas com acesso no Logto"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "data" }), " é toda a informação sobre o usuário no Logto, incluindo todos os papéis do usuário, identidades de login social, identidades de SSO, associações a organizações, etc."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "envVariables" }), " são as variáveis de ambiente que configuraste no Logto para o cenário de uso do token de acesso do usuário final, 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 cartões à direita podem ser expandidos para mostrar a introdução dos parâmetros correspondentes, e também podes definir 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: "Depois de leres as introduções de todos os cartões à direita, podes mudar para o modo de teste, onde podes editar os dados de teste e usar os dados de teste editados para verificar se o comportamento do script que escreveste no editor de código à esquerda corresponde às tuas expectativas." }), "\n", _jsxs(_components.p, { children: ["Este é um diagrama de sequência que mostra o processo de execução da função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " quando um usuário final inicia um pedido de autenticação para o Logto e eventualmente obtém o token de acesso no formato JWT retornado pelo Logto."] }), "\n", _jsxs(_components.p, { children: ["Se a funcionalidade de JWT Personalizado não estiver ativada, a etapa 3 no diagrama será ignorada e a etapa 4 será executada logo após o término da etapa 2. Neste ponto, o Logto assumirá que o valor retornado da ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " é um objeto vazio, e então continuará a passar pelos passos subsequentes."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant U as Usuário ou agente de usuário\n participant IdP como Logto (fornecedor de identidade)\n participant SP como Fornecedor de Serviços\n\n autonumber\n U ->> IdP: Pedido de Auth (com credenciais)\n activate IdP\n IdP-->>IdP: Validar credenciais &
gerar payload bruto do token de acesso\n rect rgb(191, 223, 255)\n note over IdP: JWT Personalizado\n IdP->>IdP: Executar script de claims JWT personalizadas (`getCustomJwtClaims`) &
obter claims JWT extra\n end\n IdP-->>IdP: Mesclar payload bruto do token de acesso e claims JWT extra\n IdP-->>IdP: Assinar & encriptar 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: pedido de serviço (com token de acesso JWT)\n SP-->>U: Resposta de serviço\n end\n" }) }), "\n", _jsx(Note, { children: _jsxs(_components.p, { children: ["Por razões de segurança, se as claims JWT retornadas pela função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " do Logto já\nexistirem no payload do token de acesso, estas claims NÃO terão efeito e NÃO poderão\nsobrescrever as claims existentes."] }) }), "\n", _jsxs(_components.h2, { id: "reforça-a-tua-autorização-com-claims-jwt-personalizadas-um-exemplo-prático", children: ["Reforça a tua autorização com claims JWT personalizadas: um exemplo prático", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#reforça-a-tua-autorização-com-claims-jwt-personalizadas-um-exemplo-prático", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Na seção anterior, introduzimos o princípio de funcionamento do JWT personalizado do Logto. Nesta parte, vamos mostrar como usar claims personalizadas JWT do Logto para melhorar a flexibilidade da autorização e o desempenho do fornecedor 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 equipa do John desenvolveu um app Assistente de IA que permite aos usuários conversarem com robôs de IA para obter vários serviços." }), "\n", _jsx(_components.p, { children: "Os serviços do robô de IA são divididos em serviços gratuitos e pagos. Os serviços gratuitos incluem recomendações de tarifas aéreas especiais, 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 gerir 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 apenas usar serviços gratuitos, usuários pré-pagos podem usar todos os serviços (cobrados por utilização), e usuários premium podem usar todos os serviços (mas têm limites de taxa para prevenir uso malicioso)." }), "\n", _jsx(_components.p, { children: "Além disso, o app Assistente de IA usa o Stripe para gerir pagamentos dos usuários e tem seu próprio serviço de logs para gravar logs das 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: ["Depois, criamos dois ", _jsx(_components.code, { children: "papéis" }), ", ", _jsx(_components.code, { children: "free-user" }), " e ", _jsx(_components.code, { children: "paid-user" }), ", e atribuímos os escopos correspondentes:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Atribuímos o escopo ", _jsx(_components.code, { children: "recommend:flight" }), " ao papel ", _jsx(_components.code, { children: "free-user" }), "."] }), "\n", _jsxs(_components.li, { children: ["Atribuímos tanto ", _jsx(_components.code, { children: "recommend:flight" }), " quanto ", _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: ["Atribuímos o papel ", _jsx(_components.code, { children: "free-user" }), " ao usuário ", _jsx(_components.code, { children: "free-user" }), "."] }), "\n", _jsxs(_components.li, { children: ["Atribuímos 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: ["Como mostrado na imagem a seguir, para implementar as informações de autorização necessárias para o cenário descrito acima, esperamos incluir as informações sobre ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), " e ", _jsx(_components.code, { children: "numOfCallsToday" }), " do usuário atualmente conectado no JWT. Ao verificar o token de acesso no app Assistente de IA, essas informações podem ser usadas para realizar rapidamente 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 o ", _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 claims JWT extra com base nos dados de teste atuais."] }), "\n", _jsxs(_components.p, { children: ["Como não configurámos os dados de teste para ", _jsx(_components.code, { children: "data.user.roles" }), ", os ", _jsx(_components.code, { children: "roles" }), " apresentados no resultado são um array vazio."] }), "\n", _jsxs(_components.h3, { id: "verifica-se-a-funcionalidade-jwt-personalizada-está-ativa", children: ["Verifica se a funcionalidade JWT personalizada está ativa", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#verifica-se-a-funcionalidade-jwt-personalizada-está-ativa", 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, usaremos o app de amostra fornecido pelo Logto para verificar se o nosso JWT personalizado é eficaz. Encontra o SDK com o qual estás familiarizado em ", _jsx(_components.a, { href: "https://docs.logto.io/sdk/", children: "Logto SDKs" }), " e implanta um app de amostra de acordo com a documentação e o repositório no GitHub correspondente."] }), "\n", _jsxs(_components.p, { children: ["Com base na configuração que descrevemos acima, tomando 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 conectar o 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 adicionámos 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 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: "atualizar-lógica-de-autorização-do-fornecedor-de-serviços", children: ["Atualizar lógica de autorização do fornecedor de serviços", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#atualizar-lógica-de-autorização-do-fornecedor-de-serviços", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Nos passos anteriores, adicionámos claims personalizadas com base nas necessidades de negócios ao token de acesso do usuário. A seguir, podemos usar essas claims para realizar rapidamente a verificação de autorização." }), "\n", _jsxs(Note, { children: [_jsx(_components.p, { children: "É importante notar que não recomendamos confiar inteiramente em claims personalizadas para verificação de autorização." }), _jsx(_components.p, { children: "Uma vez que a implementação de RBAC segue o princípio do privilégio mínimo, para garantir a segurança, a verificação utilizando claims personalizadas deve ser uma verificação auxiliar adicional com base em RBAC. Isso é para evitar expandir o escopo das permissões de autorização do usuário devido à introdução de claims personalizadas adicionais." })] }), "\n", _jsxs(_components.p, { children: ["Aqui fornecemos a lógica de 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 no 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 // Obter os JWKs públicos 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: ["Podes consultar a lógica da API de Logto para verificar tokens de acesso e personalizá-la de acordo com a tua própria lógica de negócios. Por exemplo, para o cenário do app Assistente de IA descrito aqui, podes adicionar a lógica de verificação para claims 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 // Obter os JWKs públicos 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 tem o escopo `predict:stock`, então se a API requerer\n * o escopo de `predict:stock`, o pedido será rejeitado 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 em claims adicionais no `payload`. */\n assertThat(\n roles.includes('paid-user') && isPaidUser,\n new RequestError({ code: 'auth.role_mismatch', status: 403 }));\n // Supondo que o limite de chamadas diárias é 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` de 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 em claims adicionais no `payload`. */\n};\n" }) }), "\n", _jsx(_components.p, { children: "O exemplo acima é para o cenário onde afeta o login do usuário final e a obtenção do token de acesso JWT. Se o teu caso de uso for máquina-a-máquina (M2M), também podes configurar claims JWT personalizadas para apps M2M separadamente." }), "\n", _jsx(_components.p, { children: "Configurar JWT personalizadas para usuários não afetará o resultado das apps 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 funcionalidade do método ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " de apps M2M para aceitar dados internos do Logto. Em outros aspetos, o método de configuração de claims JWT personalizadas para apps M2M é igual ao das apps de usuários. Este artigo não vai elaborar sobre isso. Podes usar a funcionalidade de JWT personalizada do Logto para começares."] }), "\n", _jsxs(_components.h3, { id: "por-que-usar-claims-jwt-personalizadas", children: ["Por que usar claims JWT personalizadas?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#por-que-usar-claims-jwt-personalizadas", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Fornecemos o cenário do app Assistente de IA para o John e como usar a funcionalidade de JWT personalizada do Logto para obter verificações de autorização mais flexíveis. Neste processo, podemos ver as vantagens da funcionalidade de JWT personalizada:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["Sem a funcionalidade de JWT personalizada, os usuários precisariam solicitar um API externo (como o que fazes em ", _jsx(_components.code, { children: "getCustomJwtClaims" }), ") sempre que verificarem permissões. Para o fornecedor de serviços que fornece esse API, isso pode aumentar o encargo extra. Com a funcionalidade de JWT personalizada, essas informações podem ser colocadas diretamente no JWT, reduzindo as chamadas frequentes ao API externo."] }), "\n", _jsx(_components.li, { children: "Para os fornecedores de serviços, a funcionalidade de JWT personalizada pode ajudar a verificar as permissões do usuário mais rapidamente, especialmente quando o cliente chama o fornecedor de serviços com frequência, melhorando o desempenho do serviço." }), "\n", _jsx(_components.li, { children: "A funcionalidade de JWT personalizada pode ajudar-te a implementar rapidamente informações adicionais de autorização requeridas pelos negócios, e as informações podem ser passadas entre o cliente e o fornecedor de serviços de maneira segura, uma vez que o JWT é autossuficiente e pode ser encriptado de modo que seja difícil de falsificar." }), "\n"] }), "\n", _jsx(Info, { children: _jsx(_components.p, { children: "É importante notar que, como mencionámos num post anterior, uma vez que um token de acesso JWT é\nemitido, ele não mudará durante o seu período de validade. Portanto, as informações contidas nas\nclaims JWT personalizadas devem ser combinadas com as necessidades reais de negócios e evitar incluir informações\nque são importantes para a 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 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " é executado sempre que um usuário precisa que o Logto emita um token de acesso, é necessário evitar a execução de lógica excessivamente complexa e pedidos de APIs externos com alta largura de banda. Caso contrário, pode levar muito tempo para o usuário final aguardar o resultado de ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " durante o processo de login. Se a tua função ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " retornar um objeto vazio, recomendamos fortemente que apagues temporariamente este item de configuração até que realmente precises de 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 claims JWT extra para permitir que os usuários coloquem informações adicionais do usuário final no token de acesso JWT de acordo com as suas necessidades de negócios, para que, após o usuário fazer login, as permissões do usuário possam ser verificadas rapidamente." }), "\n", _jsx(_components.p, { children: "Fornecemos o cenário do app Assistente de IA do John e demonstramos como usar a funcionalidade de JWT personalizada do Logto para alcançar verificações de autorização mais flexíveis. Também apontamos alguns pontos-chave para o uso de JWT personalizadas. Em combinação com cenários de negócios reais, os usuários podem colocar várias informações relacionadas ao usuário no token de acesso JWT de acordo com as suas necessidades de negócios, para que o fornecedor de serviços possa verificar 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."); }