Management API를 통한 계정 설정

통합 (Integrations)

Logto는 사용자 계정을 관리할 수 있는 다양한 Management API를 제공합니다. 이러한 API를 사용하여 최종 사용자를 위한 셀프 서비스 계정 설정 페이지를 구축할 수 있습니다.

아키텍처 (Architecture)

1. 사용자: 계정 설정에 접근하고 관리해야 하는 인증된 최종 사용자.
2. 클라이언트 애플리케이션: 사용자에게 계정 설정 페이지를 제공하는 클라이언트 애플리케이션.
3. 서버 측 애플리케이션: 클라이언트에 계정 설정 API를 제공하는 서버 측 애플리케이션. Logto Management API와 상호작용합니다.
4. Logto: 인증 (Authentication) 및 인가 (Authorization) 서비스로서의 Logto. 사용자 계정 관리를 위한 Management API를 제공합니다.

시퀀스 다이어그램 (Sequence diagram)

1. 사용자가 클라이언트 애플리케이션에 접근합니다.
2. 클라이언트 애플리케이션이 Logto에 인증 요청을 보내고 사용자를 Logto 로그인 페이지로 리디렉션합니다.
3. 사용자가 Logto에 로그인합니다.
4. 인증된 사용자가 인가 코드와 함께 클라이언트 애플리케이션으로 리디렉션됩니다.
5. 클라이언트 애플리케이션이 셀프 호스팅 계정 설정 API 접근을 위해 Logto에 액세스 토큰을 요청합니다.
6. Logto가 클라이언트 애플리케이션에 액세스 토큰을 발급합니다.
7. 클라이언트 애플리케이션이 사용자 액세스 토큰과 함께 서버 측 애플리케이션에 계정 설정 요청을 보냅니다.
8. 서버 측 애플리케이션이 사용자 액세스 토큰에서 요청자의 신원과 권한을 검증한 후, Logto에 Management API 액세스 토큰을 요청합니다.
9. Logto가 서버 측 애플리케이션에 Management API 액세스 토큰을 발급합니다.
10. 서버 측 애플리케이션이 Management API 액세스 토큰을 사용하여 Logto에서 사용자 데이터를 요청합니다.
11. Logto가 서버의 신원과 Management API 권한을 검증한 후 사용자 데이터를 반환합니다.
12. 서버 측 애플리케이션이 요청자의 권한에 따라 사용자 데이터를 처리하고, 사용자 계정 정보를 클라이언트 애플리케이션에 반환합니다.

서버 측 애플리케이션에 Management API 통합하기

서버 측 애플리케이션과 Management API를 통합하는 방법은 Management API 섹션을 참고하세요.

사용자 관리 API (User Management APIs)

사용자 데이터 스키마 (User data schema)

Logto의 사용자 스키마에 대해 더 알고 싶다면 사용자 데이터 및 커스텀 데이터 섹션을 참고하세요.

사용자 프로필 및 식별자 관리 API (User profile and identifiers Management APIs)

사용자 프로필과 식별자는 사용자 관리에 필수적입니다. 다음 API를 사용하여 사용자 프로필과 식별자를 관리할 수 있습니다.

method	path	description
GET	/api/users/{userId}	사용자 ID로 사용자 정보를 조회합니다.
PATCH	/api/users/{userId}	사용자 정보를 업데이트합니다.
PATCH	/api/users/{userId}/profile	사용자 ID로 사용자 프로필 필드를 업데이트합니다.
GET	/api/users/{userId}/custom-data	사용자 ID로 사용자 커스텀 데이터를 조회합니다.
PATCH	/api/users/{userId}/custom-data	사용자 ID로 사용자 커스텀 데이터를 업데이트합니다.
PATCH	/api/users/{userId}/is-suspended	사용자 ID로 사용자 정지 상태를 업데이트합니다.

이메일 및 전화번호 인증 (Email and phone number verification)

Logto 시스템에서 이메일 주소와 전화번호 모두 사용자 식별자로 사용될 수 있으므로, 이들의 인증은 필수적입니다. 이를 지원하기 위해 제공된 이메일 또는 전화번호를 인증할 수 있는 일련의 인증 코드 API를 제공합니다.

노트:

새 이메일 또는 전화번호로 사용자 프로필을 업데이트하기 전에 반드시 이메일 또는 전화번호를 인증하세요.

method	path	description
POST	/api/verifications/verification-code	이메일 또는 전화번호 인증 코드를 전송합니다.
POST	/api/verifications/verification-code/verify	인증 코드로 이메일 또는 전화번호를 인증합니다.

사용자 비밀번호 관리 (User password management)

method	path	description
POST	/api/users/{userId}/password/verify	사용자 ID로 현재 비밀번호를 인증합니다.
PATCH	/api/users/{userId}/password	사용자 ID로 비밀번호를 업데이트합니다.
GET	/api/users/{userId}/has-password	사용자 ID로 비밀번호 존재 여부를 확인합니다.

노트:

사용자 비밀번호를 업데이트하기 전에 반드시 현재 비밀번호를 인증하세요.

사용자 소셜 아이덴티티 관리 (User social identities management)

method	path	description
GET	/api/users/{userId}	사용자 ID로 사용자 정보를 조회합니다. 소셜 아이덴티티는 identities 필드에서 확인할 수 있습니다.
POST	/api/users/{userId}/identities	인증된 소셜 아이덴티티를 사용자 ID로 연결합니다.
DELETE	/api/users/{userId}/identities	사용자 ID로 소셜 아이덴티티 연결을 해제합니다.
PUT	/api/users/{userId}/identities	사용자 ID로 연결된 소셜 아이덴티티를 직접 업데이트합니다.
POST	/api/connectors/{connectorId}/authorization-uri	소셜 아이덴티티 제공자의 인가 URI를 가져옵니다. 이 URI를 사용하여 새로운 소셜 아이덴티티 연결을 시작하세요.

1. 사용자가 클라이언트 애플리케이션에 접근하여 소셜 아이덴티티 연결을 요청합니다.
2. 클라이언트 애플리케이션이 서버에 소셜 아이덴티티 연결 요청을 전송합니다.
3. 서버가 소셜 아이덴티티 제공자의 인가 URI를 얻기 위해 Logto에 요청을 보냅니다. 요청 시 state 파라미터와 redirect_uri를 직접 제공해야 합니다. 반드시 소셜 아이덴티티 제공자에 redirect_uri를 등록하세요.
4. Logto가 서버에 인가 URI를 반환합니다.
5. 서버가 인가 URI를 클라이언트 애플리케이션에 반환합니다.
6. 클라이언트 애플리케이션이 사용자를 IdP 인가 URI로 리디렉션합니다.
7. 사용자가 IdP에 로그인합니다.
8. IdP가 인가 코드와 함께 사용자를 redirect_uri로 클라이언트 애플리케이션에 리디렉션합니다.
9. 클라이언트 애플리케이션이 state를 검증하고 IdP 인가 응답을 서버로 전달합니다.
10. 서버가 Logto에 소셜 아이덴티티를 사용자에 연결하도록 요청합니다.
11. Logto가 인가 코드를 사용하여 IdP에서 사용자 정보를 조회합니다.
12. IdP가 사용자 정보를 Logto에 반환하고, Logto가 소셜 아이덴티티를 사용자에 연결합니다.

노트:

사용자에 새로운 소셜 아이덴티티를 연결할 때 고려해야 할 몇 가지 제한 사항이 있습니다:

• Management API에는 세션 컨텍스트가 없으므로, 소셜 인증 상태를 안전하게 유지하기 위해 활성 세션이 필요한 소셜 커넥터는 Management API를 통해 연결할 수 없습니다. 지원되지 않는 커넥터에는 apple, 표준 OIDC 및 표준 OAuth 2.0 커넥터가 포함됩니다.
• 같은 이유로, Logto는 인가 응답의 state 파라미터를 검증할 수 없습니다. 클라이언트 앱에서 state 파라미터를 저장하고 인가 응답을 받을 때 반드시 검증하세요.
• 사전에 소셜 아이덴티티 제공자에 redirect_uri를 등록해야 합니다. 그렇지 않으면 소셜 IdP가 사용자를 클라이언트 앱으로 리디렉션하지 않습니다. 소셜 IdP는 사용자 로그인용, 프로필 바인딩 페이지용 등 둘 이상의 콜백 redirect_uri를 허용해야 합니다.

사용자 엔터프라이즈 아이덴티티 관리 (User enterprise identities management)

method	path	description
GET	/api/users/{userId}?includeSsoIdentities=true	사용자 ID로 사용자 정보를 조회합니다. 엔터프라이즈 아이덴티티는 ssoIdentities 필드에서 확인할 수 있습니다. API에 includeSsoIdentities=true 쿼리 파라미터를 추가하세요.

현재 Management API는 사용자에 엔터프라이즈 아이덴티티를 연결하거나 해제하는 기능을 지원하지 않습니다. 연결된 엔터프라이즈 아이덴티티만 표시할 수 있습니다.

개인 액세스 토큰 (Personal access token)

method	path	description
GET	/api/users/{userId}/personal-access-tokens	사용자의 모든 개인 액세스 토큰을 조회합니다.
POST	/api/users/{userId}/personal-access-tokens	사용자에 새로운 개인 액세스 토큰을 추가합니다.
DELETE	/api/users/{userId}/personal-access-tokens/{name}	이름으로 사용자의 토큰을 삭제합니다.
PATCH	/api/users/{userId\s}/personal-access-tokens/{name}	이름으로 사용자의 토큰을 업데이트합니다.

개인 액세스 토큰은 사용자가 자격 증명과 상호작용 로그인 없이 액세스 토큰 (Access token)을 안전하게 부여할 수 있는 방법을 제공합니다. 개인 액세스 토큰 사용법에 대해 더 알아보세요.

사용자 MFA 설정 관리 (User MFA settings management)

method	path	description
GET	/api/users/{userId}/mfa-verifications	사용자 ID로 사용자 MFA 설정을 조회합니다.
POST	/api/users/{userId}/mfa-verifications	사용자 ID로 사용자 MFA 인증을 설정합니다.
DELETE	/api/users/{userId}/mfa-verifications/{verificationId}	ID로 사용자 MFA 인증을 삭제합니다.

사용자 계정 삭제 (User account deletion)

method	path	description
DELETE	/api/users/{userId}	사용자 ID로 사용자를 삭제합니다.

사용자 세션 관리 (User session management)

method	path	description
GET	/api/users/{userId}/sessions	사용자 ID로 사용자 세션을 조회합니다.
GET	/api/users/{userId}/sessions/{sessionId}	세션 ID로 사용자 세션을 조회합니다.
DELETE	/api/users/{userId}/sessions/{sessionId}	세션 ID로 사용자 세션을 삭제합니다.