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

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

시작하기 전에

  1. 직원 아이덴티티 풀 및 공급업체를 구성합니다. 자세한 내용은 직원 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 사용자 정보 및 그룹 오류를 참고하세요.

다음 단계