"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "logto-의-사용자-지정-jwt-클레임은-어떻게-작동합니까", "hProperties": { "id": "logto-의-사용자-지정-jwt-클레임은-어떻게-작동합니까" } }, "depth": 2, "value": "Logto 의 사용자 지정 JWT 클레임은 어떻게 작동합니까?" }, { "data": { "id": "사용자-지정-jwt-클레임으로-권한-강화하기-실제-예제", "hProperties": { "id": "사용자-지정-jwt-클레임으로-권한-강화하기-실제-예제" } }, "depth": 2, "value": "사용자 지정 JWT 클레임으로 권한 강화하기: 실제 예제" }, { "data": { "id": "시나리오-설정", "hProperties": { "id": "시나리오-설정" } }, "depth": 3, "value": "시나리오 설정" }, { "data": { "id": "logto-설정", "hProperties": { "id": "logto-설정" } }, "depth": 3, "value": "Logto 설정" }, { "data": { "id": "사용자-지정-jwt-기능이-발동되는지-확인하기", "hProperties": { "id": "사용자-지정-jwt-기능이-발동되는지-확인하기" } }, "depth": 3, "value": "사용자 지정 JWT 기능이 발동되는지 확인하기" }, { "data": { "id": "서비스-제공자-권한-부여-로직-업데이트", "hProperties": { "id": "서비스-제공자-권한-부여-로직-업데이트" } }, "depth": 3, "value": "서비스 제공자 권한 부여 로직 업데이트" }, { "data": { "id": "왜-사용자-지정-jwt-클레임을-사용해야-합니까", "hProperties": { "id": "왜-사용자-지정-jwt-클레임을-사용해야-합니까" } }, "depth": 3, "value": "왜 사용자 지정 JWT 클레임을 사용해야 합니까?" }, { "data": { "id": "결론", "hProperties": { "id": "결론" } }, "depth": 2, "value": "결론" }]; const readingTime = { "minutes": 3, "words": 814, "text": "3 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: "이전 기사에서, 점점 더 많은 시스템이 사용자 인증 및 액세스 제어를 위해 JWT 형식의 액세스 토큰을 사용하고 있다고 언급한 바 있습니다. 그 중요한 이유 중 하나는 JWT 가 사용자 역할 및 권한과 같은 유용한 정보를 포함할 수 있기 때문입니다. 이러한 정보는 서버와 클라이언트 간에 사용자 신원 정보를 전달하는 데 도움을 주어 사용자 인증 및 액세스 제어를 구현할 수 있습니다." }), "\n", _jsxs(_components.p, { children: ["보통 JWT 에 포함된 정보는 인증 서버에 의해 결정됩니다. OAuth 2.0 프로토콜에 따르면, JWT 는 일반적으로 ", _jsx(_components.code, { children: "sub" }), "(주체), ", _jsx(_components.code, { children: "aud" }), "(청중), ", _jsx(_components.code, { children: "exp" }), "(만료 시간)과 같은 필드를 포함하는데, 이러한 필드들을 클레임이라고 합니다. 이러한 클레임은 액세스 토큰의 유효성을 확인하는 데 도움을 줄 수 있습니다."] }), "\n", _jsx(_components.p, { children: "그러나 JWT 가 확인에 사용되는 시나리오는 무수히 많으며, 일반적인 JWT 클레임이 종종 사용자 요구를 충족시키지 못할 수 있습니다. 사람들은 종종 JWT 가 정보를 포함할 수 있다면, 권한 부여를 더 쉽게 하기 위해 일부 정보를 추가할 수 있을까 생각합니다." }), "\n", _jsx(_components.p, { children: "답은 YES 입니다. 우리는 JWT 에 커스텀 클레임을 추가할 수 있으며, 예를 들어 현재 사용자의 범위(scope)와 구독 레벨을 포함할 수 있습니다. 이렇게 하면 클라이언트와 서버 간(여기서 서버는 다양한 서비스를 제공하는 서버, 즉 서비스 제공자를 의미합니다) 사용자 신원 정보를 전달하여 사용자 인증 및 액세스 제어를 달성할 수 있습니다." }), "\n", _jsxs(_components.p, { children: ["표준 JWT 클레임에 대한 자세한 내용은 ", _jsx(_components.a, { href: "https://datatracker.ietf.org/doc/html/rfc7519", children: "RFC7519" }), " 를 참조하십시오. Logto 는 인증과 권한 부여를 모두 지원하는 아이덴티티 솔루션으로서, 표준 ", _jsx(_components.a, { href: "https://docs.logto.io/docs/recipes/rbac/", children: "RBAC" }), " 을 지원하기 위해 리소스 및 범위 클레임을 확장하였습니다. 비록 Logto 의 RBAC 구현이 표준적일지라도, 모든 사용 사례에 적합할 만큼 간단하거나 유연하지는 않습니다."] }), "\n", _jsx(_components.p, { children: "이를 바탕으로 Logto 는 JWT 클레임을 사용자 지정할 수 있는 새로운 기능을 출시하여, 사용자 인증 및 액세스 제어를 더욱 유연하게 구현할 수 있도록 하였습니다." }), "\n", _jsx(LogtoCloudButton, {}), "\n", _jsxs(_components.h2, { id: "logto-의-사용자-지정-jwt-클레임은-어떻게-작동합니까", children: ["Logto 의 사용자 지정 JWT 클레임은 어떻게 작동합니까?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#logto-의-사용자-지정-jwt-클레임은-어떻게-작동합니까", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "사이드바에서 \"JWT claims\" 버튼을 클릭하면 사용자 지정 JWT 목록 페이지로 이동할 수 있습니다." }), "\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: "최종 사용자에 대한 사용자 지정 클레임 추가부터 시작하겠습니다." }), "\n", _jsxs(_components.p, { children: ["왼쪽의 편집기에서 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 함수를 사용자 지정할 수 있습니다. 이 메서드는 ", _jsx(_components.code, { children: "token" }), ", ", _jsx(_components.code, { children: "data" }), ", ", _jsx(_components.code, { children: "envVariables" }), " 세 가지 입력 매개변수를 가집니다."] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "token" }), " 은 현재 최종 사용자의 자격 증명과 시스템 설정을 기반으로 얻은 원시 액세스 토큰 페이로드이며, Logto 에서 사용자 액세스 관련 정보를 포함합니다."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "data" }), " 는 Logto 에서의 사용자에 대한 모든 정보로, 모든 사용자 역할, 소셜 로그인 ID, SSO ID, 조직 멤버십 등을 포함합니다."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "envVariables" }), " 는 Logto 에서 현재 최종 사용자 액세스 토큰 사용 시나리오를 위해 구성한 환경 변수로, 필요한 외부 API 의 API 키(API key) 등을 의미합니다."] }), "\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: "오른쪽의 카드들은 해당 매개변수의 소개를 보여주기 위해 확장할 수 있으며, 여기서 현재 시나리오에 대한 환경 변수를 설정할 수도 있습니다." }), "\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: "오른쪽 카드의 소개를 모두 읽은 후 테스트 모드로 전환하여, 테스트 데이터를 편집하고 왼쪽 코드 편집기에서 작성한 스크립트의 동작이 예상에 부합하는지 확인할 수 있습니다." }), "\n", _jsxs(_components.p, { children: ["이것은 최종 사용자가 Logto 에 인증 요청을 하고 Logto 에서 반환한 JWT 형식의 액세스 토큰을 결국 획득할 때 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 함수의 실행 과정을 보여주는 시퀀스 다이어그램입니다."] }), "\n", _jsxs(_components.p, { children: ["Custom JWT 기능이 활성화되지 않은 경우, 그림의 3단계는 건너뛰고 2단계가 종료되는 즉시 4단계가 실행됩니다. 이 시점에서 Logto 는 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 의 반환 값을 빈 객체로 간주하고, 이후 단계를 계속 진행합니다."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant U as User or user agent\n participant IdP as Logto (identity provider)\n participant SP as Service Provider\n\n autonumber\n U ->> IdP: Auth request (with credentials)\n activate IdP\n IdP-->>IdP: Validate credentials &
generate raw access token payload\n rect rgb(191, 223, 255)\n note over IdP: Custom JWT\n IdP->>IdP: Run custom JWT claims script (`getCustomJwtClaims`) &
get extra JWT claims\n end\n IdP-->>IdP: Merge raw access token payload and extra JWT claims\n IdP-->>IdP: Sign & encrypt payload to get JWT access token\n deactivate IdP\n IdP-->>U: Issue JWT-format access token\n par Get service via API\n U->>SP: service request (with JWT access token)\n SP-->>U: service response\n end\n" }) }), "\n", _jsx(Note, { children: _jsxs(_components.p, { children: ["보안상의 이유로, Logto 의 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 함수에서 반환된 JWT 클레임이 이미 액세스 토큰 페이로드에 존재하는 경우, 이러한 클레임은 적용되지 않으며 기존 클레임을 덮어쓸 수 없습니다."] }) }), "\n", _jsxs(_components.h2, { id: "사용자-지정-jwt-클레임으로-권한-강화하기-실제-예제", children: ["사용자 지정 JWT 클레임으로 권한 강화하기: 실제 예제", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#사용자-지정-jwt-클레임으로-권한-강화하기-실제-예제", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "이전 섹션에서는 Logto 커스텀 JWT 의 작동 원리를 소개했습니다. 이번 부분에서는 Logto 커스텀 JWT 클레임을 사용하여 권한 부여의 유연성을 향상시키고 서비스 제공자의 성능을 개선하는 방법을 실제 예제를 통해 제공합니다." }), "\n", _jsxs(_components.h3, { id: "시나리오-설정", children: ["시나리오 설정", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#시나리오-설정", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "John 의 팀은 사용자가 AI 로봇과 대화하여 다양한 서비스를 제공받을 수 있는 AI Assistant App 을 개발했습니다." }), "\n", _jsx(_components.p, { children: "AI 로봇 서비스는 무료 서비스와 유료 서비스로 나뉘어집니다. 무료 서비스에는 특별 항공권 추천이 포함되며, 유료 서비스에는 주식 예측이 포함됩니다." }), "\n", _jsx(_components.p, { children: "AI Assistant App 은 Logto 를 사용하여 모든 사용자를 관리하며, 사용자는 무료 사용자, 선불 사용자, 프리미엄 사용자로 나뉩니다. 무료 사용자는 무료 서비스만 사용할 수 있고, 선불 사용자는 모든 서비스를 사용할 수 있으며(사용량에 따라 요금 부과), 프리미엄 사용자는 모든 서비스를 사용할 수 있습니다(악의적인 사용을 방지하기 위한 속도 제한이 있음)." }), "\n", _jsx(_components.p, { children: "또한, AI Assistant App 은 Stripe 를 사용하여 사용자 결제를 관리하고, 자체 로그 서비스를 사용하여 사용자 운영 로그를 기록합니다." }), "\n", _jsxs(_components.h3, { id: "logto-설정", children: ["Logto 설정", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#logto-설정", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["먼저 AI Assistant App 서비스에 대한 API 리소스를 생성하고 ", _jsx(_components.code, { children: "recommend:flight" }), " 및 ", _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: ["그런 다음 두 개의 ", _jsx(_components.code, { children: "roles" }), " , ", _jsx(_components.code, { children: "free-user" }), " 및 ", _jsx(_components.code, { children: "paid-user" }), " 를 생성하고 해당 범위를 할당합니다:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "recommend:flight" }), " 범위를 ", _jsx(_components.code, { children: "free-user" }), " 역할에 할당합니다."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "recommend:flight" }), " 및 ", _jsx(_components.code, { children: "predict:stock" }), " 범위를 모두 ", _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: ["마지막으로 ", _jsx(_components.code, { children: "free-user" }), " , ", _jsx(_components.code, { children: "prepaid-user" }), " , ", _jsx(_components.code, { children: "premium-user" }), " 세 명의 사용자를 생성하고 해당 역할을 할당합니다:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "free-user" }), " 역할을 ", _jsx(_components.code, { children: "free-user" }), " 사용자의 역할로 할당합니다."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "paid-user" }), " 역할을 ", _jsx(_components.code, { children: "prepaid-user" }), " 및 ", _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: ["아래 그림에 표시된 것처럼, 위의 시나리오에 필요한 권한 정보를 구현하기 위해 현재 로그인한 사용자의 ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), ", 및 ", _jsx(_components.code, { children: "numOfCallsToday" }), " 정보를 JWT 에 포함시키고자 합니다. AI Assistant App 에서 액세스 토큰을 확인할 때 이러한 정보를 사용하여 빠르게 권한 검증을 수행할 수 있습니다."] }), "\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: [_jsx(_components.code, { children: "envVariables" }), " 를 설정한 후, ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 함수를 구현하고 \"Run test\" 버튼을 클릭하여 현재 테스트 데이터를 기반으로 추가 JWT 클레임의 결과를 확인하세요."] }), "\n", _jsxs(_components.p, { children: ["우리가 ", _jsx(_components.code, { children: "data.user.roles" }), " 에 대한 테스트 데이터를 구성하지 않았기 때문에, 결과에 나타난 ", _jsx(_components.code, { children: "roles" }), " 는 빈 배열입니다."] }), "\n", _jsxs(_components.h3, { id: "사용자-지정-jwt-기능이-발동되는지-확인하기", children: ["사용자 지정 JWT 기능이 발동되는지 확인하기", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#사용자-지정-jwt-기능이-발동되는지-확인하기", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["앞서 설명한 Logto 설정에 따라 테스트에서 해당 결과를 얻었습니다. 다음으로, Logto 에서 제공하는 샘플 앱을 사용하여 우리의 사용자 지정 JWT 가 효과적인지 확인하겠습니다. ", _jsx(_components.a, { href: "https://docs.logto.io/sdk/", children: "Logto SDKs" }), " 에서 익숙한 SDK 를 찾아 문서와 해당 GitHub 저장소에 따라 샘플 앱을 배포합니다."] }), "\n", _jsxs(_components.p, { children: ["여기서 설명한 설정에 따라, ", _jsx(_components.a, { href: "https://docs.logto.io/sdk/react/", children: "React SDK" }), " 를 예로 들어 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: ["사용자 ", _jsx(_components.code, { children: "free_user" }), " 로 로그인하여 AI Assistant App 을 시뮬레이션하는 샘플 앱을 통해 JWT 액세스 토큰의 페이로드 부분을 보면 우리가 추가한 ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), ", ", _jsx(_components.code, { children: "numOfCallsToday" }), ", ", _jsx(_components.code, { children: "isPaidUser" }), " 및 ", _jsx(_components.code, { children: "isPremiumUser" }), " 정보를 확인할 수 있습니다."] }), "\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: [_jsx(_components.code, { children: "balance" }), ", ", _jsx(_components.code, { children: "numOfCallsToday" }), ", ", _jsx(_components.code, { children: "isPaidUser" }), " 및 ", _jsx(_components.code, { children: "isPremiumUser" }), " 의 값은 이전 테스트와 일치하며, ", _jsx(_components.code, { children: "roles" }), " 는 ", _jsx(_components.code, { children: "[\"free-user\"]" }), " 입니다. 이는 실제 최종 사용자 로그인 과정에서 사용자가 접근할 수 있는 모든 데이터를 가져와 적절히 처리하기 때문입니다."] }), "\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: ["프리미엄 사용자의 경우, ", _jsx(_components.code, { children: "roles" }), " 가 ", _jsx(_components.code, { children: "[\"paid-user\"]" }), " 이며 ", _jsx(_components.code, { children: "isPaidUser" }), " 와 ", _jsx(_components.code, { children: "isPremiumUser" }), " 모두 ", _jsx(_components.code, { children: "true" }), " 임을 확인할 수 있습니다."] }), "\n", _jsxs(_components.h3, { id: "서비스-제공자-권한-부여-로직-업데이트", children: ["서비스 제공자 권한 부여 로직 업데이트", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#서비스-제공자-권한-부여-로직-업데이트", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "앞의 단계에서 비즈니스 요구 사항에 기반한 사용자 지정 클레임을 사용자 액세스 토큰에 추가했습니다. 다음으로, 이 클레임을 사용하여 빠르게 권한 검증을 수행할 수 있습니다." }), "\n", _jsxs(Note, { children: [_jsx(_components.p, { children: "맞춤형 클레임에만 의존하여 권한 검증을 수행하는 것은 권장하지 않습니다." }), _jsx(_components.p, { children: "RBAC(Role-Based Access Control) 의 구현이 최소 권한 원칙을 따르기 때문에, 보안을 보장하기 위해 사용자 지정 클레임을 사용한 검증은 RBAC 를 기반으로 한 보조 검증이어야 합니다. 이는 추가적인 사용자 승인 클레임 도입으로 인해 사용자 권한 권한 범위가 확대되는 것을 방지하기 위함입니다." })] }), "\n", _jsxs(_components.p, { children: ["다음은 Logto 가 API 측에서 JWT 액세스 토큰을 검증하는 로직입니다. 전체 코드 구현은 ", _jsx(_components.a, { href: "https://github.com/logto-io/logto/blob/master/packages/core/src/middleware/koa-auth/index.ts", children: "GitHub repo" }), " 에서 찾을 수 있습니다:"] }), "\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 // 공개 JWK 와 발급자를 가져옵니다.\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: ["Logto API 의 액세스 토큰 검증 로직을 참고하고, 자체 비즈니스 로직에 맞게 커스터마이즈할 수 있습니다. 예를 들어, 여기서 설명한 AI Assistant App 시나리오의 경우 ", _jsx(_components.code, { children: "verifyBearerTokenFromRequest" }), " 함수에 ", _jsx(_components.code, { children: "roles" }), ", ", _jsx(_components.code, { children: "balance" }), ", ", _jsx(_components.code, { children: "numOfCallsToday" }), ", ", _jsx(_components.code, { children: "isPaidUser" }), " 및 ", _jsx(_components.code, { children: "isPremiumUser" }), " 와 같은 사용자 지정 클레임에 대한 검증 로직을 추가할 수 있습니다."] }), "\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 // 공개 JWK 와 발급자를 가져옵니다.\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 // RBAC 검증.\n /**\n * `free-user` 는 `predict:stock` 범위를 가지지 않으므로, 만약 API 에 `predict:stock`\n * 범위가 필요하다면 요청은 직접 거부됩니다.\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 /** \n * `payload` 내의 추가 클레임에 대한 검증.\n */\n assertThat(\n roles.includes('paid-user') && isPaidUser,\n new RequestError({ code: 'auth.role_mismatch', status: 403 }));\n // 일일 호출 제한이 100이라 가정합니다.\n assertThat(\n numOfCallsToday < 100,\n new RequestError({ code: 'auth.rate_limit_exceeded', status: 403 }));\n // 프리미엄 사용자의 `balance` 는 확인할 필요가 없습니다.\n if (isPremiumUser) {\n return;\n }\n // 잔액이 양수일 경우에만 서비스에 액세스할 수 있습니다.\n assertThat(\n balance > 0,\n new RequestError({ code: 'auth.balance_insufficient', status: 403 }));\n /** \n * `payload` 내의 추가 클레임에 대한 검증.\n */\n};\n" }) }), "\n", _jsx(_components.p, { children: "위의 예제는 최종 사용자의 로그인 및 JWT 액세스 토큰 획득에 영향을 미치는 시나리오에 대한 것입니다. 만약 당신의 사용 사례가 머신 간(M2M) 이라면, M2M 앱에 대해 별도의 사용자 지정 JWT 클레임을 구성할 수도 있습니다." }), "\n", _jsx(_components.p, { children: "사용자를 위한 사용자 지정 JWT 를 구성한다고 해서 M2M 앱이 액세스 토큰을 획득할 때의 결과에 영향을 미치지 않으며, 그 반대의 경우도 마찬가지입니다." }), "\n", _jsxs(_components.p, { children: ["M2M 연결의 일반성 때문에, Logto 는 현재 M2M 앱의 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 메서드가 Logto 의 내부 데이터를 수락하는 기능을 제공하지 않습니다. 이 외에, M2M 앱에 대한 사용자 지정 JWT 설정 방법은 사용자 앱과 동일합니다. 이 기사는 이에 대해 자세히 설명하지 않으며, Logto 의 사용자 지정 JWT 기능을 사용하여 시작할 수 있습니다."] }), "\n", _jsxs(_components.h3, { id: "왜-사용자-지정-jwt-클레임을-사용해야-합니까", children: ["왜 사용자 지정 JWT 클레임을 사용해야 합니까?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#왜-사용자-지정-jwt-클레임을-사용해야-합니까", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "우리는 John 의 AI Assistant App 시나리오와 Logto 의 사용자 지정 JWT 기능을 사용하여 더 유연한 권한 검증을 달성하는 방법을 제공했습니다. 이 과정에서 사용자 지정 JWT 기능의 장점을 볼 수 있었습니다:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["사용자 지정 JWT 기능 없이 사용자는 매번 권한을 확인할 때 외부 API (예: ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 에서 수행하는 작업) 를 요청해야 합니다. 이 API 를 제공하는 서비스 제공자에게는 이로 인해 추가적인 부담이 증가할 수 있습니다. 사용자 지정 JWT 기능을 사용하면 이러한 정보를 직접 JWT 에 넣을 수 있어 외부 API 의 자주 호출을 줄일 수 있습니다."] }), "\n", _jsx(_components.li, { children: "서비스 제공자 측에서는 사용자 지정 JWT 기능이 사용자 권한을 더 빠르게 검증하는 데 도움이 될 수 있으며, 특히 클라이언트가 서비스 제공자를 자주 호출할 때 서비스 성능을 향상시킬 수 있습니다." }), "\n", _jsx(_components.li, { children: "사용자 지정 JWT 기능은 비즈니스에 필요한 추가 권한 정보를 빠르게 구현할 수 있으며, JWT 는 자체적으로 포함된 정보를 통해 클라이언트와 서비스 제공자 간에 정보를 안전하게 전달할 수 있기 때문에 위조하기 어렵습니다." }), "\n"] }), "\n", _jsx(Info, { children: _jsx(_components.p, { children: "이전 블로그 게시물에서 언급한 바와 같이, JWT 액세스 토큰이 발급되면 유효 기간 동안 변하지 않음을\n유념하는 것이 중요합니다. 따라서 사용자 지정 JWT 클레임에 포함된 정보는 실제 비즈니스 요구 사항과\n결합하여 액세스 토큰의 유효 기간 동안 크게 변경되는 중요한 권한 정보는 포함하지 않도록 해야 합니다." }) }), "\n", _jsxs(_components.p, { children: ["동시에, ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 은 사용자가 Logto 에서 액세스 토큰을 발급 받을 때마다 실행되므로, 지나치게 복잡한 로직이나 고대역폭이 필요한 외부 API 요청 실행을 피해야 합니다. 그렇지 않으면, 사용자 로그인을 기다리는 동안 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 의 결과를 기다리는 시간이 길어질 수 있습니다. 만약 ", _jsx(_components.code, { children: "getCustomJwtClaims" }), " 이 빈 객체를 반환한다면, 실제로 사용해야 할 때까지 이 설정 항목을 일시적으로 삭제할 것을 강력히 권장합니다."] }), "\n", _jsxs(_components.h2, { id: "결론", children: ["결론", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#결론", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "이 기사에서, Logto 는 기본 JWT 액세스 토큰을 확장하고 추가 JWT 클레임 기능을 확장하여 사용자가 비즈니스 요구 사항에 따라 추가적인 최종 사용자 정보를 JWT 액세스 토큰에 넣을 수 있도록 하였습니다. 이를 통해 사용자가 로그인한 후, 사용자의 권한을 빠르게 검증할 수 있습니다." }), "\n", _jsx(_components.p, { children: "우리는 John 의 AI Assistant App 시나리오를 제공하고, Logto 의 사용자 지정 JWT 기능을 사용하여 더 유연한 권한 검증을 달성하는 방법을 시연하였습니다. 또한 사용자 지정 JWT 를 사용할 때의 몇 가지 주요 포인트를 지적하였습니다. 실제 비즈니스 시나리오와 결합하여, 사용자는 비즈니스 요구 사항에 따라 다양한 사용자 관련 정보를 JWT 액세스 토큰에 넣어 서비스 제공자가 사용자의 권한을 빠르게 확인할 수 있도록 할 수 있습니다." }), "\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."); }