IAM 기반 API 인증 개요

이 페이지는 Apigee에 적용되지만 Apigee Hybrid에는 적용되지 않습니다.

Apigee는 API 프록시의 IAM 기반 인증 및 승인을 지원합니다. 이 솔루션을 사용하면 API 호출에 대한 액세스는 요청 흐름에 VerifyIAM 정책이 포함되어 있는지, API 소비자에게 Apigee API를 호출하는 데 필요한 Google Cloud IAM 역할 또는 권한이 있는지 등 여러 요소를 기반으로 합니다. 승인은 모든 Google Cloud 주 구성원에게 부여할 수 있으며 개별 사용자로 제한되지 않습니다.

IAM 기반 액세스 제어 사용

이 섹션에서는 IAM 기반 인증 및 승인 설정을 위한 엔드 투 엔드 프로세스, 액세스가 설정된 후 요청이 평가되는 방식, 이전에 액세스 권한이 있었던 API 소비자의 액세스 권한을 취소하는 방법을 설명합니다.

액세스 관리 추가

API 프록시의 액세스 관리를 설정하려면 다음 단계를 따르세요.

요청 흐름의 일부로 Apigee API 프록시 또는 프록시에 VerifyIAM 정책을 추가합니다.
Apigee 프로젝트의 Cloud 관리자:
1. 프로젝트 수준에서 API 소비자의 Google Cloud 주 구성원에게 deploymentInvoker IAM 역할(또는 apigee.deployments.invoke IAM 권한이 있는 커스텀 역할)을 부여합니다. 이렇게 하면 연결된 Apigee 조직에서 호스팅된 모든 API를 호출할 수 있는 API 소비자 액세스 권한이 부여됩니다.
  
  또는
2. SetIamPolicy 작업을 사용하여 특정 배포에서 또는 여러 배포에서 반복적으로 API 소비자의 Google Cloud 원칙에 역할 또는 권한을 부여합니다. 배포 리소스의 작업 나열을 사용하여 API 프록시와 공유 흐름을 모두 포함한 환경 내의 모든 배포를 확인합니다. 배포 이름은 API 프록시 또는 공유 흐름의 이름입니다.
  참고: 공유 흐름 배포에 역할 또는 권한을 추가해도 공유 흐름에 VerifyIAM 정책 검사가 생성되지는 않습니다. 권한은 프록시에만 적용됩니다. 공유 흐름을 호출하는 프록시의 경우 권한이 프록시에 적용되어야 합니다. 프록시 체이닝을 사용하여 정책이 있는 프록시에 권한을 부여합니다. 체인의 다른 프록시에는 권한이 필요하지 않습니다.
API 소비자에게 액세스 토큰을 생성하도록 안내합니다. 이 토큰은 권한 확인을 위해 Apigee API 요청 내에서 전달됩니다. 생성된 토큰에는 https://www.googleapis.com/auth/cloud-platform 인증 범위가 있어야 합니다.

관리 작업

이 섹션에는 API 관리자(API 프로듀서)가 IAM 기반 권한을 관리할 때 취하는 작업이 나와 있습니다.

IAM 기반 액세스를 관리할 때 사용되는 API 기반 작업에 관한 문서는 organizations.environments 및 organizations.environments.deployments API 참조 문서에 있으며 SetIamPolicy, GetIamPolicy, TestIamPermissions, GetDeployment 작업을 포함합니다.

다음 테이블은 작업을 필요한 권한에 매핑합니다.

관리 작업	작업	필요한 IAM 권한	권한이 필요한 IAM 리소스^*
GetDeployment	Apigee 환경에서 배포에 대한 정보 검색	apigee.deployments.get	Google Cloud 프로젝트 또는 Apigee 환경
ListDeployments	Apigee 환경에서 배포 나열	apigee.deployments.list	프로젝트 또는 Apigee 환경
SetIamPolicy	특정 API 배포에서 API 소비자의 호출 액세스 설정	apigee.deployments.setIamPolicy	Google Cloud 프로젝트 또는 Apigee 환경
GetIamPolicy	API 배포의 호출 액세스 설정 집합 가져오기	apigee.deployments.getIamPolicy	Google Cloud 프로젝트 또는 Apigee 환경
TestIamPermissions	이 API를 호출하는 사용자에게 페이로드에 언급된 권한이 있는지 확인	IAM 권한 필요 없음	해당 사항 없음

^* Google Cloud 프로젝트는 Apigee를 프로비저닝하는 데 사용되는 프로젝트입니다. Apigee 환경 수준 권한은 setIAMPolicy를 사용하여 환경에 설정됩니다.

런타임 액세스 확인

API 소비자가 IAM 기반 액세스 제어로 API에 액세스하려고 하면 프로젝트 또는 배포 수준에서 필요한 액세스 토큰과 적절한 역할 또는 권한이 있는지 확인하는 검사가 실행됩니다. 이 경우 프록시에 계속 액세스할 수 있습니다. 그렇지 않으면 차단됩니다.

액세스 권한 삭제

프로젝트 수준에서 액세스 권한 삭제: 프로젝트 수준에서 관리되는 API 소비자의 액세스 권한을 삭제하려면 Apigee 프로젝트의 Cloud 관리자는 Google Cloud 프로젝트에 대한 API 소비자의 Google Cloud 주 구성원에서 deploymentInvoker IAM 역할(또는 apigee.deployments.invoke IAM 권한이 있는 커스텀 역할)을 취소합니다.

setIamPolicy를 사용하여 개별 배포에 액세스 권한이 부여된 경우 다른 setIamPolicy 작업을 사용하여 배포에서 역할 또는 권한을 삭제합니다.

IAM 기반 액세스 제어의 특성 및 제한사항

IAM 기반 인증 및 승인을 사용할 때는 다음과 같은 특성 및 제한사항에 유의하세요.

일반적으로 VerifyIAM을 사용한 정책 실행에는 약 10밀리초가 소요됩니다. 그러나 일부 호출에는 완료 지연 시간이 약 50ms가 발생할 수 있습니다. 예를 들어 asia-east2 리전에서는 평균 지연 시간이 50ms까지 증가할 수 있으며 일부 호출은 완료하는 데 약 100ms가 걸릴 수 있습니다.

이러한 지연 시간 수치는 보장되지 않습니다.
프록시에 VerifyIAM 정책을 포함하는 것은 인증됨/인증되지 않음 검사만 수행합니다. API 소비자의 특정 역할 및 권한은 요청 또는 응답 흐름의 후속 프로세스에서 고려되지 않습니다.
승인 확인은 VerifyIAM 정책 실행 시점에만 실행되므로 VerifyIAM은 트래픽 관리 정책 다음으로 요청 흐름에서 첫 번째 정책이어야 합니다.
권한 유효성 검사에 성공하거나 API 프로듀서가 VerifyIAM 정책을 오류 발생 시 계속 실행하도록 표시한 경우 요청 흐름은 다른 정책(있는 경우)을 계속 실행하여 궁극적으로 대상 서버에 도달합니다. 권한 검사에 실패하고 API 프로듀서가 정책을 오류 발생 시 계속 진행하도록 표시하지 않은 경우 사용자에게 오류가 표시됩니다.
환경 수준에서 호출 액세스(apigee.deployments.invoke)를 추가해도 환경 내 모든 API 배포에 호출 액세스가 전달되지는 않습니다.
IAM 조건은 배포 리소스에서 지원되지 않으며 호출 액세스를 제어하는 데 사용할 수 없습니다. 자세한 내용은 정책에 Apigee IAM 조건 추가를 참조하세요.
IAM 기반 액세스 제어는 단일 정책 내에서 최대 1,500개의 역할 바인딩과 기타 제한사항을 지원합니다. IAM 할당량 및 한도를 참조하세요.
IAM 기반 액세스 제어에는 IAM 적용 지연이 적용됩니다.
배포 수준 setIAMPolicy를 통해 apigee.deployments.delete과 같은 다른 apigee.deployments 작업을 관리하려고 하면 효과가 없지만 오류가 반환되지도 않습니다. apigee.deployements.invoke만 유효합니다.
상응하는 프록시가 환경에서 배포 해제되거나 삭제되면 배포의 액세스 권한이 삭제됩니다. 액세스 권한은 재배포 시 다시 추가해야 합니다.
현재 하이브리드에서는 IAM 기반 인증 및 승인을 사용할 수 없습니다.

예시

이 섹션에서는 API에 대한 IAM 기반 액세스 권한을 부여하고 취소하는 예시를 제공합니다. 이러한 예시에서는 모두 VerifyIAM이 이미 적절한 API 프록시에 추가되었다고 가정합니다.

이 예시에서는 Cloud 콘솔 또는 gcloud(표시됨)를 사용하여 API 소비자의 Google Cloud 주 구성원에서 역할 또는 권한을 관리합니다. 예시의 $Project는 Google Cloud 프로젝트입니다.

Apigee 조직에서 모든 API를 호출할 수 있는 사용자 액세스 권한 부여 및 취소

액세스 권한을 추가하려면 deploymentInvoker 역할을 추가합니다.

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

액세스 권한을 취소하려면 deploymentInvoker 역할을 삭제합니다.

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

환경 내 특정 배포에 대한 사용자 액세스 권한 부여 및 취소

특정 배포에 사용자의 호출자 역할을 추가하려면 다음 단계를 따르세요.

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
    --header 'Authorization: Bearer $TOKEN ' \
    --header 'Content-Type: application/json' \
    --data '{"policy":{"bindings":[{"members":["user:$user"],"role":"roles/apigee.deploymentInvoker"}]}}'

성공 응답은 다음과 같이 표시됩니다.

  {
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

추가한 정책 객체가 올바르게 유지되는지 확인하려면 다음 단계를 따르세요(선택사항).

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

위와 같은 성공 응답이 표시됩니다.

사용자가 지정된 배포에 액세스할 수 있는지(지정된 배포에서 지정된 사용자에게 apigee.deployments.invoke 권한이 설정되어 있는지) 확인할 수 있도록, 사용자가 이전에 생성한 액세스 토큰을 사용하여 이 요청을 제출하도록 안내합니다.

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

응답에는 사용자의 apigee.deployments.invoke 권한이 포함되어야 합니다.

특정 배포에서 액세스 권한을 취소하려면 deploymentInvoker 역할을 삭제합니다. 먼저 현재 배포와 연결된 정책 객체를 가져옵니다.

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

성공 응답은 다음 출력과 같이 표시됩니다. 다른 바인딩도 표시될 수 있습니다.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

바인딩을 삭제하려면 다음 단계를 따르세요.

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

빈 페이로드를 제공하면 모든 사용자의 액세스 권한이 삭제되지만, 이 예시에서는 액세스 권한이 있는 사용자가 한 명뿐이므로 적절합니다. 다른 사용자의 액세스가 계속되어야 하는 상황에서 사용자 액세스 권한을 삭제할 때는 해당 사용자의 초기 액세스 권한을 설정할 때와 마찬가지로 페이로드에서 계속 액세스 권한을 가져야 하는 사용자를 지정합니다.

바인딩이 삭제되었는지 확인하려면 배포에서 사용자에게 apigee.deployments.invoke 권한이 없는지 확인합니다.

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

권한이 있는 사용자가 없으면 빈 출력이 반환됩니다.