사용자 정의 토큰 클레임 스크립트 생성

액세스 토큰에 사용자 정의 클레임 추가를 위해, 해당 클레임을 포함하는 객체를 반환하는 스크립트를 제공해야 합니다. 스크립트는 사용자 정의 클레임이 포함된 객체를 반환하는 JavaScript 함수로 작성되어야 합니다.

콘솔 > 사용자 정의 JWT로 이동합니다.
액세스 토큰 클레임을 사용자 정의할 수 있는 두 가지 유형의 액세스 토큰이 있습니다:
- 사용자 액세스 토큰: 최종 사용자에게 발급된 액세스 토큰입니다. 예를 들어, 웹 애플리케이션이나 모바일 애플리케이션에 사용됩니다.
- 기계 간 액세스 토큰: 서비스나 애플리케이션에 발급된 액세스 토큰입니다. 예를 들어, 기계 간 애플리케이션에 사용됩니다.
다양한 유형의 액세스 토큰은 서로 다른 토큰 페이로드 컨텍스트를 가질 수 있습니다. 각 유형의 액세스 토큰에 대해 토큰 클레임을 별도로 사용자 정의할 수 있습니다.

사용자 정의할 액세스 토큰 유형을 선택하고 사용자 정의 클레임 추가 버튼을 클릭하여 새 스크립트를 생성하세요.

노트:

사용자 정의 토큰 클레임 기능은 다음 사용자에게만 제공됩니다:

Logto OSS 사용자
개발 환경이 있는 Logto Cloud 테넌트
프로덕션 환경이 있는 Logto Cloud 유료 테넌트 ( Pro 테넌트 및 엔터프라이즈 테넌트 포함)

`getCustomJwtClaims()` 함수 구현

사용자 정의 JWT 세부 정보 페이지에서 사용자 정의 토큰 클레임 스크립트를 작성할 수 있는 스크립트 편집기를 찾을 수 있습니다. 스크립트는 사용자 정의 클레임 객체를 반환하는 JavaScript 함수여야 합니다.

1단계: 스크립트 편집

왼쪽의 코드 편집기를 사용하여 스크립트를 수정하세요. 빈 객체 반환 값을 가진 기본 getCustomJwtClaims가 제공되어 시작할 수 있습니다. 이 함수를 수정하여 사용자 정의 클레임 객체를 반환하도록 할 수 있습니다.

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

이 편집기는 JavaScript 언어 서버를 사용하여 기본 구문 강조, 코드 완성 및 오류 검사를 제공합니다. 입력 매개변수는 잘 정의되어 있으며 jsDoc 스타일로 문서화되어 있습니다. 편집기의 IntelliSense를 사용하여 입력 객체의 속성을 올바르게 액세스할 수 있습니다. 페이지 오른쪽에서 자세한 매개변수 정의를 찾을 수 있습니다.

노트:

이 함수는 모듈로 내보내질 것입니다. 모듈이 함수를 올바르게 내보낼 수 있도록 함수 이름을 getCustomJwtClaims로 유지하세요.

2단계: 입력 매개변수

getCustomJwtClaims 함수는 객체를 입력 매개변수로 받습니다. 입력 객체는 다음 속성을 포함합니다:

token

토큰 페이로드 객체입니다. 이 객체는 스크립트에서 액세스해야 할 원래 토큰 클레임과 메타데이터를 포함합니다.

토큰 페이로드 객체와 사용자 데이터 객체의 자세한 유형 정의는 페이지 오른쪽에서 찾을 수 있습니다. 편집기의 IntelliSense는 입력 객체의 이러한 속성을 올바르게 액세스하는 데 도움을 줍니다.

사용자 액세스 토큰 데이터 객체

속성	설명	유형
`jti`	고유한 JWT ID	`string`
`aud`	토큰의 대상	`string`
`scope`	토큰의 스코프	`string`
`clientId`	토큰의 클라이언트 ID	`string`
`accountId`	토큰의 사용자 ID	`string`
`expiresWithSession`	토큰이 세션과 함께 만료되는지 여부	`boolean`
`grantId`	토큰의 현재 인증 부여 ID	`string`
`gty`	토큰의 부여 유형	`string`
`kind`	토큰 종류	`AccessToken`

기계 간 액세스 토큰 데이터 객체
속성 설명 유형
jti 고유한 JWT ID string
aud 토큰의 대상 string
scope 토큰의 스코프 string
clientId 토큰의 클라이언트 ID string
kind 토큰 종류 ClientCredentials

context (사용자 액세스 토큰에만 사용 가능)

컨텍스트 객체는 현재 인가 (Authorization) 과정과 관련된 사용자 데이터와 부여 데이터를 포함합니다.

사용자 데이터 객체 사용자 액세스 토큰의 경우, Logto는 사용자 정의 클레임을 설정하는 데 필요한 모든 사용자 프로필 데이터와 조직 멤버십 데이터를 포함하는 추가 사용자 데이터 컨텍스트를 제공합니다. 자세한 내용은 사용자 및 조직을 확인하세요.
부여 데이터 객체 사용자 가장 토큰 교환에 의해 부여된 사용자 액세스 토큰의 경우, Logto는 액세스할 수 있는 추가 부여 데이터 컨텍스트를 제공합니다. 부여 데이터 객체는 주체 토큰의 사용자 정의 컨텍스트를 포함합니다. 자세한 내용은 사용자 가장을 확인하세요.

environmentVariables

오른쪽의 환경 변수 설정 섹션을 사용하여 스크립트의 환경 변수를 설정하세요. 이 변수들을 사용하여 스크립트에 하드코딩하고 싶지 않은 민감한 정보나 구성 데이터를 저장할 수 있습니다. 예를 들어, API 키, 비밀, 또는 URL.

여기서 설정한 모든 환경 변수는 스크립트에서 사용할 수 있습니다. 입력 매개변수의 environmentVariables 객체를 사용하여 이러한 변수를 액세스하세요.

api

api 객체는 토큰 발급 과정에 대한 추가 접근 제어를 위해 스크립트에서 사용할 수 있는 유틸리티 함수 세트를 제공합니다. api 객체는 다음과 같은 함수를 포함합니다:

api.denyAccess(message?: string): void

api.denyAccess() 함수는 사용자 정의 메시지로 토큰 발급 과정을 거부할 수 있게 해줍니다. 이 함수를 사용하여 토큰 발급 과정에 대한 추가 접근 검증을 강제할 수 있습니다.

3단계: 외부 데이터 가져오기

스크립트에서 외부 데이터를 가져오기 위해 노드 내장 fetch 함수를 사용할 수 있습니다. fetch 함수는 외부 API에 HTTP 요청을 할 수 있는 프로미스 기반 함수입니다.

const getCustomJwtClaims = async ({ environmentVariables }) => {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${environmentVariables.API_KEY}`,
    },
  });

  const data = await response.json();

  return {
    data,
  };
};

노트:

외부 데이터를 가져오는 것은 토큰 발급 과정에 지연을 초래할 수 있습니다. 외부 API가 신뢰할 수 있고 요구 사항을 충족할 만큼 빠른지 확인하세요.

또한:

스크립트에서 오류와 타임아웃을 적절히 처리하여 토큰 발급 과정이 차단되지 않도록 하세요.
외부 API를 무단 접근으로부터 보호하기 위해 적절한 인증 헤더를 사용하세요.

4단계: 스크립트 테스트

스크립트를 저장하기 전에 테스트하세요. 페이지 오른쪽의 테스트 컨텍스트 탭을 클릭하여 테스트를 위한 모의 토큰 페이로드와 사용자 데이터 컨텍스트를 수정하세요.

편집기의 오른쪽 상단 모서리에 있는 테스트 실행을 클릭하여 모의 데이터로 스크립트를 실행하세요. 스크립트의 출력은 테스트 결과 서랍에 표시됩니다.

노트:

테스트 결과는 모의 데이터로 getCustomJwtClaims 함수의 출력입니다 ( 시퀀스 다이어그램에서 3단계를 완료한 후 얻은 "추가 토큰 클레임"). 스크립트가 토큰 발급 과정에서 실행될 때 실제 토큰 페이로드와 사용자 데이터 컨텍스트는 다를 것입니다.

생성 버튼을 클릭하여 스크립트를 저장하세요. 사용자 정의 토큰 클레임 스크립트는 저장되어 액세스 토큰 발급 과정에 적용됩니다.

getCustomJwtClaims() 함수 구현​

1단계: 스크립트 편집​

2단계: 입력 매개변수​

token​

context (사용자 액세스 토큰에만 사용 가능)​

environmentVariables​

api​

3단계: 외부 데이터 가져오기​

4단계: 스크립트 테스트​