기업은 일반적으로 ID 공급업체(IDP)를 사용해 사용자 및 사용자 그룹과 같은 ID를 관리합니다. 하지만 기업이 사내에서 자체 개발한 커스텀 애플리케이션에서는, 애플리케이션 내부에만 정의된 새로운 사용자 그룹을 고객이 직접 만들도록 허용할 수 있습니다. 이러한 애플리케이션 전용 사용자 그룹 또는 보조 사용자 ID를 외부 ID라고 합니다.
왜 ID 매핑을 설정해야 하나요?
Google이 액세스 제어를 올바르게 적용할 수 있도록, IDP ID를 Gemini Enterprise와 함께 사용할 커스텀 애플리케이션의 외부 ID와 매핑해야 합니다.
앱 결과에 액세스 제어를 적용하기 위해 Google은 IDP를 기준 정보로 사용해서 사용자가 어떤 데이터에 액세스할 수 있는지 판단합니다. 기업은 직원이 하나의 회사 사용자 인증 정보만으로 모든 회사 리소스에 로그인하고 액세스할 수 있도록 IDP를 다른 SaaS 솔루션과 연동하는 경우가 많습니다.
커스텀 애플리케이션과 같이 앱에 연결하려는 애플리케이션을 통해 외부 ID가 정의되어 있다면, 액세스 제어를 위한 기준 정보가 IDP 하나만이 아닙니다.
예를 들어 "example.com" 도메인을 사용하는 Example Organization에 "JaneDoe"라는 사용자가 있다고 가정해 보겠습니다. 이 사용자의 IDP 상 ID는 "JaneDoe@example.com"으로 정의되어 있습니다. 하지만 이 동일한 사용자가 다른 커스텀 애플리케이션 안에서는 "JDoe"라는 별도의 ID를 사용합니다. IDP는 이 ID가 존재하는 것을 알지 못할 수 있습니다. 이 때문에 Gemini Enterprise는 IDP를 통해 커스텀 애플리케이션의 ID 정보를 전달받지 못합니다.
Gemini Enterprise에서는 사용자가 만들고 매핑 정보를 가져와 저장하는 ID 매핑 스토어에 ID 매핑이 보관됩니다. 커스텀 커넥터를 사용할 계획이라면, 해당 커넥터의 데이터 스토어에 ID 매핑 스토어를 바인딩한 후, 외부 ID 정보를 사용해 데이터 스토어의 ACL 메타데이터를 업데이트할 수 있습니다.
시작하기 전에
ID 매핑을 설정하기 전에 먼저 Google Cloud 프로젝트에 ID 공급업체를 연결해야 합니다.
ID 매핑 항목 준비
가져오기에 사용할 ID 매핑 항목을 준비합니다. ID 매핑은 다음 예시와 같은 형식으로 구성해야 합니다.
{
"identity_mapping_entries": [
{
"external_identity": "u1",
"user_id": "user1@example.com"
},
{
"external_identity": "u2",
"user_id": "user2@example.com"
},
{
"external_identity": "gABC",
"group_id": "groupABC@example.com"
}
]
}
예를 들어 다음 차트는 Ext가 외부 그룹을 의미하는 사용자-그룹 멤버십 예시를 나타냅니다. 이 차트는 외부 그룹과 IDP 사용자 및 그룹 간의 예시 관계를 보여줍니다.
이 사용자-그룹 멤버십 그래프에는 다음과 같은 매핑이 존재합니다.
{
"identity_mapping_entries": [
{
"external_identity": "Ext1",
"user_id": "IDPUser1@example.com"
},
{
"external_identity": "Ext2",
"user_id": "IDPUser1@example.com"
},
{
"external_identity": "Ext2",
"user_id": "IDPUser2@example.com"
},
{
"external_identity": "Ext3",
"user_id": "IDPUser2@example.com"
},
{
"external_identity": "Ext3",
"group_id": "IDPGroup1@example.com"
},
{
"external_identity": "Ext3",
"group_id": "IDPGroup2@example.com"
}
]
}
외부 ID가 하위 ID를 가지는 중첩 ID 멤버십은 반드시 평면화해야 합니다.
Google은 커넥터가 외부 ID에 대해 기본 ID를 전송한다고 가정합니다. 예를 들어 그룹 이름은 커스텀 애플리케이션에서 그룹이 존재하는 동안 변경될 수 있으므로, 그룹 이름이 아니라 그룹 ID를 가져와야 합니다.
ID 매핑 설정
IDP와 외부 ID 간의 ID 매핑을 Gemini Enterprise에서 설정하려면 다음 절차를 따르세요. 이어지는 단계에서 ID 매핑 스토어를 만들고, 미리 준비해 둔 ID 매핑을 가져옵니다. 커스텀 커넥터를 사용할 계획이라면, ID 매핑 스토어에 바인딩된 새 데이터 스토어도 함께 만듭니다.
ID 매핑 스토어 만들기
첫 번째 단계는 ID 매핑 스토어를 설정하는 것입니다. 이 스토어는 모든 ID 매핑이 저장되는 상위 리소스입니다.
ID 매핑 스토어를 만들면 Gemini Enterprise 프로젝트에 연결해 둔 IDP에서 IDP 구성을 자동으로 가져옵니다.
ID 매핑 저장소를 만들려면
identityMappingStores.create메서드를 사용하여 다음 명령어를 실행합니다.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?identityMappingStoreId=IDENTITY_MAPPING_STORE_ID" \ -d '{ "name": "projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID" }'다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.IDENTITY_MAPPING_STORE_ID: ID 매핑 스토어의 고유 ID입니다. 예를 들면test-id-mapping-store입니다.
ID 매핑 가져오기
ID 매핑 스토어를 만든 후 준비해 둔 ID 매핑 항목을 가져옵니다.
ID 매핑을 가져오려면
importIdentityMappings메서드를 사용하여 다음 명령어를 실행합니다.curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.IDENTITY_MAPPING_STORE_ID: ID 매핑 스토어의 고유 ID입니다.IDENTITY_MAPPINGS_JSON: JSON 형식으로 준비된 ID 매핑입니다.
다음으로, 커스텀 커넥터를 빌드하고 외부 ID를 사용할 계획이라면 ID 매핑 스토어에 커스텀 데이터 스토어 바인딩으로 이동합니다. 그렇지 않다면 ACL 메타데이터 업데이트로 건너뜁니다.
ID 매핑 스토어에 커스텀 데이터 스토어 바인딩
이 절차는 커스텀 커넥터를 빌드하는 경우에만 필요합니다. 커스텀 커넥터를 빌드하지 않는다면 이 단계를 건너뛰세요.
커스텀 커넥터의 경우 외부 ID를 문서에 연결할 수 있으려면 데이터 스토어 생성 시 ID 매핑 저장소를 해당 스토어에 바인딩해야 합니다. 이 필드는 데이터 스토어를 생성할 때만 설정할 수 있습니다.
데이터 스토어를 ID 매핑 스토어에 바인딩하려면
Datastores.create메서드를 사용해 데이터 스토어를 만들 때identity_mapping_store를 지정합니다.curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID \ -d '{ ... "identity_mapping_store": "IDENTITY_MAPPING_STORE_NAME" }'다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.DATA_STORE_ID: 만들려는 데이터 스토어의 ID입니다. 이 ID는 소문자, 숫자, 밑줄, 하이픈만 포함할 수 있습니다.IDENTITY_MAPPING_STORE_NAME: ID 매핑 스토어의 전체 리소스 이름입니다. 예를 들면projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store입니다. 데이터 스토어를 만든 후에는 이 이름을 업데이트할 수 없습니다.
ACL 메타데이터 추가
문서에 대해 ACL 메타데이터를 AclInfo 객체에 포함합니다.
사용자가 검색 요청을 보냈을 때, ACL 메타데이터에 외부 ID가 포함된 문서가 검색되면 해당 외부 ID가 평가됩니다.
사용자의 ID(groupID 또는 userID)가 문서에 연결된 외부 ID(externalEntityId)에 매핑되어 있다면, 사용자는 그 문서에 액세스할 수 있습니다.
예를 들어 Jira용 커스텀 커넥터를 만들었다고 가정해보겠습니다. 특정 Jira 문제는 일부 IDP 사용자, 일부 IDP 그룹, 그리고 관리자 역할이 액세스할 수 있습니다. 이러한 사용자들이 검색 결과에서 해당 문제에 액세스할 수 있도록 하려면, ID 매핑 스토어를 만들고 IDP 사용자와 그룹을 Jira 전용 외부 ID에 매핑합니다. 그리고 해당 ID 매핑 스토어를 Jira 데이터 스토어에 바인딩합니다. 이후 Jira 데이터 스토어에서 문서를 만들 때, 그 문서에 액세스해야 하는 IDP 사용자, IDP 그룹, 외부 ID를 aclInfo에 구성합니다.
외부 ID 정보를 포함하도록 ACL 메타데이터를 업데이트하려면 외부 ID와 연결된 사용자 및 그룹 ID를 지정하는 다음 형식을 사용합니다.
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
ACL 메타데이터 업데이트에 대한 자세한 내용은 액세스 제어가 포함된 데이터 소스 구성을 참조하세요.
ID 매핑 관리
ID 스토어에서 ID 매핑을 나열하거나, 인라인 소스를 사용하거나 필터 조건을 지정하여 ID 스토어를 정리할 수 있습니다.
ID 매핑에 대해 수행할 수 있는 관리 작업은 다음과 같습니다.
ID 매핑 나열
ID 매핑을 나열하려면
listIdentityMappings메서드를 사용해 다음 명령어를 실행합니다.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:listIdentityMappings?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.PAGE_SIZE: 반환할 ID 매핑 스토어의 최대 개수입니다. 지정하지 않으면 기본적으로 100입니다. 허용되는 최댓값은 1,000입니다. 1,000보다 큰 값은 1,000으로 조정됩니다.PAGE_TOKEN: 이전ListIdentityMappingStores호출에서 받은 페이지 토큰입니다. 이후 페이지를 가져오려면 이 값을 제공합니다.
인라인 소스를 사용하여 정리
정리할 ID를 포함한 JSON 파일을 제공하여, ID 매핑 스토어에서 지정된 항목을 정리할 수 있습니다.
인라인 소스를 사용해 ID 매핑을 정리하려면,
purgeIdentityMappings메서드로 다음 명령어를 실행합니다.curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.IDENTITY_MAPPING_STORE_ID: ID 매핑 스토어의 고유 ID입니다.IDENTITY_MAPPING_STORE_NAME: ID 매핑 스토어의 이름입니다.IDENTITY_MAPPINGS_JSON: 정리할 ID 매핑입니다.
필터 조건을 사용하여 정리
업데이트 시간, 외부 ID 또는 모든 항목을 기준으로 필터링하여, ID 매핑 스토어에서 특정 항목을 정리할 수 있습니다.
필터 조건을 사용해 ID 매핑을 정리하려면
purgeIdentityMappings메서드로 다음 명령어를 실행합니다.curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \ -d '{"identity_mapping_store":"IDENTITY_MAPPING_STORE_NAME", "filter": "FILTER_CONDITION"}'다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.IDENTITY_MAPPING_STORE_ID: ID 매핑 스토어의 고유 ID입니다.IDENTITY_MAPPING_STORE_NAME: ID 매핑 스토어의 이름입니다.FILTER_CONDITION: 다음 필터 유형 중 하나입니다.- 업데이트 시간. 예를 들면
update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z">입니다. - 외부 ID. 예를 들면
external_id = "id1"입니다. - 모든 ID 매핑. 예를 들면
*입니다.
ID 매핑 스토어 관리
ID 매핑 스토어에 대해 조회, 삭제, 나열, 정리 작업을 수행할 수 있습니다.
ID 매핑 스토어 조회
ID 매핑 스토어를 조회하려면
identityMappingStores.get메서드를 사용해 다음 명령어를 실행합니다.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.IDENTITY_MAPPING_STORE_ID: ID 매핑 스토어의 고유 ID입니다.IDENTITY_MAPPING_STORE_NAME: ID 매핑 스토어의 이름입니다.
ID 매핑 스토어 나열
ID 매핑 스토어를 나열하려면
identityMappingStores.list메서드를 사용해 다음 명령어를 실행합니다.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.PAGE_SIZE: 반환할 ID 매핑 스토어의 최대 개수입니다. 지정하지 않으면 기본적으로 100입니다. 허용되는 최댓값은 1,000입니다. 1,000보다 큰 값은 1,000으로 조정됩니다.PAGE_TOKEN: 이전ListIdentityMappingStores호출에서 받은 페이지 토큰입니다. 이후 페이지를 가져오려면 이 값을 제공합니다.
ID 매핑 스토어 삭제
ID 매핑 스토어를 삭제하려면 해당 스토어가 어떤 데이터 스토어에도 바인딩되어 있지 않아야 하며, ID 매핑 스토어 내부에 ID 매핑이 존재하지 않아야 합니다.
ID 매핑 스토어를 삭제하려면
identityMappingStores.delete메서드를 사용해 다음 명령어를 실행합니다.curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.IDENTITY_MAPPING_STORE_ID: ID 매핑 스토어의 고유 ID입니다.IDENTITY_MAPPING_STORE_NAME: ID 매핑 스토어의 이름입니다.