조직 구성원 초대하기

다중 조직 애플리케이션에서 흔히 요구되는 기능 중 하나는 조직에 구성원을 초대하는 것입니다. 이 가이드에서는 애플리케이션에서 이 기능을 구현하는 단계와 기술적 세부 사항을 안내합니다.

흐름 개요

전체 프로세스는 아래 다이어그램과 같이 설명됩니다:

조직 역할 생성하기

조직에 구성원을 초대하기 전에, 조직 역할을 생성해야 합니다. 조직 역할과 권한에 대해 더 알고 싶다면 조직 템플릿을 확인하세요.

이 가이드에서는 admin과 member라는 두 가지 대표적인 조직 역할을 생성해보겠습니다.

admin 역할은 조직 내 모든 리소스에 대한 전체 접근 권한을 가지며, member 역할은 제한된 접근 권한을 가집니다. 예를 들어, 각 역할은 다음과 같은 권한 집합을 가질 수 있습니다:

• admin 역할:
  • read:data - 모든 조직 데이터 리소스 읽기 권한
  • write:data - 모든 조직 데이터 리소스 쓰기 권한
  • delete:data - 모든 조직 데이터 리소스 삭제 권한
  • invite:member - 조직에 구성원 초대
  • manage:member - 조직 내 구성원 관리
  • delete:member - 조직에서 구성원 제거
• member 역할:
  • read:data - 모든 조직 데이터 리소스 읽기 권한
  • write:data - 모든 조직 데이터 리소스 쓰기 권한
  • invite:member - 조직에 구성원 초대

이 작업은 Logto Console에서 쉽게 할 수 있습니다. 또한 Logto Management API를 사용하여 프로그래밍 방식으로 조직 역할을 생성할 수도 있습니다.

이메일 커넥터 구성하기

초대장은 이메일을 통해 전송되므로, 이메일 커넥터가 올바르게 구성되어 있는지 확인하세요. 초대장을 보내려면 이메일 템플릿 사용 유형 중 OrganizationInvitation을 설정해야 합니다. 또한 조직(예: 조직명, 로고) 및 초대자(예: 초대자 이메일, 이름) 변수를 내용에 포함하거나, 필요에 따라 다국어 템플릿을 커스터마이즈할 수 있습니다.

OrganizationInvitation 사용 유형의 샘플 이메일 템플릿은 아래와 같습니다:

{
  "subject": "우리 조직에 오신 것을 환영합니다",
  "content": "<p>{{organization.name}}에 이 <a href=\"{{link}}\" target=\"_blank\">링크</a>로 참여하세요.</p>",
  "usageType": "OrganizationInvitation",
  "type": "text/html"
}

이메일 내용의 {{link}} 플레이스홀더는 이메일 발송 시 실제 초대 링크로 대체됩니다. 이 가이드에서는 https://your-app.com/invitation/accept/{your-invitation-id}와 같은 형태라고 가정합니다.

노트:

Logto Cloud의 내장 "Logto email service"는 현재 OrganizationInvitation 사용 유형을 지원하지 않습니다. 대신, 이메일 커넥터(예: Sendgrid)를 구성하고 OrganizationInvitation 템플릿을 설정해야 합니다.

Logto Management API로 초대 처리하기

노트:

아직 Logto Management API를 설정하지 않았다면, Management API와 상호작용하기를 참고하세요.

조직 기능에는 초대 관련 Management API가 제공됩니다. 이 API들을 통해 다음 작업을 할 수 있습니다:

• POST /api/organization-invitations로 조직 역할이 할당된 조직 초대 생성

• POST /api/organization-invitations/{id}/message로 초대받는 사람에게 이메일로 조직 초대 전송
  참고: 이 API의 payload에는 link 속성이 지원되므로, 초대 ID를 기반으로 초대 링크를 작성할 수 있습니다. 예시:

  {
    "link": "https://your-app.com/invitation/accept/{your-invitation-id}"
  }

  이에 따라, 초대받는 사람이 초대 링크를 통해 애플리케이션에 접근할 때 랜딩 페이지를 구현해야 합니다.

• GET /api/organization-invitations & GET /api/organization-invitations/{id}로 모든 초대장 또는 특정 초대장(ID 기준) 조회
  랜딩 페이지에서 이 API들을 사용하여 사용자가 받은 모든 초대장 또는 특정 초대장 정보를 표시할 수 있습니다.

• PUT /api/organization-invitations/{id}/status로 초대 상태를 업데이트하여 초대를 수락 또는 거절
  사용자의 초대 응답을 처리할 때 이 API를 사용하세요.

조직 역할 기반 접근 제어(RBAC)로 사용자 권한 관리하기

위의 설정을 마치면, 이메일로 초대장을 보내고 초대받은 사용자가 할당된 역할로 조직에 참여할 수 있습니다.

조직 내 서로 다른 역할을 가진 사용자는 조직 토큰에 서로 다른 스코프(권한)를 가지게 됩니다. 따라서 클라이언트 앱과 백엔드 서비스 모두 이 스코프를 확인하여 노출되는 기능과 허용되는 동작을 결정해야 합니다.

조직 토큰의 스코프 업데이트 처리하기

노트:

이 섹션은 조직 템플릿 및 인가(Authorization) 시나리오에 대한 고급 주제를 다룹니다. 해당 개념에 익숙하지 않다면 먼저 인가 (Authorization) 및 조직 템플릿을 읽어보세요.

조직 토큰의 스코프 업데이트 관리는 다음과 같습니다:

기존 스코프 취소(Revoking existing scopes)

예를 들어, 관리자를 일반 멤버로 강등할 경우 사용자에게서 스코프를 제거해야 합니다. 이 경우, 캐시된 조직 토큰을 단순히 삭제하고 리프레시 토큰으로 새 토큰을 받아오면 됩니다. 축소된 스코프는 새로 발급된 조직 토큰에 즉시 반영됩니다.

새로운 스코프 부여(Granting new scopes)

이 경우는 두 가지 시나리오로 나눌 수 있습니다:

인증 시스템에 이미 정의된 새 스코프 부여

스코프 취소와 유사하게, 새로 부여된 스코프가 이미 인증 서버에 등록되어 있다면, 새 조직 토큰을 발급받기만 하면 새 스코프가 즉시 반영됩니다.

인증 시스템에 새로 도입된 스코프 부여

이 경우, 사용자의 조직 토큰을 업데이트하기 위해 재로그인 또는 재동의(consent) 과정을 트리거해야 합니다. 예: Logto SDK의 signIn 메서드 호출.

실시간 권한 체크 및 조직 토큰 업데이트 구현하기

Logto는 조직 내 사용자의 실시간 권한을 조회할 수 있는 Management API를 제공합니다.

• GET /api/organizations/{id}/users/{userId}/scopes (API 참조)

이후 사용자의 조직 토큰 내 스코프와 실시간 권한을 비교하여 승격 또는 강등 여부를 판단할 수 있습니다.

• 강등된 경우, 캐시된 조직 토큰을 삭제하면 SDK가 자동으로 스코프가 업데이트된 새 토큰을 발급합니다.

  const { clearAccessToken } = useLogto();
  
  ...
  // 실시간 스코프가 조직 토큰 스코프보다 적을 경우
  await clearAccessToken();

  이 과정에는 재로그인 또는 재동의가 필요하지 않습니다. Logto SDK가 자동으로 새 조직 토큰을 발급합니다.

• 인증 시스템에 새 스코프가 도입된 경우, 재로그인 또는 재동의 과정을 트리거하여 조직 토큰을 업데이트해야 합니다. React SDK 예시:

  const { clearAllTokens, signIn } = useLogto();
  
  ...
  // 실시간 스코프에 새로 할당된 스코프가 있을 경우
  await clearAllTokens();
  signIn({
    redirectUri: '<your-sign-in-redirect-uri>',
    prompt: 'consent',
  });

  위 코드는 동의 화면(consent screen)으로 페이지 이동을 트리거하고, 동의 후 자동으로 앱으로 리디렉션되어 조직 토큰의 스코프가 업데이트됩니다.

관련 리소스

다중 테넌트 앱에서 사용자 협업을 구현하는 방법