Cloud OAuth API로 토큰 교환

이 가이드에서는 직원 ID 제휴 통합에서 Cloud OAuth API(cloudoauth.googleapis.com)를 사용하여 외부 사용자 인증 정보, 승인 코드 또는 갱신 토큰을 Google Cloud 액세스 토큰으로 교환하는 방법을 설명합니다.

시작하기 전에

  1. 직원 아이덴티티 풀 및 공급업체를 구성합니다. 자세한 내용은 직원 ID 제휴 구성을 참고하세요.
  2. OAuth 클라이언트를 등록하고 클라이언트 사용자 인증 정보를 만듭니다. 자세한 내용은 OAuth 애플리케이션 관리를 참고하세요.

  3. Cloud OAuth API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

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

    API 사용 설정하기

인증 방식

Cloud OAuth API는 다음 두 가지 클라이언트 인증 방법을 지원합니다.

  • HTTP 기본 인증 (권장): Base64로 인코딩된 클라이언트 ID와 클라이언트 보안 비밀번호를 Authorization 헤더에 전달합니다.

    -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)"

  • 요청 본문 매개변수: 요청 본문에서 client_id 및 client_secret 매개변수를 전달합니다.

승인 코드를 토큰으로 교환

액세스 토큰과 갱신 토큰을 Google Cloud 승인 코드로 교환하려면 HTTP POST 요청을 전송하세요.

  • 조직 범위 (단일 테넌트) 엔드포인트

    curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=AUTHORIZATION_CODE" \
--data-urlencode "redirect_uri=REDIRECT_URI"

    요청 본문 사용자 인증 정보

    curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=AUTHORIZATION_CODE" \
--data-urlencode "redirect_uri=REDIRECT_URI" \
--data-urlencode "client_id=CLIENT_ID" \
--data-urlencode "client_secret=CLIENT_SECRET"

다음을 바꿉니다.

  • BASE64_ENCODED_CREDENTIALS: CLIENT_ID:CLIENT_SECRET의 Base64 인코딩 문자열입니다.
  • AUTHORIZATION_CODE:Google Cloud에서 발급한 승인 코드입니다.
  • REDIRECT_URI: OAuth 클라이언트에서 구성된 리디렉션 URI입니다.
  • ORGANIZATION_ID: 숫자로 된 Google Cloud조직 ID입니다.
  • CLIENT_ID: 등록된 OAuth 클라이언트 ID입니다.
  • CLIENT_SECRET: OAuth 클라이언트 보안 비밀번호입니다.

액세스 토큰 새로고침

액세스 토큰이 만료되면 refresh_token 부여 유형을 사용하여 수명이 짧은 새 액세스 토큰을 가져옵니다.

  • 조직 범위 (단일 테넌트) 엔드포인트

    curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=REFRESH_TOKEN" \
--data-urlencode "redirect_uri=REDIRECT_URI"

REFRESH_TOKEN을 토큰 엔드포인트가 이전에 반환한 갱신 토큰으로 바꿉니다.

토큰 응답 필드

토큰 교환이 성공하면 Cloud OAuth API는 다음 필드가 포함된 HTTP 200 OK 상태를 반환합니다.

필드 유형 설명
access_token string Google Cloud API를 호출하기 위해 Cloud OAuth API에서 발급한 OAuth 2.0 액세스 토큰입니다.
refresh_token string 현재 토큰이 만료될 때 새 액세스 토큰을 가져오는 데 사용되는 갱신 토큰입니다.
expires_in integer 액세스 토큰의 남은 수명(초)(일반적으로 3599)입니다.
token_type string 토큰 유형입니다 (예: Bearer).
scope string 토큰과 연결된 범위 목록입니다.
id_token string 인증된 ID 클레임이 포함된 OIDC ID 토큰입니다.

Cloud OAuth API에서 반환되는 오류 응답에 대한 자세한 내용은 Cloud OAuth API 토큰 교환 오류를 참고하세요.

다음 단계