커스텀 대상(서비스)

이 페이지에서는 승인에 커스텀 대상을 사용하는 방법을 설명합니다. 공개(인증되지 않은) 액세스를 허용하지 않고 커스텀 도메인을 통해 요청을 수신하는 Cloud Run 서비스에서 커스텀 대상을 설정합니다.

커스텀 대상 이해

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 beta run services update SERVICE --add-custom-audiences=AUDIENCE

바꾸기

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

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

gcloud beta 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 주석을 설정합니다.
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE","AUDIENCE2"]'
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    ...
```
바꾸기
- SERVICE를 Cloud Run 서비스 이름으로 바꿉니다.
- AUDIENCE 및 AUDIENCE2를 지원하려는 커스텀 대상의 문자열로 바꿉니다(예: example.com 또는 aud1).
속성 값은 큰따옴표와 작은따옴표를 모두 사용해야 하는 따옴표로 묶인 문자열의 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)로 바꿉니다.
요청이 승인되었고 서비스의 예상 응답이 표시되는지 확인합니다.