조직 멤버 초대

다중 조직 애플리케이션으로서, 일반적인 요구 사항 중 하나는 조직에 멤버를 초대하는 것입니다. 이 가이드에서는 애플리케이션에서 이 기능을 구현하는 단계와 기술적 세부 사항을 안내합니다.

흐름 개요

전체 프로세스는 아래 다이어그램에 설명되어 있습니다:

조직 역할 생성

조직에 멤버를 초대하기 전에, 조직 역할을 생성해야 합니다. 자세한 지침은 조직 템플릿 구성 가이드를 참조하세요.

이 가이드에서는 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": "Welcome to my organization",
  "content": "<p>Join my organization by this <a href=\"{{link}}\" target=\"_blank\">link</a>.</p>",
  "usageType": "OrganizationInvitation",
  "type": "text/html"
}

이메일 내용의 {{link}} 자리표시는 이메일을 보낼 때 실제 초대 링크로 대체됩니다. 이 가이드에서는 https://your-app.com/invitation/accept/{your-invitation-id}가 될 것입니다.

노트:

Logto Cloud의 내장 "Logto 이메일 서비스"는 현재 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 페이로드는 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를 사용하여 초대에 대한 사용자의 응답을 처리하세요.

위에 나열된 모든 API는 유효한 "조직 토큰"이 필요합니다. 조직 토큰을 얻는 방법은 이 가이드를 확인하세요.

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

위의 설정을 통해 이제 이메일로 초대를 보낼 수 있으며, 초대받는 사람은 할당된 역할로 조직에 가입할 수 있습니다.

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

조직 토큰에서 스코프 업데이트 처리

노트:

앱과 조직을 통합했는지 확인하세요. 자세한 내용은 통합 가이드를 확인하세요.

조직 토큰에서 스코프 업데이트를 관리하는 방법은 다음과 같습니다:

기존 스코프 철회

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

새로운 스코프 부여

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

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

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

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

이 경우, 사용자의 조직 토큰을 업데이트하기 위해 재로그인 또는 재동의 과정을 트리거해야 합니다. 예를 들어, 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',
  });

  위의 코드는 동의 화면으로 페이지 이동을 트리거하고, 사용자의 조직 토큰에 업데이트된 스코프와 함께 앱으로 자동 리디렉션됩니다.

관련 리소스

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