커스텀 대상(서비스)

이 페이지에서는 승인에 커스텀 대상을 사용하는 방법을 설명합니다.

Identity and Access Management로 보호되는 Cloud Run 서비스를 호출하는 클라이언트는 수신 서비스의 *.run.app URL과 일치하는 대상 클레임이 포함된 유효한 ID 토큰을 제공해야 합니다. 이 URL을 모르는 클라이언트의 경우 커스텀 대상 값을 사용하면 됩니다.

커스텀 대상 이해

Cloud Run은 IAM으로 액세스 제어를 지원하는 호출자(roles/run.invoker) 역할을 제공합니다. IAM 액세스 제어는 JSON 웹 토큰(JWT)으로 패키징된 Google 서명 ID 토큰을 사용합니다. 이러한 토큰의 콘텐츠는 OIDC 표준을 준수합니다.

대상 필드는 토큰을 사용할 수 있는 의도된 타겟을 지정하기 위해 토큰에 인코딩됩니다. 이렇게 하면 한 서비스에 사용하도록 의도된 가로채인 토큰이 다른 서비스에서 재실행되는 재생 공격의 위험이 제한됩니다.

규칙에 따라 이 대상은 타겟 서비스의 전체 URL입니다. 기본적으로 Cloud Run에서 run.app으로 끝나는 서비스의 Google 생성 URL입니다.

그러나 다음 시나리오와 같이 Cloud Run 서비스는 기본 생성된 URL이 아닌 URL 뒤에 있을 수 있습니다.

클라이언트가 Google에서 생성한 URL을 인식하지 못하는 서비스에 연결하기 위해 커스텀 도메인을 사용하는 경우
클라이언트에서 요청이 도달할 리전 서비스를 예측할 수 없는 부하 분산기 뒤에서 여러 서비스를 배포하는 경우. Google에서 생성한 서비스 URL은 서비스 이름이 동일하더라도 리전에 따라 달라집니다.

이러한 시나리오에서는 클라이언트가 알고 있는 추가 타겟을 허용하는 커스텀 대상 값을 허용하도록 서비스를 구성해야 합니다. Google에서 생성한 기본 URL은 항상 허용되는 대상 값으로 유지됩니다.

커스텀 대상 설정 및 업데이트

Cloud Run의 커스텀 대상 설정은 서비스 수준에서 수행되며 IAM 승인 멤버십과 마찬가지로 모든 제공 버전에 적용됩니다.

대상의 JSON 인코딩이 문자열 목록으로 32,768자를 초과하지 않는 한 여러 커스텀 대상을 설정할 수 있습니다.

구성을 변경하면 새 버전이 생성됩니다. 이를 변경하는 명시적 업데이트가 없으면 이후 버전에도 이 구성 설정이 자동으로 적용됩니다.

명령줄

다음 명령어를 사용하여 서비스에 커스텀 대상을 설정할 수 있습니다.

gcloud run services update SERVICE --add-custom-audiences=AUDIENCE

바꾸기

SERVICE를 Cloud Run 서비스 이름으로 바꿉니다.
AUDIENCE를 지원하려는 커스텀 대상의 문자열로 바꿉니다(예: myservice 또는 https://myservice.example.com).

다음 명령어를 사용하여 서비스에서 모든 커스텀 대상을 삭제할 수 있습니다.

gcloud run services update SERVICE --clear-custom-audiences

YAML

YAML 형식으로 정리된 결과를 생성하는 gcloud run services describe --format export 명령어를 사용하면 기존 서비스 구성을 다운로드해서 볼 수 있습니다. 그런 다음 아래 설명된 필드를 수정하고 gcloud run services replace 명령어를 사용하여 수정된 YAML을 업로드할 수 있습니다. 설명된 대로 필드만 수정해야 합니다.

구성을 보고 다운로드하려면 다음을 실행합니다.

gcloud run services describe SERVICE --format export > service.yaml

서비스 메타데이터(template 메타데이터가 아님)에서 run.googleapis.com/custom-audiences 주석을 설정합니다:googledata/devsite/site-cloud/en/run/docs/authenticating/service-to-service.md
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE"]'
spec:
  template:
    ...
```
바꾸기
- SERVICE를 Cloud Run 서비스 이름으로 바꿉니다.
- AUDIENCE를 지원하려는 커스텀 대상의 문자열로 바꿉니다(예: myservice 또는 https://myservice.example.com).
속성 값은 큰따옴표와 작은따옴표를 모두 사용해야 하는 따옴표로 묶인 문자열의 JSON 배열입니다.
다음 명령어를 사용하여 작업을 새 구성으로 바꿉니다.
```
gcloud run services replace service.yaml
```

커스텀 대상 확인

서비스를 호출할 수 있는 IAM 권한이 있는 서비스 계정의 ID 토큰을 가져옵니다. 커스텀 대상 AUDIENCE를 사용한다는 점에 유의하세요.
```
export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')
```
다음과 같이 바꿉니다.
- SERVICE_ACCOUNT_EMAIL을 서비스 계정의 이메일로 바꿉니다. .iam.gserviceaccount.com으로 끝납니다.
- AUDIENCE를 서비스에 설정한 커스텀 대상 값으로 바꿉니다.
해당 ID 토큰으로 서비스의 엔드포인트를 호출합니다.
```
curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT
```
ENDPOINT를 서비스에 연결할 엔드포인트(예: 커스텀 도메인 또는 .run.app URL)로 바꿉니다.
요청이 승인되었고 서비스의 예상 응답이 표시되는지 확인합니다.