본문으로 건너뛰기

개인 액세스 토큰 (Personal access token)

개인 액세스 토큰 (PAT, Personal access token)은 사용자가 자신의 자격 증명과 상호작용 로그인 없이 액세스 토큰 (Access token)을 안전하게 부여할 수 있는 방법을 제공합니다. 이는 CI/CD, 스크립트, 또는 리소스에 프로그래밍 방식으로 접근해야 하는 애플리케이션에 유용합니다.

개인 액세스 토큰 관리하기​

콘솔 사용하기​

콘솔 > 사용자 관리의 사용자 상세 페이지에서 개인 액세스 토큰을 관리할 수 있습니다. "인증 (Authentication)" 카드에서 개인 액세스 토큰 목록을 확인하고 새로 생성할 수 있습니다.

Management API 사용하기​

Management API를 설정한 후, API 엔드포인트를 사용하여 개인 액세스 토큰을 생성, 조회, 삭제할 수 있습니다.

PAT로 액세스 토큰 부여하기​

PAT를 생성한 후, 토큰 교환 엔드포인트를 사용하여 애플리케이션에 액세스 토큰을 부여할 수 있습니다.

토큰 플로우 동등성:

PAT를 사용해 획득한 액세스 토큰은 표준 리프레시 토큰 (Refresh token) 플로우로 획득한 토큰과 동일하게 동작합니다. 즉:

  • 조직 컨텍스트: PAT로 획득한 토큰은 리프레시 토큰 플로우와 동일한 조직 권한 및 스코프를 지원합니다.
  • 인가 플로우: PAT로 교환한 액세스 토큰을 조직 권한 및 조직 수준 API 리소스에 사용할 수 있습니다.
  • 토큰 검증: 동일한 검증 로직이 적용되며, 초기 grant type만 다릅니다.

조직과 함께 작업할 때, PAT 또는 리프레시 토큰을 사용하더라도 접근 패턴과 권한은 동일합니다.

요청​

애플리케이션은 HTTP POST 메서드를 사용하여 테넌트의 토큰 엔드포인트에 특수한 grant type으로 토큰 교환 요청을 보냅니다. 다음 파라미터들은 application/x-www-form-urlencoded 형식으로 HTTP 요청 엔티티 본문에 포함됩니다.

  1. client_id: 필수. 애플리케이션의 클라이언트 ID.
  2. grant_type: 필수. 이 파라미터의 값은 urn:ietf:params:oauth:grant-type:token-exchange이어야 하며, 토큰 교환이 수행됨을 나타냅니다.
  3. resource: 선택. 리소스 지표 (Resource indicator), 다른 토큰 요청과 동일합니다.
  4. scope: 선택. 요청된 스코프 (Scope), 다른 토큰 요청과 동일합니다.
  5. subject_token: 필수. 사용자의 PAT.
  6. subject_token_type: 필수. subject_token 파라미터에 제공된 보안 토큰의 타입. 이 파라미터의 값은 urn:logto:token-type:personal_access_token이어야 합니다.

응답​

토큰 교환 요청이 성공하면, 테넌트의 토큰 엔드포인트는 사용자의 아이덴티티를 나타내는 액세스 토큰을 반환합니다. 응답은 application/json 형식의 HTTP 응답 엔티티 본문에 다음 파라미터를 포함합니다.

  1. access_token: 필수. 사용자의 액세스 토큰으로, authorization_code 또는 refresh_token과 같은 다른 토큰 요청과 동일합니다.
  2. issued_token_type: 필수. 발급된 토큰의 타입. 이 파라미터의 값은 urn:ietf:params:oauth:token-type:access_token이어야 합니다.
  3. token_type: 필수. 토큰의 타입. 이 파라미터의 값은 Bearer이어야 합니다.
  4. expires_in: 필수. 액세스 토큰의 유효 기간(초 단위).
  5. scope: 선택. 액세스 토큰의 스코프.

토큰 교환 예시​

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client-id:client-secret)>

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&scope=profile
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile"
}

예시 액세스 토큰 페이로드:

{
  "jti": "iFtbZBeh2M1cTTBuKbHk4",
  "sub": "123",
  "iss": "https://tenant.logto.app/oidc",
  "exp": 1672531200,
  "iat": 1672527600,
  "scope": "profile",
  "client_id": "client-id"
}

개인 액세스 토큰이란? 언제 개인 액세스 토큰을 사용해야 할까요?

개인 액세스 토큰, 기계 간 (Machine-to-Machine) 인증 (Authentication), 그리고 API 키의 정의 및 실제 시나리오