본문으로 건너뛰기

조직 수준 API 리소스 보호하기

API 리소스와 조직 템플릿을 결합하여 각 조직 내에서 API 및 데이터 접근을 제한함으로써, SaaS에서 테넌트 수준의 격리를 보장하세요.

조직 수준 API 리소스란?​

조직 수준 API 리소스는 특정 조직에 범위가 지정된 애플리케이션의 엔드포인트 또는 서비스입니다. 이러한 API는 조직 컨텍스트에 따라 인가 (Authorization)와 접근을 강제하여, 사용자 또는 클라이언트가 자신의 조직과 관련된 데이터 및 작업만 접근할 수 있도록 보장합니다.

사용 사례 예시

  • 조직 구성원, 역할 또는 설정을 관리하는 API (예: /organizations/{organizationId}/members)
  • 조직 범위의 대시보드, 분석, 리포트
  • 조직에 연결된 결제, 구독, 감사 엔드포인트
  • 테넌트별로 작업과 데이터가 분리되어야 하는 모든 API

Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 활용하여 이러한 조직 API를 안전하게 보호하며, 멀티 테넌트 SaaS 아키텍처를 지원합니다.

이러한 권한은 조직 템플릿에 정의된 조직 역할을 통해 관리됩니다. 모든 조직은 동일한 템플릿을 사용하므로, 모든 조직에 일관된 권한 모델이 적용됩니다.

Logto에서의 동작 방식​

  • API 리소스와 권한은 전역적으로 등록됨: 각 API 리소스는 Logto에서 고유한 리소스 지표 (URI)와 권한(스코프) 집합으로 정의됩니다.
  • 조직 수준의 역할: 조직 역할은 조직 템플릿에서 정의됩니다. API 리소스 권한(스코프)은 조직 역할에 할당되고, 각 조직 내의 사용자 또는 클라이언트에 할당됩니다.
  • 컨텍스트 인식 인가: 클라이언트가 API 리소스와 organization_id를 함께 포함하여 액세스 토큰을 요청하면, Logto는 조직 컨텍스트와 API 대상이 모두 포함된 토큰을 발급합니다. 토큰의 권한(스코프)은 지정된 조직에 대한 사용자의 조직 역할에 따라 결정됩니다.
  • 전역 리소스와의 분리: API 리소스는 조직 컨텍스트와 함께 또는 없이 접근할 수 있습니다. 조직 RBAC는 요청에 organization_id가 포함된 경우에만 적용됩니다. 모든 사용자에게 공유되는 API의 경우 전역 API 리소스 보호하기를 참고하세요.
조직 수준 API 리소스 RBAC

구현 개요​

  1. API 리소스를 등록하고, Logto에서 해당 권한(스코프)을 정의하세요.
  2. 조직 역할을 정의하고, 관련 API 권한을 할당하세요.
  3. 각 조직 내에서 사용자 또는 클라이언트에 역할을 할당하세요.
  4. API에 대한 액세스 토큰을 요청할 때 organization_id를 포함하여 조직 컨텍스트를 추가하세요.
  5. API에서 액세스 토큰을 검증하여 조직 컨텍스트와 권한을 모두 강제하세요.

Logto의 조직 RBAC 적용 방식​

  • organization_id 없이 액세스 토큰을 요청하면, 전역 역할/권한만 고려됩니다.
  • organization_id와 함께 액세스 토큰을 요청하면, Logto는 해당 조직에 대한 사용자의 조직 역할과 연결된 권한을 평가합니다.
  • 결과 JWT에는 API 대상(aud 클레임)과 조직 컨텍스트(organization_id 클레임)가 모두 포함되며, 스코프는 사용자의 조직 역할에 의해 부여된 권한으로 필터링됩니다.

인가 플로우: 조직 컨텍스트로 API 인증 및 보호하기​

다음 플로우는 클라이언트(웹, 모바일, 백엔드)가 조직 토큰을 획득하고, 조직 수준 API 리소스에 접근하는 과정을 보여줍니다.

이 플로우는 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 핵심 단계에 초점을 맞추고 있습니다. 실제 동작 방식을 계속 읽어보세요.

사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격증명 + 조직 컨텍스트를 사용하는 백엔드 서비스 또는 스크립트.

구현 단계​

API 리소스 등록하기​

  1. 콘솔 → API 리소스로 이동하세요.
  2. 새 API 리소스(예: https://api.yourapp.com/org)를 생성하고, 해당 권한(스코프)을 정의하세요.

전체 설정 방법은 권한과 함께 API 리소스 정의하기를 참고하세요.

조직 역할 설정하기​

  1. 콘솔 → 조직 템플릿 → 조직 역할

     로 이동하세요.
  2. 조직 역할(예: admin, member)을 생성하고, 각 역할에 API 권한을 할당하세요.
  3. 각 조직 내에서 사용자 또는 클라이언트에 역할을 할당하세요. 아직 멤버가 아니라면 초대하거나 먼저 추가하세요.

전체 설정 방법은 조직 역할 사용하기를 참고하세요.

API 리소스를 위한 조직 토큰 획득하기​

클라이언트/앱은 조직 수준 API에 접근하기 위해 resource와 organization_id를 모두 포함하여 토큰을 요청해야 합니다. Logto는 조직 토큰을 JSON Web Token (JWT) 형태로 발급합니다. 리프레시 토큰 플로우 또는 클라이언트 자격증명 플로우를 사용할 수 있습니다.

리프레시 토큰 플로우​

거의 모든 Logto 공식 SDK는 리프레시 토큰 플로우를 통해 조직 토큰 획득을 기본적으로 지원합니다. 표준 OAuth 2.0 / OIDC 클라이언트 라이브러리로도 이 플로우를 구현할 수 있습니다.

Logto SDK를 초기화할 때, scopes 파라미터에 urn:logto:scope:organizations와 원하는 조직 권한(스코프)을 추가하세요.

일부 Logto SDK에는 조직용 미리 정의된 스코프가 있습니다. 예를 들어 JavaScript SDK에서는 UserScope.Organizations가 있습니다.

노트:

ID 토큰의 organizations 클레임을 확인하여 사용자가 속한 조직 ID 목록을 얻을 수 있습니다. 이 클레임은 사용자가 소속된 모든 조직을 나열하므로, 애플리케이션에서 조직을 나열하거나 전환하는 것이 쉽습니다.

getAccessToken()을 호출할 때, API 리소스(resource)와 조직 ID(organizationId)를 모두 지정하여 조직 토큰을 획득하세요.

각 SDK별 자세한 내용은 빠른 시작을 참고하세요.

클라이언트 자격증명 플로우​

기계 간 (M2M) 시나리오에서는 클라이언트 자격증명 플로우를 사용하여 조직 수준 API 리소스 권한에 대한 액세스 토큰을 획득할 수 있습니다. Logto의 /oidc/token 엔드포인트에 조직 파라미터와 함께 POST 요청을 보내면, 클라이언트 ID와 시크릿으로 조직 토큰을 요청할 수 있습니다.

요청에 포함해야 할 주요 파라미터는 다음과 같습니다:

  • resource: API 리소스 식별자(예: https://api.yourapp.com/org)
  • organization_id: 토큰을 받고자 하는 조직의 ID
  • scope: 요청할 조직 수준 API 리소스 권한(예: invite:member, manage:billing)

다음은 클라이언트 자격증명 grant 타입을 사용하는 토큰 요청 예시입니다:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&resource=https://api.yourapp.com/org
&organization_id=your-organization-id
&scope=invite:member manage:billing

조직 토큰 검증하기​

Logto가 발급한 조직 토큰(JWT)에는 API가 조직 수준 접근 제어를 강제할 수 있는 클레임이 포함되어 있습니다.

앱이 조직 토큰을 받으면 다음을 수행해야 합니다:

  • 토큰 서명 검증(Logto의 JWKs 사용)
  • 토큰 만료 여부 확인(exp 클레임)
  • iss(발급자)가 Logto 엔드포인트와 일치하는지 확인
  • aud(대상)이 등록한 API 리소스 식별자(예: https://api.yourapp.com/org)와 일치하는지 확인
  • organization_id 클레임이 올바른 조직에 범위가 지정되어 있는지 확인
  • scope 클레임(공백 구분)을 분리하여 필요한 권한이 포함되어 있는지 확인
  • API 경로에 조직 ID가 포함되어 있다면(예: /organizations/{organizationId}/members), organization_id 클레임이 경로 파라미터와 일치하는지 확인

단계별 및 언어별 가이드는 액세스 토큰 검증 방법을 참고하세요.

Optional: Handle user permission change​

User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.

Scope subset rule:

An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.

Downscoped permissions​

When a user loses permissions:

  • Newly issued tokens immediately reflect the reduced scopes.
  • Existing JWTs keep the old scopes until they expire.
  • Your API should always validate scopes and rely on short token lifetimes.

If you need faster reactions, implement your own signal that tells clients to refresh their tokens.

Enlarged permissions​

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

Recommendations​

  • Validate scopes in your API on every call.
  • Keep token expiration short.
  • Add optional notifications if you need immediate permission-change propagation.

모범 사례 및 보안 팁​

  • 항상 조직 컨텍스트를 검증하세요: 토큰만 신뢰하지 말고, 조직 범위 API 호출마다 organization_id 클레임을 확인하세요.
  • 대상 제한 사용: 항상 aud 클레임을 확인하여 토큰이 의도한 조직용인지 확인하세요.
  • 비즈니스 중심의 권한 유지: 실제 동작에 매핑되는 명확한 이름을 사용하고, 각 조직 역할에 필요한 권한만 부여하세요.
  • API와 비 API 권한을 분리하세요(가능하다면, 단일 역할에 모두 포함할 수도 있습니다).
  • 토큰 수명은 짧게 유지: 토큰이 유출될 경우 위험을 줄입니다.
  • 조직 템플릿을 정기적으로 검토: 제품이 발전함에 따라 역할과 권한을 업데이트하세요.

자주 묻는 질문​

토큰 요청에 organization_id를 포함하지 않으면 어떻게 되나요?​

전역 역할/권한만 평가됩니다. 조직 RBAC는 적용되지 않습니다.

하나의 역할에 조직 및 비조직 권한을 혼합할 수 있나요?​

아니요, 조직 권한(조직 수준 API 권한 포함)은 조직 템플릿에 의해 정의되며, 전역 API 권한과 혼합할 수 없습니다. 하지만, 조직 권한과 조직 수준 API 권한을 모두 포함하는 역할을 생성할 수는 있습니다.

추가 자료​

액세스 토큰 검증 방법 토큰 클레임 커스터마이징

사용 사례: 멀티 테넌트 SaaS 애플리케이션 구축

 RFC 8707: 리소스 지표