본문으로 건너뛰기

불투명 토큰 (Opaque token)

인증 (Authentication) 과정에서 리소스가 지정되지 않은 경우, Logto는 JWT 대신 불투명 토큰 (opaque access token)을 발급합니다. 불투명 토큰은 임의의 문자열이며, JWT보다 훨씬 짧습니다:

{
  "access_token": "some-random-string", // 불투명 토큰 (opaque token)
  "expires_in": 3600,
  "id_token": "eyJhbGc...aBc", // JWT
  "scope": "openid profile email",
  "token_type": "Bearer"
}

불투명 토큰은 userinfo 엔드포인트 호출 및 인증 (Authentication)이 필요한 보호된 리소스에 접근하는 데 사용할 수 있습니다. JWT가 아니기 때문에, 리소스 서버는 이를 어떻게 검증할 수 있을까요?

Logto는 불투명 토큰을 검증할 수 있는 introspection 엔드포인트를 제공합니다. 기본적으로 introspection 엔드포인트는 /oidc/token/introspection이며, POST 요청을 허용합니다. 다음 파라미터가 필요합니다:

  • token: 검증할 불투명 토큰

엔드포인트는 클라이언트 인증도 필요로 합니다. 다음 방법 중 하나를 사용할 수 있습니다:

  • HTTP Basic 인증: Authorization 헤더에 Basic <base64-encoded-credentials> 값을 사용합니다. 자격 증명은 클라이언트 ID와 클라이언트 시크릿을 콜론(:)으로 구분하여 base64로 인코딩해야 합니다.
  • HTTP POST 인증: client_id 및 client_secret 파라미터를 사용합니다:
    • client_id: 토큰을 요청한 애플리케이션의 클라이언트 ID
    • client_secret: 토큰을 요청한 애플리케이션의 클라이언트 시크릿

클라이언트 ID (앱 ID)와 클라이언트 시크릿 (앱 시크릿)은 Logto의 "전통적인 웹" 또는 "기계 간" 애플리케이션의 앱 자격 증명을 사용할 수 있습니다. 자격 증명이 올바르지 않으면 introspection 엔드포인트는 오류를 반환합니다.

introspection 엔드포인트는 토큰의 클레임 (Claim) 정보를 담은 JSON 객체를 반환합니다:

{
  "active": true, // 토큰이 유효한지 여부
  "sub": "1234567890", // 토큰의 주체 (Subject, 사용자 ID)
  "acr": "urn:logto:acr:1fa", // 인증 보증 수준 (Authentication assurance level), 달성 시
  "amr": ["pwd"], // 상호작용에서 사용된 인증 방법
  "auth_time": 1787745600 // 사용자가 인증한 시점 (epoch 초)
}

토큰이 유효하지 않은 경우, active 필드는 false가 되며 다른 클레임 (Claim)은 생략됩니다. acr, amr, auth_time 검증 방법은 Step-up 인증 (Authentication)에서 확인하세요. 구조화된 JWT 액세스 토큰 (Access token)은 /oidc/token/introspection에서 introspect 할 수 없으니, 반드시 JWT 액세스 토큰 (Access token)을 테넌트의 JWKS로 로컬에서 검증하세요.

다음은 introspection 요청의 비공식 예시입니다:

curl --location \
  --request POST 'https://[tenant-id].logto.app/oidc/token/introspection' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=some-random-string' \
  --data-urlencode 'client_id=1234567890' \
  --data-urlencode 'client_secret=1234567890'

[tenant-id]를 본인의 테넌트 ID로 교체하는 것을 잊지 마세요.

불투명 토큰 (Opaque token)과 조직 (Organization)​

불투명 토큰은 userinfo 엔드포인트를 통해 조직 (Organization) 멤버십 정보를 조회하는 데 사용할 수 있습니다. urn:logto:scope:organizations 스코프 (Scope)를 요청하면, userinfo 엔드포인트는 사용자의 조직 (Organization) 관련 클레임 (예: organizations(조직 ID) 및 organization_data)을 반환합니다.

하지만, 불투명 토큰은 조직 토큰 (Organization token)으로 사용할 수 없습니다. 조직 토큰은 항상 JWT 형식으로 발급됩니다. 그 이유는 다음과 같습니다:

  1. 조직 토큰에는 조직 (Organization)별 클레임 (예: organization_id 및 스코프된 권한 (Permission))이 포함되어 있으며, 리소스 서버에서 검증이 필요합니다.
  2. JWT 형식은 리소스 서버가 추가적인 API 호출 없이 토큰을 검증하고 조직 (Organization) 컨텍스트를 추출할 수 있게 해줍니다.

조직 토큰을 얻으려면, 리프레시 토큰 (Refresh token) 플로우 또는 클라이언트 자격 증명 플로우에서 조직 (Organization) 파라미터를 사용해야 합니다.