Management API를 통한 계정 설정
통합
Logto는 사용자 계정을 관리하기 위한 다양한 Management API를 제공합니다. 이러한 API를 사용하여 최종 사용자를 위한 셀프 서비스 계정 설정 페이지를 구축할 수 있습니다.
아키텍처
- 사용자: 계정 설정에 접근하고 관리해야 하는 인증된 최종 사용자.
- 클라이언트 애플리케이션: 사용자에게 계정 설정 페이지를 제공하는 클라이언트 애플리케이션.
- 서버 측 애플리케이션: 클라이언트에 계정 설정 API를 제공하는 서버 측 애플리케이션. Logto Management API와 상호작용합니다.
- Logto: 인증 및 인가 서비스로서의 Logto. 사용자 계정을 관리하기 위한 Management API를 제공합니다.
시퀀스 다이어그램
- 사용자가 클라이언트 애플리케이션에 접근합니다.
- 클라이언트 애플리케이션은 Logto에 인증 요청을 보내고 사용자를 Logto 로그인 페이지로 리디렉션합니다.
- 사용자가 Logto에 로그인합니다.
- 인증된 사용자가 인가 코드와 함께 클라이언트 애플리케이션으로 리디렉션됩니다.
- 클라이언트 애플리케이션은 셀프 호스팅 계정 설정 API 접근을 위해 Logto에 액세스 토큰을 요청합니다.
- Logto는 클라이언트 애플리케이션에 액세스 토큰을 부여합니다.
- 클라이언트 애플리케이션은 사용자 액세스 토큰과 함께 서버 측 애플리케이션에 계정 설정 요청을 보냅니다.
- 서버 측 애플리케이션은 사용자 액세스 토큰에서 요청자의 아이덴티티와 권한을 확인합니다. 그런 다음 Logto에서 Management API 액세스 토큰을 요청합니다.
- Logto는 서버 측 애플리케이션에 Management API 액세스 토큰을 부여합니다.
- 서버 측 애플리케이션은 Management API 액세스 토큰을 사용하여 Logto에서 사용자 데이터를 요청합니다.
- Logto는 서버의 아이덴티티와 Management API 권한을 확인하고 사용자 데이터를 반환합니다.
- 서버 측 애플리케이션은 요청자의 권한에 따라 사용자 데이터를 처리하고 사용자 계정 세부 정보를 클라이언트 애플리케이션에 반환합니다.
서버 측 애플리케이션에 Management API 통합
서버 측 애플리케이션과 Management API를 통합하는 방법에 대해 알아보려면 Management API 섹션을 확인하세요.
사용자 관리 API
사용자 데이터 스키마
Logto의 사용자 스키마에 대해 더 알고 싶다면 사용자 데이터 및 사용자 정의 데이터 섹션을 확인하세요.
사용자 프로필 및 식별자 관리 API
사용자의 프로필과 식별자는 사용자 관리에 필수적입니다. 다음 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로 사용자 정지 상태를 업데이트합니다. |
이메일 및 전화번호 인증
Logto 시스템에서 이메일 주소와 전화번호는 사용자 식별자로 사용될 수 있으므로, 이들의 인증이 필수적입니다. 이를 지원하기 위해 제공된 이메일 또는 전화번호를 인증하는 데 도움이 되는 일련의 인증 코드 API를 제공합니다.
노트:
사용자 프로필을 새로운 이메일 또는 전화번호로 업데이트하기 전에 반드시 이메일 또는 전화번호를 인증하세요.
| method | path | description |
|---|---|---|
| POST | /api/verifications/verification-code | 이메일 또는 전화번호 인증 코드를 보냅니다. |
| POST | /api/verifications/verification-code/verify | 인증 코드로 이메일 또는 전화번호를 인증합니다. |
사용자 비밀번호 관리
| method | path | description |
|---|---|---|
| POST | /api/users/{userId}/password/verify | 사용자 ID로 현재 사용자 비밀번호를 인증합니다. |
| PATCH | /api/users/{userId}/password | 사용자 ID로 사용자 비밀번호를 업데이트합니다. |
| GET | /api/users/{userId}/has-password | 사용자 ID로 사용자가 비밀번호를 가지고 있는지 확인합니다. |
노트:
사용자 비밀번호를 업데이트하기 전에 사용자의 현재 비밀번호를 인증하세요.
사용자 소셜 아이덴티티 관리
| 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를 사용하여 새로운 소셜 아이덴티티 연결을 시작합니다. |
- 사용자가 클라이언트 애플리케이션에 접근하여 소셜 아이덴티티 연결을 요청합니다.
- 클라이언트 애플리케이션은 서버에 소셜 아이덴티티 연결 요청을 보냅니다.
- 서버는 소셜 아이덴티티 제공자의 인가 URI를 얻기 위해 Logto에 요청을 보냅니다. 요청 시
state매개변수와redirect_uri를 제공해야 합니다. 소셜 아이덴티티 제공자에redirect_uri를 사전에 등록하세요. - Logto는 서버에 인가 URI를 반환합니다.
- 서버는 클라이언트 애플리케이션에 인가 URI를 반환합니다.
- 클라이언트 애플리케이션은 사용자를 IdP 인가 URI로 리디렉션합니다.
- 사용자가 IdP에 로그인합니다.
- IdP는 인가 코드와 함께 사용자를
redirect_uri를 통해 클라이언트 애플리케이션으로 리디렉션합니다. - 클라이언트 애플리케이션은
state를 검증하고 IdP 인가 응답을 서버로 전달합니다. - 서버는 Logto에 소셜 아이덴티티를 사용자에게 연결하도록 요청합니다.
- Logto는 인가 코드를 사용하여 IdP에서 사용자 정보를 가져옵니다.
- IdP는 사용자 정보를 Logto에 반환하고 Logto는 소셜 아이덴티티를 사용자에게 연결합니다.
노트:
사용자에게 새로운 소셜 아이덴티티를 연결할 때 고려해야 할 몇 가지 제한 사항이 있습니다:
- Management API는 세션 컨텍스트가 없으므로, 소셜 인증 상태를 안전하게 유지하기 위해 활성 세션이 필요한 소셜 커넥터는 Management API를 통해 연결할 수 없습니다. 지원되지 않는 커넥터에는 apple, 표준 OIDC 및 표준 OAuth 2.0 커넥터가 포함됩니다.
- 같은 이유로, Logto는 인가 응답에서
state매개변수를 검증할 수 없습니다. 클라이언트 앱에state매개변수를 저장하고 인가 응답을 받을 때 이를 검증하세요. - 소셜 아이덴티티 제공자에
redirect_uri를 사전에 등록해야 합니다. 그렇지 않으면 소셜 IdP가 사용자를 클라이언트 앱으로 다시 리디렉션하지 않습니다. 소셜 IdP는 사용자 로그인용과 프로필 바인딩 페이지용으로 두 개 이상의 콜백redirect_uri를 허용해야 합니다.
사용자 엔터프라이즈 아이덴티티 관리
| method | path | description |
|---|---|---|
| GET | /api/users/{userId}?includeSsoIdentities=true | 사용자 ID로 사용자 세부 정보를 가져옵니다. 엔터프라이즈 아이덴티티는 ssoIdentities 필드에서 찾을 수 있습니다. 사용자 세부 정보 API에 includeSsoIdentities=true 쿼리 매개변수를 추가하여 포함시킵니다. |
현재 Management API는 사용자에게 엔터프라이즈 아이덴티티를 연결하거나 연결 해제하는 것을 지원하지 않습니다. 사용자가 연결한 엔터프라이즈 아이덴티티만 표시할 수 있습니다.
개인 액세스 토큰
| 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} | 이름으로 사용자의 토큰을 업데이트합니다. |
개인 액세스 토큰은 사용자가 자격 증명과 상호작용 로그인 없이 액세스 토큰을 부여할 수 있는 안전한 방법을 제공합니다. 개인 액세스 토큰 사용에 대해 더 알아보세요.
사용자 MFA 설정 관리
| 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 인증을 삭제합니다. |
사용자 계정 삭제
| method | path | description |
|---|---|---|
| DELETE | /api/users/{userId} | 사용자 ID로 사용자를 삭제합니다. |
사용자 세션 관리
| method | path | description |
|---|---|---|
| GET | /api/users/{userId}/sessions | 사용자 ID로 사용자 세션을 가져옵니다. |
| GET | /api/users/{userId}/sessions/{sessionId} | 세션 ID로 사용자 세션을 가져옵니다. |
| DELETE | /api/users/{userId}/sessions/{sessionId} | 세션 ID로 사용자 세션을 삭제합니다. |
사용자 승인된 앱 (grants) 관리
| method | path | description |
|---|---|---|
| GET | /api/users/{userId}/grants | 사용자의 활성 앱 승인을 나열합니다. |
| DELETE | /api/users/{userId}/grants/{grantId} | 특정 앱 승인을 ID로 취소합니다. |
승인 목록에 대한 선택적 쿼리 매개변수:
appType=firstParty: 퍼스트 파티 앱 승인만 반환합니다.appType=thirdParty: 서드 파티 앱 승인만 반환합니다.appType생략: 모든 활성 승인을 반환합니다.
승인이 취소되면, 해당 승인에 대해 이전에 발급된 불투명 액세스 토큰 및 리프레시 토큰이 무효화됩니다.