Cloud OAuth API로 사용자 정보 가져오기

이 가이드에서는 Cloud OAuth API(cloudoauth.googleapis.com)의 /userinfo 엔드포인트를 사용하여 인증된 직원 사용자의 OpenID Connect(OIDC) 표준 클레임, 커스텀 디렉터리 클레임, 그룹 멤버십을 검색하는 방법을 설명합니다.

시작하기 전에

  1. 직원 ID 풀 및 공급업체를 구성합니다. 자세한 내용은 직원 ID 제휴 구성을 참조하세요.
  2. OAuth 클라이언트를 등록하고 승인 코드를 액세스 토큰으로 교환합니다. 자세한 내용은 Cloud OAuth API로 토큰 교환을 참조하세요.
  3. 액세스 토큰에 openid 범위가 포함되어 있는지 확인합니다.

  4. Cloud OAuth API가 아직 사용 설정되지 않은 경우 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

    API 사용 설정하기

조직 범위 엔드포인트

Cloud OAuth API는 클라이언트 애플리케이션과 리소스가 특정Google Cloud 조직으로 제한된 경우 사용할 수 있는 조직 범위(단일 테넌트) 엔드포인트를 제공합니다.

Cloud OAuth API의 organizations.userinfo 메서드는 특정 조직의 인증된 사용자에 대한 OpenID Connect(OIDC) 표준 클레임, 커스텀 클레임, 그룹 멤버십을 검색합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • TOKEN: 토큰 교환 엔드포인트에서 가져온 수명이 짧은 OAuth 2.0 액세스 토큰입니다.
  • ORGANIZATION_ID: 숫자로 된 Google Cloud 조직 ID입니다.

HTTP 메서드 및 URL: 

GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/userinfo

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

SCIM 프로비저닝이 사용 설정되지 않은 직원 ID 풀의 경우 엔드포인트는 프로필 속성, 커스텀 클레임, 그룹 멤버십을 인라인으로 반환합니다.

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

사용자 클레임 및 SCIM 분산 그룹

요청이 성공하면 /userinfo 엔드포인트는 HTTP 200 OK 상태와 인증된 사용자의 클레임이 포함된 JSON 객체를 반환합니다.

클레임 형식은 직원 ID 풀 공급업체에서 SCIM 프로비저닝을 사용하는지 여부에 따라 달라집니다.

인라인 클레임(비SCIM ID 풀)

SCIM 프로비저닝이 사용 설정되지 않은 직원 ID 풀의 경우 엔드포인트는 프로필 속성, 커스텀 클레임, 그룹 멤버십을 인라인으로 반환합니다.

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

분산 클레임(SCIM 지원 ID 풀)

SCIM 프로비저닝이 사용 설정된 직원 ID 풀의 경우 그룹 멤버십이 분산 클레임으로 반환됩니다. 응답에는 /groups 엔드포인트를 참조하는 _claim_names 및 _claim_sources가 포함됩니다.

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "name": "Jane Doe",
  "email": "user@example.com",
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://cloudoauth.googleapis.com/v1/common/groups"
    }
  }
}

클레임 필드

응답에는 다음과 같은 표준 및 분산 클레임 필드가 포함됩니다.

필드 유형 설명
sub string 직원 ID 풀에서 인증된 사용자의 고유 주 구성원 식별자입니다.
name string 사용자의 성명입니다(ID 공급업체에서 제공하는 경우).
email string 인증된 사용자의 이메일 주소입니다.
groups array of strings (SCIM이 아닌 경우에만 해당) 사용자의 엔터프라이즈 그룹 멤버십 목록입니다.
_claim_names object (SCIM 사용 설정된 경우에만 해당) 분산 클레임 이름(예: groups)을 _claim_sources의 소스 식별자에 매핑하는 JSON 객체입니다.
_claim_sources object (SCIM 사용 설정된 경우에만 해당) 각 분산 클레임 식별자의 소스 엔드포인트를 정의하는 JSON 객체입니다.

/userinfo 엔드포인트에서 반환하는 오류 응답에 대한 자세한 내용은 Cloud OAuth 사용자 정보 및 그룹 오류를 참조하세요.

다음 단계