본문으로 건너뛰기

조직 (비 API) 권한 보호

조직 템플릿을 사용하여 Logto에서 조직 수준의 역할 및 권한을 관리하고 적용하세요. 이를 통해 조직 컨텍스트 내에서 앱 기능 및 워크플로우에 대한 접근을 제어할 수 있습니다.

조직 (비 API) 권한이란?​

조직 권한(비 API)은 사용자가 조직 컨텍스트 내에서 무엇을 할 수 있는지를 제어하지만, API 수준에서 강제 적용되지는 않습니다. 대신, 백엔드 API가 아닌 앱 기능, UI 요소, 워크플로우 또는 비즈니스 액션에 대한 접근을 관리합니다.

사용 사례 예시

  • 조직 내에서 멤버 초대 또는 관리
  • 조직 역할 할당 또는 변경
  • 조직의 결제, 설정, 관리 기능 관리
  • API 엔드포인트가 없는 대시보드, 분석, 내부 도구 접근

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

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

Logto에서의 동작 방식​

  • 조직 수준 RBAC: 역할과 권한은 조직 템플릿에서 정의됩니다. 사용자가 조직에 가입하면 하나 이상의 역할이 할당되어 특정 권한을 부여받습니다.
  • 비 API 강제 적용: 권한은 앱의 UI, 워크플로우 또는 백엔드 로직에서 확인 및 적용되며, 반드시 API 게이트웨이에서만 적용되는 것은 아닙니다.
  • API 보호와 분리: 조직(비 API) 권한은 API 리소스 권한과 구분됩니다. 고급 시나리오에서는 둘을 조합할 수 있습니다.
조직 권한 RBAC

구현 개요​

  1. Logto의 조직 템플릿에서 조직 권한을 정의합니다.
  2. 조직별 액션에 필요한 권한을 묶은 조직 역할을 생성합니다.
  3. 각 조직 내에서 사용자 또는 클라이언트에 역할을 할당합니다.
  4. 리프레시 토큰 또는 클라이언트 자격 증명 플로우를 사용하여 현재 조직에 대한 **조직 토큰 (JWT)**을 획득합니다.
  5. 앱의 UI 또는 백엔드에서 액세스 토큰을 검증하여 조직 권한을 적용합니다.

인가 플로우: 조직 권한 인증 및 보호​

다음 플로우는 클라이언트(웹, 모바일, 백엔드)가 조직 토큰을 획득하고 비 API 권한 적용에 사용하는 과정을 보여줍니다.

이 플로우는 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 주요 단계에 초점을 맞춥니다. 실제 동작 방식은 아래 설명을 참고하세요.

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

구현 단계​

조직 권한 등록​

  1. 콘솔 → 조직 템플릿 → 조직 권한

     으로 이동하세요.
  2. 필요한 조직 권한을 정의하세요 (예: invite:member, manage:billing, view:analytics).

전체 설정 단계는 조직 권한 정의하기를 참고하세요.

조직 역할 설정​

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

     로 이동하세요.
  2. 앞서 정의한 조직 권한을 묶은 역할을 생성하세요 (예: admin, member, billing).
  3. 각 조직 내에서 사용자 또는 클라이언트에 이 역할을 할당하세요.

전체 설정 단계는 조직 역할 사용하기를 참고하세요.

조직 토큰(비 API) 획득​

클라이언트/앱은 조직 권한에 접근하기 위해 조직 토큰(비 API)을 획득해야 합니다. 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 목록을 얻을 수 있습니다. 이 클레임은 사용자가 소속된 모든 조직을 나열하므로, 애플리케이션에서 조직을 나열하거나 전환하는 것이 쉽습니다.

특정 조직에 대한 조직 토큰을 요청하려면 getOrganizationToken 또는 유사한 메서드(예: 조직 ID와 함께 사용하는 getAccessToken)를 사용하세요.

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

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

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

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

  • organization_id: 토큰을 발급받을 조직의 ID
  • scope: 요청할 조직 권한(예: 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
&organization_id=your-organization-id
&scope=invite:member manage:billing

조직 토큰 검증​

Logto가 발급한 조직 토큰(JWT)에는 앱/UI/백엔드에서 조직 수준 접근 제어를 적용할 수 있는 클레임이 포함되어 있습니다.

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

  • 토큰 서명 검증(Logto의 JWKs 사용)
  • 토큰 만료 여부 확인(exp 클레임)
  • iss(발급자)가 Logto 엔드포인트와 일치하는지 확인
  • aud(대상)이 포맷된 조직 식별자(예: urn:logto:organization:{organization_id})와 일치하는지 확인
  • scope 클레임(공백 구분)을 분리하여 필요한 권한이 포함되어 있는지 확인

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

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.

모범 사례 및 보안 팁​

  • UI 강제 적용만으로는 충분하지 않습니다: 중요한 액션은 반드시 백엔드에서 권한을 검증하세요.
  • 대상 제한 사용: 항상 aud 클레임을 확인하여 토큰이 의도한 조직용인지 검증하세요.
  • 비즈니스 중심 권한 사용: 실제 액션에 매핑되는 명확한 이름을 사용하고, 각 조직 역할에 필요한 권한만 부여하세요.
  • API와 비 API 권한을 분리하세요(단, 둘 다 하나의 역할에 포함될 수 있음).
  • 제품이 발전함에 따라 조직 템플릿을 정기적으로 검토하세요.

자주 묻는 질문​

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

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

비 API 권한은 어디에서 강제 적용해야 하나요?​

비 API 권한은 UI(기능 제한)와 서버 측 로직(민감한 액션)에 모두 확인하세요.

추가 자료​

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

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