커스텀 토큰 클레임 스크립트 생성하기

액세스 토큰 (Access token)에 커스텀 클레임 (Claim)을 추가하려면, 해당 클레임을 포함하는 객체를 반환하는 스크립트를 제공해야 합니다. 이 스크립트는 커스텀 클레임이 포함된 객체를 반환하는 JavaScript 함수로 작성되어야 합니다.

콘솔 > 커스텀 JWT로 이동하세요.
액세스 토큰에는 두 가지 유형이 있으며, 각각의 액세스 토큰 클레임을 커스터마이즈할 수 있습니다:
- 사용자 액세스 토큰: 최종 사용자에게 발급되는 액세스 토큰입니다. 예: 웹 애플리케이션 또는 모바일 애플리케이션용.
- 기계 간 (Machine-to-Machine) 액세스 토큰: 서비스 또는 애플리케이션에 발급되는 액세스 토큰입니다. 예: 기계 간 애플리케이션용.
액세스 토큰의 유형에 따라 토큰 페이로드 컨텍스트가 다를 수 있습니다. 각 액세스 토큰 유형별로 토큰 클레임을 개별적으로 커스터마이즈할 수 있습니다.

커스터마이즈할 액세스 토큰 유형을 선택한 후, Add custom claims 버튼을 클릭하여 새 스크립트를 생성하세요.

노트:

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

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

`getCustomJwtClaims()` 함수 구현하기

커스텀 JWT 상세 페이지에서 커스텀 토큰 클레임 스크립트를 작성할 수 있는 스크립트 에디터를 찾을 수 있습니다. 이 스크립트는 커스텀 클레임 객체를 반환하는 JavaScript 함수여야 합니다.

1단계: 스크립트 편집하기

좌측의 코드 에디터를 사용하여 스크립트를 수정하세요. 기본적으로 빈 객체를 반환하는 getCustomJwtClaims 함수가 제공됩니다. 이 함수를 수정하여 원하는 커스텀 클레임 객체를 반환할 수 있습니다.

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

이 에디터는 JavaScript 언어 서버를 사용하여 기본적인 구문 강조, 코드 완성, 오류 검사를 제공합니다. 입력 파라미터는 잘 타입 지정되어 있으며 jsDoc 스타일로 문서화되어 있습니다. 에디터의 IntelliSense를 활용하여 입력 객체의 속성에 올바르게 접근할 수 있습니다. 상세한 파라미터 정의는 페이지 우측에서 확인할 수 있습니다.

노트:

이 함수는 모듈로 export됩니다. 함수 이름을 반드시 getCustomJwtClaims로 유지해야 모듈이 올바르게 함수를 export할 수 있습니다.

2단계: 입력 파라미터

getCustomJwtClaims 함수는 객체를 입력 파라미터로 받습니다. 입력 객체에는 다음과 같은 속성이 포함되어 있습니다:

token

토큰 페이로드 객체입니다. 이 객체에는 원본 토큰 클레임과 스크립트에서 접근할 수 있는 메타데이터가 포함되어 있습니다.

토큰 페이로드 객체와 사용자 데이터 객체의 상세 타입 정의는 페이지 우측에서 확인할 수 있습니다. 에디터의 IntelliSense를 통해 입력 객체의 속성에 올바르게 접근할 수 있습니다.

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

Property	Description	Type
`jti`	고유 JWT id	`string`
`aud`	토큰의 대상 (Audience)	`string`
`scope`	토큰의 스코프 (Scope)	`string`
`clientId`	토큰의 클라이언트 id	`string`
`accountId`	토큰의 사용자 id	`string`
`expiresWithSession`	토큰이 세션과 함께 만료되는지 여부	`boolean`
`grantId`	토큰의 현재 인증 (Authentication) grant id	`string`
`gty`	토큰의 grant type	`string`
`kind`	토큰 종류	`AccessToken`

기계 간 액세스 토큰 데이터 객체
Property Description Type
jti 고유 JWT id string
aud 토큰의 대상 (Audience) string
scope 토큰의 스코프 (Scope) string
clientId 토큰의 클라이언트 id string
kind 토큰 종류 ClientCredentials

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

context 객체에는 현재 인가 (Authorization) 과정과 관련된 사용자 데이터 및 grant 데이터가 포함되어 있습니다.

사용자 데이터 객체 사용자 액세스 토큰의 경우, Logto는 커스텀 클레임 설정에 필요한 모든 사용자 프로필 데이터와 조직 멤버십 데이터를 포함한 추가 사용자 데이터 컨텍스트를 제공합니다. 자세한 내용은 사용자 및 조직을 확인하세요.
Grant 데이터 객체 impersonation 토큰 교환으로 부여된 사용자 액세스 토큰의 경우, Logto는 추가 grant 데이터 컨텍스트를 제공합니다. grant 데이터 객체에는 subject 토큰의 커스텀 컨텍스트가 포함되어 있습니다. 자세한 내용은 사용자 가장 (User impersonation)을 확인하세요.

사용자 상호작용 데이터 객체 특정 사용자 액세스 토큰의 경우, 현재 인가 세션에 대한 사용자의 상호작용 세부 정보를 접근해야 할 때가 있습니다. 예를 들어, 사용자가 로그인에 사용한 엔터프라이즈 SSO 아이덴티티를 조회해야 할 수 있습니다. 이 사용자 상호작용 데이터 객체에는 최근 사용자가 제출한 상호작용 데이터가 포함되어 있습니다. 예시:

Property	Description	Type
`interactionEvent`	현재 사용자 상호작용의 이벤트	`SignIn` 또는 `Register`
`userId`	현재 사용자 상호작용의 사용자 id	`string`
`verificationRecords`	상호작용 중 사용자가 아이덴티티를 식별 및 검증하기 위해 제출한 검증 기록 목록	`VerificationRecord[]`

검증 기록 타입 예시:

// VerificationType.Password
{
  id: string;
  type: 'Password';
  identifier: {
    type: 'username' | 'email' | 'phone' | 'userId';
    value: string;
  }
  verified: boolean;
}

// VerificationType.EmailVerificationCode
{
  id: string;
  templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
  verified: boolean;
  type: 'EmailVerificationCode';
  identifier: {
    type: 'email';
    value: string;
  }
}

// VerificationType.PhoneVerificationCode
{
  id: string;
  templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
  verified: boolean;
  type: 'PhoneVerificationCode';
  identifier: {
    type: 'phone';
    value: string;
  }
}

// VerificationType.Social
{
  id: string;
  type: 'Social';
  connectorId: string;
  socialUserInfo?: {
    id: string;
    email?: string | undefined;
    phone?: string | undefined;
    name?: string | undefined;
    avatar?: string | undefined;
    rawData?: Record<string, unknown> | undefined;
  } | undefined;
}

// VerificationType.EnterpriseSso
{
  id: string;
  type: 'EnterpriseSso';
  connectorId: string;
  enterpriseUserInfo?: {
    id: string;
    email?: string | undefined;
    phone?: string | undefined;
    name?: string | undefined;
    avatar?: string | undefined;
    [key: string]?: unknown;
  } | undefined;
  issuer?: string | undefined;
}

// VerificationType.Totp (MFA)
{
  id: string;
  type: 'Totp';
  userId: string;
  verified: boolean;
}

// VerificationType.WebAuthn (MFA)
{
  id: string;
  type: 'WebAuthn';
  userId: string;
  verified: boolean;
}

// VerificationType.BackupCode (MFA)
{
  id: string;
  type: "BackupCode";
  userId: string;
  code?: string | undefined;
}

// VerificationType.OneTimeToken
{
  id: string;
  type: "OneTimeToken";
  verified: boolean;
  identifier: {
    type: "email";
    value: string;
  };
  oneTimeTokenContext?: {
    jitOrganizationIds?: string[] | undefined;
  } | undefined;
}

노트:

사용자 상호작용 데이터 객체에는 여러 개의 검증 기록이 존재할 수 있습니다. 특히 사용자가 여러 번 로그인 또는 회원가입 과정을 거친 경우에 그렇습니다.

예: 사용자가 Social 검증 기록으로 로그인한 후, EmailVerificationCode 검증 기록을 통해 새 이메일 주소를 바인딩하고, Totp 검증 기록으로 MFA 상태를 검증한 경우. 이 경우, 스크립트에서 모든 검증 기록을 적절히 처리해야 할 수 있습니다.

각 검증 기록 타입은 사용자 상호작용 데이터 객체에 한 번만 존재합니다.

environmentVariables

우측의 환경 변수 설정 (Set environment variables) 섹션을 사용하여 스크립트에 사용할 환경 변수를 설정하세요. 이 변수들은 스크립트 내에 하드코딩하고 싶지 않은 민감 정보나 설정 데이터를 저장하는 데 사용할 수 있습니다. 예: API 키, 시크릿, URL 등.

여기서 설정한 모든 환경 변수는 스크립트 내에서 사용할 수 있습니다. 입력 파라미터의 environmentVariables 객체를 통해 접근하세요.

api

api 객체는 토큰 발급 과정에서 추가 접근 제어를 위해 사용할 수 있는 유틸리티 함수 집합을 제공합니다. api 객체에는 다음과 같은 함수가 포함되어 있습니다:

api.denyAccess(message?: string): void

api.denyAccess() 함수는 커스텀 메시지와 함께 토큰 발급 과정을 거부할 수 있게 해줍니다. 이 함수를 사용하여 토큰 발급 과정에서 추가 접근 검증을 강제할 수 있습니다.

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

스크립트 내에서 node 내장 fetch 함수를 사용하여 외부 데이터를 가져올 수 있습니다. fetch 함수는 외부 API에 HTTP 요청을 보낼 수 있는 promise 기반 함수입니다.

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가 충분히 신뢰할 수 있고 빠른지 반드시 확인하세요.

추가로:

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

4단계: 스크립트 테스트하기

스크립트를 저장하기 전에 반드시 테스트하세요. 페이지 우측의 Test context 탭을 클릭하여 테스트용 모의 토큰 페이로드와 사용자 데이터 컨텍스트를 수정할 수 있습니다.

에디터 우측 상단의 Run test를 클릭하여 모의 데이터로 스크립트를 실행하세요. 스크립트의 출력 결과는 Test Result 드로어에 표시됩니다.

노트:

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

Create 버튼을 클릭하여 스크립트를 저장하세요. 커스텀 토큰 클레임 스크립트가 저장되어 액세스 토큰 발급 과정에 적용됩니다.

getCustomJwtClaims() 함수 구현하기​

1단계: 스크립트 편집하기​

2단계: 입력 파라미터​

token​

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

environmentVariables​

api​

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

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