커스텀 액세스 토큰 스크립트 생성

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

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

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

노트:

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

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를 통해 입력 객체의 속성에 올바르게 접근할 수 있습니다.

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

속성	설명	타입
`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 타입	`string`
`kind`	토큰 종류	`AccessToken`

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

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

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

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

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

속성	설명	타입
`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

우측의 환경 변수 설정 섹션을 사용하여 스크립트에 사용할 환경 변수를 설정할 수 있습니다. 이 변수들은 스크립트 내에서 하드코딩하지 않고 민감한 정보나 설정 데이터를 저장하는 데 사용할 수 있습니다. 예: 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단계: 스크립트 테스트

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

에디터 우측 상단의 테스트 실행을 클릭하면, 모의 데이터로 스크립트를 실행할 수 있습니다. 스크립트의 출력 결과는 테스트 결과 드로어에 표시됩니다.

노트:

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

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

getCustomJwtClaims() 함수 구현하기​

1단계: 스크립트 편집​

2단계: 입력 파라미터​

token​

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

environmentVariables​

api​

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

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