불투명 토큰 (Opaque token)

인증 (Authentication) 과정에서 리소스가 지정되지 않은 경우, Logto는 JWT 대신 불투명 토큰 (opaque token)을 액세스 토큰 (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)
}

토큰이 유효하지 않은 경우, active 필드는 false가 되고, sub 필드는 생략됩니다.

다음은 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 and organizations)

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

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

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

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

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

불투명 토큰과 조직 (Opaque token and organizations)