Google 인증 확장 프로그램

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동
정보

버전: 1.0.2

지정한 Google API에 액세스하려면 Google에 인증합니다.

이 확장 프로그램을 사용하여 Google Cloud 서비스에 대한 토큰 (OAuth 또는 JWT)을 가져온 다음 Service콜아웃 정책을 사용하는 등의 방법으로 Google API에 대한 후속 호출에 이 토큰을 사용할 수 있습니다.

예를 들어 API 프록시에서 이 확장 프로그램을 사용하여 토큰을 가져오고 PopulateCache 정책을 사용하여 토큰을 캐시한 다음 ServiceCall 정책을 통해 토큰을 전달하여 API 프록시 흐름 내에서 Google Cloud 서비스에 액세스할 수 있습니다.

기본 요건

이 콘텐츠는 이 확장 프로그램을 구성하고 사용하기 위한 참조를 제공합니다. Extension콜아웃 정책을 사용하여 API 프록시의 확장 프로그램을 사용하려면 다음 요건을 충족해야 합니다.

  1. 확장 프로그램이 사용할 계정(사용자 인증 정보에 사용할 서비스 계정으로 표시되는 계정)에 확장 프로그램이 인증할 Google Cloud 서비스에 대한 액세스 권한이 있는지 확인합니다.

  2. Google Cloud 콘솔을 사용하여 서비스 계정의 키를 생성합니다.

  3. 구성 참조를 사용하여 확장 프로그램을 추가 및 구성할 때 생성된 서비스 계정 키 JSON 파일의 콘텐츠를 사용합니다.

Google Cloud 인증 정보

이 확장 프로그램은 Google Cloud 프로젝트에 정의된 특정 구성원을 나타내는 방식으로 Google Cloud의 인증을 요청합니다. 이 확장 프로그램을 구성할 때 프로젝트 구성원의 서비스 계정 JSON 파일을 사용합니다.

따라서 이 확장 프로그램은 해당 구성원이 권한을 가진 리소스에만 액세스할 수 있습니다. 즉, 이 확장 프로그램의 성공적인 인증은 Google Cloud 콘솔에서 부여된 권한과 런타임 시 확장 프로그램에서 요청한 액세스 권한 (범위 또는 잠재고객 사용) 간의 일치 여부에 따라 달라집니다.

일반적으로 이 확장 프로그램에서 API에 액세스하기 위해 인증하는 단계는 다음과 같습니다.

  1. 이 확장 프로그램이 나타내는 구성원 서비스 계정에 액세스하려는 Google 리소스에 대한 액세스 권한이 있는지 확인하세요. Google Cloud 콘솔의 Cloud Identity and Access Management (Cloud IAM) 페이지를 사용하여 이 확장 프로그램이 나타내는 프로젝트 구성원에게 역할을 부여할 수 있습니다.

  2. 이 확장 프로그램을 구성할 때 해당 구성원의 서비스 계정 키 JSON을 사용하세요.

  3. 이 확장 프로그램을 사용하도록 Extension콜아웃 정책을 구성할 때 프로젝트 구성원이 액세스할 수 있는 리소스에 대해서만 인증을 요청하세요.

샘플

다음 예시는 ExtensionCall 정책을 사용하여 Google Cloud에 인증하는 방법을 보여줍니다.

액세스 토큰 가져오기

다음 예에서 확장 프로그램의 getOauth2AccessToken 작업은 Cloud Translation API 요청에 사용할 토큰을 검색합니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-Access-Token">
    <DisplayName>Get Access Token</DisplayName>
    <Connector>google-auth</Connector>
    <Action>getOauth2AccessToken</Action>
    <Input><![CDATA[{
      "scope" : [
        "https://www.googleapis.com/auth/cloud-translation"
      ]
    }]]></Input>
    <Output>google.credentials</Output>
</ConnectorCallout>

응답 값은 다음과 같습니다.

{
  "access_token":"ya29.c.ElpSB...BMgkALBJ0kou-8",
  "token_type":"Bearer",
  "expiresInSec": 3600
}

다음 AssignMessage 정책은 위의 ExtensionCall 정책에서 응답 값을 가져와서 응답 페이로드에 복사합니다. 이는 디버깅에 유용할 수 있습니다. 실제로는 클라이언트에 토큰을 반환하지 않는 것이 좋습니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Retrieve-Auth-Token">
    <DisplayName>Retrieve Auth Token</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{google.credentials.access_token}</Payload>
    </Set>
</AssignMessage>

액세스 토큰 캐시

토큰을 가져오기 위해 불필요한 호출을 피하려면 수신한 토큰을 캐시하는 것이 좋습니다. 토큰이 필요한 후속 호출의 경우 Apigee Edge 캐시에서 토큰을 가져오는 것이 새 토큰을 가져오는 것보다 빠릅니다. 캐시된 토큰이 만료되면 새 토큰을 검색하고 캐시를 새로고침합니다.

API 프록시 예의 다음 코드는 캐시된 토큰을 설정하고 사용하여 ServiceCallout 정책을 통해 Google Translation API를 호출하는 방법을 보여줍니다. 여기에 있는 각 코드 예시는 흐름의 각기 다른 정책을 위한 것입니다.

다음 정책은 다음 흐름 XML에 설명된 순서대로 실행됩니다.

  <Request>
    <!-- Attempt to get a token from the cache. -->
    <Step>
        <Name>Get-Cached-Auth-Token</Name>
    </Step>
    <!-- Only execute the following ExtensionCallout policy if the call to the
      cache couldn't retrieve a cached token. -->
    <Step>
        <Name>Google-Auth-Callout</Name>
        <Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
    </Step>
    <!-- Only execute the following PopulateCache policy if the call to the
      cache couldn't retrieve a cached token. -->
    <Step>
        <Name>Cache-Auth-Token</Name>
        <Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
    </Step>
    <!-- Use the ServiceCallout policy to call the translate API. -->
    <Step>
        <Name>Translate-Text</Name>
    </Step>
</Request>
  1. 다음 LookupCache 정책은 캐시에서 토큰을 가져오려고 시도합니다. 토큰을 이미 가져와 캐시한 경우 이 정책은 토큰을 API 프록시에서 사용하도록 가져옵니다.

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <LookupCache async="false" continueOnError="false" enabled="true" name="Get-Cached-Auth-Token">
          <DisplayName>Get Cached Auth Token</DisplayName>
          <!-- Give cache key and scope to specify the entry for the cached token. -->
          <CacheKey>
              <Prefix/>
              <KeyFragment>gcp_translate_token_</KeyFragment>
          </CacheKey>
          <Scope>Exclusive</Scope>
          <!-- Assign the retrieved token (if any) to a variable, where it
           can be retrieved by policies. -->
          <AssignTo>cloud.translation.auth.token</AssignTo>
      </LookupCache>
    
  2. 캐시 조회 시 캐시된 토큰이 검색되지 않으면 다음 ExtensionCall 정책은 Google Cloud Translation API를 토큰의 범위로 지정하여 새 OAuth 토큰을 가져옵니다. Google-Auth-Callout 확장 프로그램을 구성할 때 사용된 서비스 계정 사용자 인증 정보가 API에 액세스할 수 있는 프로젝트 구성원을 나타내는 경우 Google Cloud는 유효한 토큰을 반환합니다.

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Google-Auth-Callout">
          <DisplayName>Google-Auth-Callout</DisplayName>
          <Connector>example-auth-extension</Connector>
          <Action>getOauth2AccessToken</Action>
          <Input><![CDATA[{
            "scope" : ["https://www.googleapis.com/auth/cloud-translation"]
          }]]></Input>
          <Output parsed="false">cloud.translation.auth.token</Output>
      </ConnectorCallout>
    
  3. 확장 콜아웃 정책이 새 토큰을 가져오면 PopulateCache 정책에서 나중에 API 프록시의 정책에서 사용할 수 있도록 이 토큰을 캐시합니다.

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <PopulateCache async="false" continueOnError="false" enabled="true" name="Cache-Auth-Token">
          <DisplayName>Cache Auth Token</DisplayName>
          <Properties/>
          <!-- Set cache key information to specify a unique key for this entry. -->
          <CacheKey>
              <Prefix/>
              <KeyFragment>gcp_translate_token_</KeyFragment>
          </CacheKey>
          <Scope>Exclusive</Scope>
          <ExpirySettings>
              <TimeoutInSec>5</TimeoutInSec>
          </ExpirySettings>
          <!-- Get the token to cache from the variable where the ExtensionCallout put it. -->
          <Source>cloud.translation.auth.token</Source>
      </PopulateCache>
    

작업

getOauth2AccessToken

OAuth 2.0 액세스 토큰을 가져옵니다. Google API에 OAuth 토큰이 필요할 때 이 작업을 사용하여 API 프록시와 Google API 간에 two-legged OAuth를 지원합니다.

Two-legged OAuth에서 이 확장 프로그램 작업은 서비스 계정 JSON (확장 프로그램을 구성할 때 해당 JSON을 추가)으로 Google에 인증하여 OAuth 토큰을 가져옵니다. 이 작업에서 OAuth 토큰을 가져오면 API 프록시에서 이 토큰을 사용하여 Google API를 호출하고 Google 서비스 계정 대신 API를 효과적으로 호출할 수 있습니다.

Google Cloud API에 대한 액세스는 Google API용 OAuth 2.0 범위에 나열된 범위를 통해 필터링됩니다.

OAuth 2.0과의 서버 간 상호작용에 대한 자세한 내용은 서버 간 애플리케이션에 OAuth 2.0 사용하기를 참고하세요.

문법

<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
  "scope" : [
    "scope1",
    "scope2"
  ]
}]]></Input>

다음 예에서 확장 프로그램의 getOauth2AccessToken 작업은 Cloud Translation API 요청에 사용할 토큰을 검색합니다.

<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
    "scope" : [
      "https://www.googleapis.com/auth/cloud-translation"
  ]
}]]></Input>

요청 매개변수

매개변수 설명 유형 기본 계정 필수
범위 OAuth 2.0 범위의 배열입니다. 범위에 관한 자세한 내용은 Google API용 OAuth 2.0 범위를 참고하세요. 배열 ["https://www.googleapis.com/auth/cloud-platform"] - 서비스 계정이 액세스 권한을 보유한 모든 API에 대한 액세스 권한을 부여합니다. 번호

응답

액세스 토큰, 유형, 다음 형식의 만료일을 포함하는 객체입니다.

{
  "accessToken": "ewogICJ0eXB...C5jb20iCn0K",
  "token_type": "Bearer",
  "expiresInSec": 3600
}

응답 속성

매개변수 설명 기본 계정 필수
accessToken OAuth 2.0 액세스 토큰입니다. 없음 지원됨
tokenType 토큰 유형입니다. Bearer 지원됨
expiresInSec 토큰 만료까지 남은 시간(초)입니다. 3600 지원됨

getJWTAccessToken

JSON 웹 토큰 (JWT) 액세스 토큰을 가져옵니다. 호출하려는 API에 Google API GitHub 저장소에 게시된 서비스 정의가 있는 경우 이 토큰을 사용하여 Google API로 인증할 수 있습니다.

일부 Google API에서는 OAuth 2.0 액세스 토큰이 아닌 서명된 JWT를 Bearer 토큰으로 직접 사용하여 승인된 API 호출을 수행할 수 있습니다. 이 경우 API 호출 전에 Google 인증 서버에 네트워크 요청을 하지 않아도 됩니다.

JWT 액세스 토큰으로 인증하는 방법에 대한 자세한 내용은 서버 간 애플리케이션에 OAuth 2.0 사용하기를 참고하세요.

문법

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
    "audience" : "audience"
}]]></Input>

예: Cloud 함수 URL

다음 예에서 확장 프로그램의 getOauth2AccessToken 작업은 Cloud Translation API 요청에 사용할 토큰을 검색합니다.

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/FUNCTION_NAME"
}]]></Input>

예: Cloud IAP 보안 클라이언트 ID

다음 예에서 확장 프로그램의 getOauth2AccessToken 작업은 Cloud Translation API 요청에 사용할 토큰을 검색합니다.

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "Cloud-IAP-secured-client-ID"
}]]></Input>

요청 매개변수

매개변수 설명 기본 계정 필수
audience 토큰의 의도된 수신자입니다. 여기에는 Cloud IAP 보안 클라이언트 ID, Cloud Functions URL 등이 포함될 수 있습니다. 없음 지원됨

응답

{
  "accessToken": "token",
  "tokenType": "Bearer",
  "expiresInSec": 3600
}

응답 속성

매개변수 설명 기본 계정 필수
accessToken 액세스 토큰입니다. 없음 지원됨
tokenType 토큰 유형입니다. Bearer 지원됨
expiresInSec 만료 기한은 초입니다. 3600 지원됨

구성 참조

API 프록시에서 사용할 이 확장 프로그램을 구성하고 배포할 때 다음을 사용하세요. Apigee 콘솔을 사용하여 확장 프로그램을 구성하는 단계는 확장 프로그램 추가 및 구성을 참조하세요.

일반적인 확장 속성

모든 확장 프로그램에는 다음과 같은 속성이 있습니다.

속성 설명 기본 필수
name 확장 프로그램의 구성에 지정할 이름입니다. 없음 지원됨
packageName Apigee Edge에서 제공하는 확장 프로그램 패키지 이름입니다. 없음 지원됨
version 확장 프로그램을 구성하는 확장 프로그램 패키지의 버전 번호입니다. 없음 지원됨
configuration 추가하는 확장 프로그램 관련 구성 값입니다. 이 확장 프로그램 속성의 속성을 참조하세요. 없음 지원됨

이 확장 프로그램 패키지의 속성

이 확장 프로그램에 해당하는 다음 구성 속성의 값을 지정합니다.

속성 설명 기본 계정 필수
사용자 인증 정보 Apigee Edge 콘솔에 입력하면 서비스 계정 키 JSON 파일의 전체 콘텐츠가 표시됩니다. 관리 API를 통해 전송될 때 이 값은 전체 서비스 계정 키 JSON 파일에서 생성된 base64로 인코딩된 값입니다. 없음 지원됨