SAML 그룹 매핑은 사용자의 SAML 어설션에 포함된 그룹을 기반으로 Apidog 팀 액세스를 할당합니다. 이는 그룹 멤버십의 소스를 ID 공급자로 유지하면서 수동 팀 멤버십 작업을 줄여줍니다.
이 자습서에서는 Microsoft Entra ID를 사용합니다. groups 클레임을 추가하고, Entra 그룹을 Apidog 팀에 매핑하며, 로그인 시 할당된 초기 프로젝트 권한을 확인합니다.
시작하기 전에
다음이 필요합니다:
- SAML SSO가 이미 구성된 Apidog Enterprise 조직;
- Apidog에서 조직 소유자(Organization Owner) 또는 조직 관리자(Organization Admin) 액세스 권한;
- Apidog에 사용되는 Microsoft Entra 엔터프라이즈 애플리케이션에 대한 관리자 액세스 권한;
- 하나 이상의 Entra 그룹과 해당 그룹에 할당된 테스트 사용자.
SAML이 아직 구성되지 않은 경우, 먼저 Microsoft Entra ID 구성을 완료하십시오.
SAML 그룹 매핑은 Apidog 팀 및 프로젝트에 대한 액세스를 제어합니다. 이는 프로덕션 API에 대한 액세스 권한을 부여하거나 런타임 권한 부여를 대체하지 않습니다.
초기 프로젝트 액세스 할당 방식
그룹이 일치하면 Apidog는 사용자를 매핑된 팀에 추가하고 선택된 팀 역할로부터 초기 프로젝트 액세스 권한을 파생합니다.
| 매핑된 팀 역할 | 초기 프로젝트 역할 |
|---|---|
| 팀 관리자 (Team Admin) | 프로젝트 유지 관리자 (Project Maintainer) |
| 팀 멤버 (Team Member) | 프로젝트 읽기 전용 (Project Readonly) |
| 팀 게스트 (Team Guest) | 프로젝트 읽기 전용 (Project Readonly) |
Apidog는 누락된 프로젝트 멤버십을 생성하거나 아직 역할이 없는 프로젝트 멤버십을 업데이트합니다. 기존에 수동으로 할당된 프로젝트 역할은 이후 SAML 로그인 시 덮어쓰여지지 않습니다.
1단계: Microsoft Entra ID에서 groups 클레임 추가
- Microsoft Entra 관리 센터에 로그인합니다.
- 엔터프라이즈 애플리케이션으로 이동하여 Apidog SSO에 사용되는 애플리케이션을 엽니다.
- 단일 Sign-on을 선택한 다음, 속성 & 클레임을 엽니다.
- 그룹 클레임 추가를 선택합니다.
- 모든 그룹을 선택합니다.
- 그룹 클레임 이름 사용자 지정을 활성화하고 클레임 이름으로
groups를 입력합니다. - 클레임을 저장합니다.
Apidog가 groups 속성에서 Entra 그룹 개체 ID를 수신하도록 그룹 클레임을 구성합니다.
Apidog는 이 클레임의 그룹 개체 ID를 사용합니다. Microsoft Entra ID에서 그룹에 대한 다른 정보를 검색하지 않습니다.
2단계: Entra 그룹 이름 및 개체 ID 복사
- Microsoft Entra ID에서 그룹을 엽니다.
- Apidog에서 액세스 권한을 부여할 그룹을 선택합니다.
- 해당 이름과 개체 ID를 복사합니다.
Entra 그룹 페이지에 표시된 개체 ID를 사용하십시오. 개체 ID 대신 애플리케이션 ID, 테넌트 ID 또는 표시 이름을 사용하지 마십시오.
Apidog에서 매핑을 구성하는 동안 이 페이지를 열어두십시오.
3단계: 그룹을 Apidog 팀에 매핑
- Apidog에서 조직을 엽니다.
- 조직의 SAML 그룹 설정으로 이동합니다.
- 그룹 매핑을 추가합니다.
- Entra 그룹 이름을 입력하고 해당 개체 ID를 붙여넣습니다.
- 그룹이 액세스해야 하는 Apidog 팀을 선택합니다.
- 각 매핑된 팀에 필요한 팀 역할을 선택합니다.
- 매핑을 저장합니다.
Entra 그룹 개체 ID를 필요한 Apidog 팀 및 팀 역할에 매핑합니다.
SAML 그룹 매핑에는 별도의 프로젝트 역할 선택기가 없습니다. 초기 프로젝트 역할은 위 표에 표시된 팀 역할에서 파생됩니다. 다른 액세스가 필요한 경우 나중에 프로젝트 멤버 설정에서 사용자의 프로젝트 역할을 조정하십시오.
4단계: 매핑 테스트
관리자 계정 대신 테스트 계정을 사용하십시오.
- 테스트 사용자가 매핑된 Entra 그룹에 속하는지 확인합니다.
- Apidog에서 로그아웃합니다.
- 조직의 SSO 진입점을 통해 로그인합니다.
- 매핑된 팀을 열고 사용 가능한지 확인합니다.
- 사용자의 팀 역할을 확인합니다.
- 팀의 프로젝트를 열고 초기 프로젝트 역할을 확인합니다.
사용자가 이미 수동으로 할당된 프로젝트 역할을 가지고 있었다면, 다른 SSO 로그인 후에도 해당 역할이 변경되지 않는지 확인하십시오.
멤버십 제거 확인
배포 전에 그룹 제거도 테스트해야 합니다.
- 매핑된 Entra 그룹에서 테스트 사용자를 제거합니다.
- ID 공급자 변경이 완료될 때까지 기다립니다.
- 사용자가 SSO를 통해 다시 로그인하도록 합니다.
- 해당 팀 멤버십과 프로젝트 멤버십을 확인합니다.
사용자가 더 이상 매핑된 그룹에 포함되지 않으면, Apidog는 SAML 동기화 중에 해당 팀에서 사용자를 제거할 수 있습니다. 팀 멤버십이 제거되면 해당 팀의 프로젝트 멤버십도 제거됩니다.
첫 제거 테스트에는 프로덕션 계정을 사용하지 마십시오. ID 구성 및 온보딩 해제 절차를 위해 관찰된 결과를 기록하십시오.
문제 해결
| 문제 | 확인할 사항 |
|---|---|
| 사용자가 로그인했지만 팀에 추가되지 않습니다. | 클레임 이름이 정확히 groups인지, 어설션에 예상된 개체 ID가 포함되어 있는지, 그리고 Apidog의 개체 ID에 추가 공백이 없는지 확인하십시오. |
| 어설션에 그룹 값이 없습니다. | 사용자가 그룹에 속하는지, 그리고 Entra 엔터프라이즈 애플리케이션이 그룹 클레임을 전송하는지 확인하십시오. 많은 그룹 멤버십을 가진 사용자의 경우, Microsoft의 그룹 클레임 초과 지침을 검토하십시오. |
| 사용자에게 잘못된 프로젝트 역할이 있습니다. | 매핑된 팀 역할을 확인하십시오. 기존에 할당된 프로젝트 역할은 이후 SAML 동기화에 의해 덮어쓰여지지 않습니다. |
| 그룹 변경 사항이 반영되지 않습니다. | 변경 사항이 Entra에 도달했는지 확인한 다음, Apidog가 현재 어설션을 동기화할 수 있도록 새로운 SSO 로그인을 시작하십시오. |
| 사용자가 조직에 남아 있습니다. | SAML 그룹 매핑은 매핑된 팀 액세스를 관리합니다. 조직 멤버십은 초대, SSO 또는 SCIM을 통해 관리될 수도 있습니다. |
중요한 제한 사항
- Apidog는 SCIM을 통해 ID 공급자 그룹을 생성하거나 삭제하지 않습니다.
- SAML 그룹 매핑은 각 프로젝트에 대한 별도의 역할 설정을 제공하지 않습니다.
- 기존에 할당된 프로젝트 역할은 이후 SSO 로그인 시 재설정되지 않습니다.
- 동일한 사용자 및 팀에 여러 매핑이 적용될 수 있는 경우, 우선 순위 규칙을 가정하기보다 배포 전에 결과를 테스트하십시오.
- 워크스페이스 역할은 배포된 API 호출을 승인하지 않습니다.
관련 API 거버넌스 자습서:
이 자습서들은 엔터프라이즈 API 워크스페이스를 관리하기 위한 보완적인 제어 기능을 다룹니다:
- API 거버넌스 프레임워크 — 소유권, 제어, 증거 및 수명 주기 결정을 연결합니다.
- Microsoft Entra ID를 통한 SAML 그룹 매핑 — ID 공급자 그룹에서 팀 액세스를 할당합니다.
- 비밀 스캐너 — 지원되는 Apidog 자산에서 노출될 수 있는 자격 증명을 검토합니다.
- 감사 로그 — 관리 조직 활동을 조사하고 내보냅니다.
- SCIM 프로비저닝 — ID 수명 주기를 통해 조직 사용자를 관리합니다.
- 엔터프라이즈 정책 — 자격 증명, 멤버십, SSO 세션 및 초대 제어를 구성합니다.
- 자체 서비스 API 팀 관리 — 소유권 감독을 유지하면서 멤버가 생성한 팀을 허용합니다.
- GitHub Enterprise Cloud 통합 — OpenAPI 워크플로우를 위해 지원되는 GHE.com 리포지토리를 연결합니다.
관련 공식 문서: