push 구독 인증

push 구독에 인증이 사용되는 경우 Pub/Sub 서비스가 JWT를 서명하고 push 요청의 승인 헤더에서 JWT를 전송합니다. JWT에는 클레임 및 서명이 포함됩니다.

구독자는 JWT를 검증하고 다음 사항을 확인할 수 있습니다.

클레임이 정확한가
Pub/Sub 서비스가 클레임에 서명했는가

구독자가 방화벽을 사용하는 경우 push 요청을 수신할 수 없습니다. push 요청을 받으려면 방화벽을 사용 중지하고 JWT를 확인해야 합니다.

시작하기 전에

구독에 대해 알아보기
push 구독의 작동 방식 알아보기
push 구독 만들기

JWT 형식

JWT는 헤더, 클레임 세트, 서명으로 구성되는 OpenIDConnect JWT입니다. Pub/Sub 서비스는 JWT를 마침표 구분 기호가 포함된 base64 문자열로 인코딩합니다.

예를 들어 다음 승인 헤더에는 인코딩된 JWT가 포함됩니다.

"Authorization" : "Bearer
eyJhbGciOiJSUzI1NiIsImtpZCI6IjdkNjgwZDhjNzBkNDRlOTQ3MTMzY2JkNDk5ZWJjMWE2MWMzZDVh
YmMiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL2V4YW1wbGUuY29tIiwiYXpwIjoiMTEzNzc0M
jY0NDYzMDM4MzIxOTY0IiwiZW1haWwiOiJnYWUtZ2NwQGFwcHNwb3QuZ3NlcnZpY2VhY2NvdW50LmNvb
SIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJleHAiOjE1NTAxODU5MzUsImlhdCI6MTU1MDE4MjMzNSwia
XNzIjoiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tIiwic3ViIjoiMTEzNzc0MjY0NDYzMDM4MzIxO
TY0In0.QVjyqpmadTyDZmlX2u3jWd1kJ68YkdwsRZDo-QxSPbxjug4ucLBwAs2QePrcgZ6hhkvdc4UHY
4YF3fz9g7XHULNVIzX5xh02qXEH8dK6PgGndIWcZQzjSYfgO-q-R2oo2hNM5HBBsQN4ARtGK_acG-NGG
WM3CQfahbEjZPAJe_B8M7HfIu_G5jOLZCw2EUcGo8BvEwGcLWB2WqEgRM0-xt5-UPzoa3-FpSPG7DHk7
z9zRUeq6eB__ldb-2o4RciJmjVwHgnYqn3VvlX9oVKEgXpNFhKuYA-mWh5o7BCwhujSMmFoBOh6mbIXF
cyf5UiVqKjpqEbqPGo_AvKvIQ9VTQ"

헤더 및 클레임 세트는 JSON 문자열입니다. 디코딩되면 다음과 같은 형식을 사용합니다.

{"alg":"RS256","kid":"7d680d8c70d44e947133cbd499ebc1a61c3d5abc","typ":"JWT"}

{
   "aud":"https://example.com",
   "azp":"113774264463038321964",
   "email":"gae-gcp@appspot.gserviceaccount.com",
   "sub":"113774264463038321964",
   "email_verified":true,
   "exp":1550185935,
   "iat":1550182335,
   "iss":"https://accounts.google.com"
  }

push 엔드포인트로 전송된 요청에 연결된 토큰은 최대 1시간이 걸릴 수 있습니다.

push 인증을 위한 Pub/Sub 구성

다음 예시에서는 push 인증 서비스 계정을 원하는 서비스 계정으로 설정하는 방법과 Google 관리형 서비스 계정 service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com에 iam.serviceAccountTokenCreator 역할을 부여하는 방법을 보여줍니다.

콘솔

Pub/Sub 구독 페이지로 이동합니다.

구독 페이지로 이동
구독 만들기를 클릭합니다.
구독 ID 필드에 이름을 입력합니다.
주제를 선택합니다.
전송 유형으로 push를 선택합니다.
엔드포인트 URL을 입력합니다.
인증 사용 설정을 선택합니다.
서비스 계정을 선택합니다.
Google 관리형 서비스 계정 service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com에 프로젝트의 IAM 대시보드에 대한 iam.serviceAccountTokenCreator 역할이 있는지 확인합니다. 서비스 계정에 역할이 부여되지 않은 경우 IAM 대시보드에서 권한 부여를 클릭하여 역할을 수행합니다.
선택사항: 잠재고객을 입력합니다.
만들기를 클릭합니다.

gcloud

# Configure the push subscription
gcloud pubsub subscriptions (create|update|modify-push-config) ${SUBSCRIPTION} \
 --topic=${TOPIC} \
 --push-endpoint=${PUSH_ENDPOINT_URI} \
 --push-auth-service-account=${SERVICE_ACCOUNT_EMAIL} \
 --push-auth-token-audience=${OPTIONAL_AUDIENCE_OVERRIDE}

# Your Google-managed service account
# `service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com` needs to have the
# `iam.serviceAccountTokenCreator` role.
PUBSUB_SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
 --member="serviceAccount:${PUBSUB_SERVICE_ACCOUNT}"\
 --role='roles/iam.serviceAccountTokenCreator'

push 구독에 대해 인증을 사용 설정할 때 permission denied 또는 not authorized 오류가 발생할 수 있습니다. 이 문제를 해결하려면 구독 만들기 또는 업데이트를 시작하는 주 구성원에게 서비스 계정에 대한 iam.serviceAccounts.actAs 권한을 부여합니다. 자세한 내용은 'push 구독 만들기'에서 인증을 참조하세요.

IAP(Identity-Aware Proxy)로 보호되는 App Engine 애플리케이션에 인증된 push 구독을 사용하는 경우 push 인증 토큰 대상으로 IAP 클라이언트 ID를 제공해야 합니다. App Engine 애플리케이션에서 IAP를 사용 설정하려면 IAP 사용 설정을 참조하세요. IAP 클라이언트 ID를 찾으려면 사용자 인증 정보 페이지에서 IAP-App-Engine-app 클라이언트 ID를 찾습니다.

클레임

JWT는 Google에서 서명한 email 및 aud 클레임을 포함한 클레임을 확인하는 데 사용할 수 있습니다. 인증 및 승인에 Google의 OAuth 2.0 API를 사용하는 방법에 대한 자세한 내용은 OpenID Connect를 참조하세요.

이러한 클레임을 의미 있게 하는 두 가지 메커니즘이 있습니다. 먼저 Pub/Sub에서는 CreateSubscription, UpdateSubscription 또는 ModifyPushConfig 호출을 수행하는 사용자 또는 서비스 계정이 push 인증 서비스 계정에 대해 iam.serviceAccounts.actAs 권한이 있는 역할이 있을 것을 요구합니다. 이러한 역할의 예시로는 roles/iam.serviceAccountUser 역할이 있습니다.

두 번째로 토큰 서명에 사용된 인증서에 대한 액세스는 엄격하게 제어됩니다. 토큰을 만들려면 Pub/Sub에서 Google 관리형 서비스 계정 service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com인 별도의 서명 서비스 계정 ID를 사용하여 내부 Google 서비스를 호출해야 합니다. 이 서명 서비스 계정은 push 인증 서비스 계정(또는 프로젝트와 같은 push 인증 서비스 계정의 모든 상위 리소스)에 대해 iam.serviceAccounts.getOpenIdToken 권한 또는 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)이 있어야 합니다.

토큰 검증

Pub/Sub에서 push 엔드포인트로 보낸 토큰 검증에는 다음이 포함됩니다.

서명 유효성 검사를 사용하여 토큰 무결성을 확인합니다.
토큰의 email 및 audience 클레임이 push 구독 구성에서 설정된 값과 일치하는지 확인

다음 예시는 IAP(Identity-Aware Proxy)로 보호되지 않는 App Engine 애플리케이션에 대해 push 요청을 인증하는 방법을 보여줍니다. App Engine 애플리케이션이 IAP로 보호되는 경우 IAP JWT를 포함하는 HTTP 요청 헤더가 x-goog-iap-jwt-assertion이고 그에 따라 검증되어야 합니다.

프로토콜

요청:

GET https://oauth2.googleapis.com/tokeninfo?id_token={BEARER_TOKEN}

응답:

200 OK

{
    "alg": "RS256",
    "aud": "example.com",
    "azp": "104176025330667568672",
    "email": "{SERVICE_ACCOUNT_NAME}@{YOUR_PROJECT_NAME}.iam.gserviceaccount.com",
    "email_verified": "true",
    "exp": "1555463097",
    "iat": "1555459497",
    "iss": "https://accounts.google.com",
    "kid": "3782d3f0bc89008d9d2c01730f765cfb19d3b70e",
    "sub": "104176025330667568672",
    "typ": "JWT"
}

C#

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C# API 참고 문서를 확인하세요.

        /// <summary>
        /// Extended JWT payload to match the pubsub payload format.
        /// </summary>
        public class PubSubPayload : JsonWebSignature.Payload
        {
            [JsonProperty("email")]
            public string Email { get; set; }
            [JsonProperty("email_verified")]
            public string EmailVerified { get; set; }
        }
        /// <summary>
        /// Handle authenticated push request coming from pubsub.
        /// </summary>
        [HttpPost]
        [Route("/AuthPush")]
        public async Task<IActionResult> AuthPushAsync([FromBody] PushBody body, [FromQuery] string token)
        {
            // Get the Cloud Pub/Sub-generated "Authorization" header.
            string authorizaionHeader = HttpContext.Request.Headers["Authorization"];
            string verificationToken = token ?? body.message.attributes["token"];
            // JWT token comes in `Bearer <JWT>` format substring 7 specifies the position of first JWT char.
            string authToken = authorizaionHeader.StartsWith("Bearer ") ? authorizaionHeader.Substring(7) : null;
            if (verificationToken != _options.VerificationToken || authToken is null)
            {
                return new BadRequestResult();
            }
            // Verify and decode the JWT.
            // Note: For high volume push requests, it would save some network
            // overhead if you verify the tokens offline by decoding them using
            // Google's Public Cert; caching already seen tokens works best when
            // a large volume of messages have prompted a single push server to
            // handle them, in which case they would all share the same token for
            // a limited time window.
            var payload = await JsonWebSignature.VerifySignedTokenAsync<PubSubPayload>(authToken);

            // IMPORTANT: you should validate payload details not covered
            // by signature and audience verification above, including:
            //   - Ensure that `payload.Email` is equal to the expected service
            //     account set up in the push subscription settings.
            //   - Ensure that `payload.Email_verified` is set to true.

            var messageBytes = Convert.FromBase64String(body.message.data);
            string message = System.Text.Encoding.UTF8.GetString(messageBytes);
            s_authenticatedMessages.Add(message);
            return new OkResult();
        }

Go

// receiveMessagesHandler validates authentication token and caches the Pub/Sub
// message received.
func (a *app) receiveMessagesHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != "POST" {
		http.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
		return
	}

	// Verify that the request originates from the application.
	// a.pubsubVerificationToken = os.Getenv("PUBSUB_VERIFICATION_TOKEN")
	if token, ok := r.URL.Query()["token"]; !ok || len(token) != 1 || token[0] != a.pubsubVerificationToken {
		http.Error(w, "Bad token", http.StatusBadRequest)
		return
	}

	// Get the Cloud Pub/Sub-generated JWT in the "Authorization" header.
	authHeader := r.Header.Get("Authorization")
	if authHeader == "" || len(strings.Split(authHeader, " ")) != 2 {
		http.Error(w, "Missing Authorization header", http.StatusBadRequest)
		return
	}
	token := strings.Split(authHeader, " ")[1]
	// Verify and decode the JWT.
	// If you don't need to control the HTTP client used you can use the
	// convenience method idtoken.Validate instead of creating a Validator.
	v, err := idtoken.NewValidator(r.Context(), option.WithHTTPClient(a.defaultHTTPClient))
	if err != nil {
		http.Error(w, "Unable to create Validator", http.StatusBadRequest)
		return
	}
	// Please change http://example.com to match with the value you are
	// providing while creating the subscription.
	payload, err := v.Validate(r.Context(), token, "http://example.com")
	if err != nil {
		http.Error(w, fmt.Sprintf("Invalid Token: %v", err), http.StatusBadRequest)
		return
	}
	if payload.Issuer != "accounts.google.com" && payload.Issuer != "https://accounts.google.com" {
		http.Error(w, "Wrong Issuer", http.StatusBadRequest)
		return
	}

	// IMPORTANT: you should validate claim details not covered by signature
	// and audience verification above, including:
	//   - Ensure that `payload.Claims["email"]` is equal to the expected service
	//     account set up in the push subscription settings.
	//   - Ensure that `payload.Claims["email_verified"]` is set to true.
	if payload.Claims["email"] != "test-service-account-email@example.com" || payload.Claims["email_verified"] != true {
		http.Error(w, "Unexpected email identity", http.StatusBadRequest)
		return
	}

	var pr pushRequest
	if err := json.NewDecoder(r.Body).Decode(&pr); err != nil {
		http.Error(w, fmt.Sprintf("Could not decode body: %v", err), http.StatusBadRequest)
		return
	}

	a.messagesMu.Lock()
	defer a.messagesMu.Unlock()
	// Limit to ten.
	a.messages = append(a.messages, pr.Message.Data)
	if len(a.messages) > maxMessages {
		a.messages = a.messages[len(a.messages)-maxMessages:]
	}

	fmt.Fprint(w, "OK")
}

Java

@WebServlet(value = "/pubsub/authenticated-push")
public class PubSubAuthenticatedPush extends HttpServlet {
  private final String pubsubVerificationToken = System.getenv("PUBSUB_VERIFICATION_TOKEN");
  private final MessageRepository messageRepository;
  private final GoogleIdTokenVerifier verifier =
      new GoogleIdTokenVerifier.Builder(new NetHttpTransport(), new GsonFactory())
          /**
           * Please change example.com to match with value you are providing while creating
           * subscription as provided in @see <a
           * href="https://github.com/GoogleCloudPlatform/java-docs-samples/tree/main/appengine-java8/pubsub">README</a>.
           */
          .setAudience(Collections.singletonList("example.com"))
          .build();
  private final Gson gson = new Gson();

  @Override
  public void doPost(HttpServletRequest req, HttpServletResponse resp)
      throws IOException, ServletException {

    // Verify that the request originates from the application.
    if (req.getParameter("token").compareTo(pubsubVerificationToken) != 0) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
      return;
    }
    // Get the Cloud Pub/Sub-generated JWT in the "Authorization" header.
    String authorizationHeader = req.getHeader("Authorization");
    if (authorizationHeader == null
        || authorizationHeader.isEmpty()
        || authorizationHeader.split(" ").length != 2) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
      return;
    }
    String authorization = authorizationHeader.split(" ")[1];

    try {
      // Verify and decode the JWT.
      // Note: For high volume push requests, it would save some network overhead
      // if you verify the tokens offline by decoding them using Google's Public
      // Cert; caching already seen tokens works best when a large volume of
      // messsages have prompted a single push server to handle them, in which
      // case they would all share the same token for a limited time window.
      GoogleIdToken idToken = verifier.verify(authorization);

      GoogleIdToken.Payload payload = idToken.getPayload();
      // IMPORTANT: you should validate claim details not covered by signature
      // and audience verification above, including:
      //   - Ensure that `payload.getEmail()` is equal to the expected service
      //     account set up in the push subscription settings.
      //   - Ensure that `payload.getEmailVerified()` is set to true.

      messageRepository.saveToken(authorization);
      messageRepository.saveClaim(payload.toPrettyString());
      // parse message object from "message" field in the request body json
      // decode message data from base64
      Message message = getMessage(req);
      messageRepository.save(message);
      // 200, 201, 204, 102 status codes are interpreted as success by the Pub/Sub system
      resp.setStatus(102);
      super.doPost(req, resp);
    } catch (Exception e) {
      resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
    }
  }

  private Message getMessage(HttpServletRequest request) throws IOException {
    String requestBody = request.getReader().lines().collect(Collectors.joining("\n"));
    JsonElement jsonRoot = JsonParser.parseString(requestBody).getAsJsonObject();
    String messageStr = jsonRoot.getAsJsonObject().get("message").toString();
    Message message = gson.fromJson(messageStr, Message.class);
    // decode from base64
    String decoded = decode(message.getData());
    message.setData(decoded);
    return message;
  }

  private String decode(String data) {
    return new String(Base64.getDecoder().decode(data));
  }

  PubSubAuthenticatedPush(MessageRepository messageRepository) {
    this.messageRepository = messageRepository;
  }

  public PubSubAuthenticatedPush() {
    this(MessageRepositoryImpl.getInstance());
  }
}

Node.js

app.post('/pubsub/authenticated-push', jsonBodyParser, async (req, res) => {
  // Verify that the request originates from the application.
  if (req.query.token !== PUBSUB_VERIFICATION_TOKEN) {
    res.status(400).send('Invalid request');
    return;
  }

  // Verify that the push request originates from Cloud Pub/Sub.
  try {
    // Get the Cloud Pub/Sub-generated JWT in the "Authorization" header.
    const bearer = req.header('Authorization');
    const [, token] = bearer.match(/Bearer (.*)/);
    tokens.push(token);

    // Verify and decode the JWT.
    // Note: For high volume push requests, it would save some network
    // overhead if you verify the tokens offline by decoding them using
    // Google's Public Cert; caching already seen tokens works best when
    // a large volume of messages have prompted a single push server to
    // handle them, in which case they would all share the same token for
    // a limited time window.
    const ticket = await authClient.verifyIdToken({
      idToken: token,
      audience: 'example.com',
    });

    const claim = ticket.getPayload();

    // IMPORTANT: you should validate claim details not covered
    // by signature and audience verification above, including:
    //   - Ensure that `claim.email` is equal to the expected service
    //     account set up in the push subscription settings.
    //   - Ensure that `claim.email_verified` is set to true.

    claims.push(claim);
  } catch (e) {
    res.status(400).send('Invalid token');
    return;
  }

  // The message is a unicode string encoded in base64.
  const message = Buffer.from(req.body.message.data, 'base64').toString(
    'utf-8'
  );

  messages.push(message);

  res.status(200).send();
});

Python

@app.route("/push-handlers/receive_messages", methods=["POST"])
def receive_messages_handler():
    # Verify that the request originates from the application.
    if request.args.get("token", "") != current_app.config["PUBSUB_VERIFICATION_TOKEN"]:
        return "Invalid request", 400

    # Verify that the push request originates from Cloud Pub/Sub.
    try:
        # Get the Cloud Pub/Sub-generated JWT in the "Authorization" header.
        bearer_token = request.headers.get("Authorization")
        token = bearer_token.split(" ")[1]
        TOKENS.append(token)

        # Verify and decode the JWT. `verify_oauth2_token` verifies
        # the JWT signature, the `aud` claim, and the `exp` claim.
        # Note: For high volume push requests, it would save some network
        # overhead if you verify the tokens offline by downloading Google's
        # Public Cert and decode them using the `google.auth.jwt` module;
        # caching already seen tokens works best when a large volume of
        # messages have prompted a single push server to handle them, in which
        # case they would all share the same token for a limited time window.
        claim = id_token.verify_oauth2_token(
            token, requests.Request(), audience="example.com"
        )

        # IMPORTANT: you should validate claim details not covered by signature
        # and audience verification above, including:
        #   - Ensure that `claim["email"]` is equal to the expected service
        #     account set up in the push subscription settings.
        #   - Ensure that `claim["email_verified"]` is set to true.

        CLAIMS.append(claim)
    except Exception as e:
        return f"Invalid token: {e}\n", 400

    envelope = json.loads(request.data.decode("utf-8"))
    payload = base64.b64decode(envelope["message"]["data"])
    MESSAGES.append(payload)
    # Returning any 2xx status indicates successful receipt of the message.
    return "OK", 200

Ruby

post "/pubsub/authenticated-push" do
  halt 400 if params[:token] != PUBSUB_VERIFICATION_TOKEN

  begin
    bearer = request.env["HTTP_AUTHORIZATION"]
    token = /Bearer (.*)/.match(bearer)[1]
    claim = Google::Auth::IDTokens.verify_oidc token, aud: "example.com"

    # IMPORTANT: you should validate claim details not covered by signature
    # and audience verification above, including:
    #   - Ensure that `claim["email"]` is equal to the expected service
    #     account set up in the push subscription settings.
    #   - Ensure that `claim["email_verified"]` is set to true.

    claims.push claim
  rescue Google::Auth::IDTokens::VerificationError => e
    puts "VerificationError: #{e.message}"
    halt 400, "Invalid token"
  end

  message = JSON.parse request.body.read
  payload = Base64.decode64 message["message"]["data"]

  messages.push payload
end

위 코드 샘플에 사용된 환경 변수 PUBSUB_VERIFICATION_TOKEN에 대한 상세 설명은 Pub/Sub 메시지 작성 및 응답을 참조하세요.

이 웹사이트용 Google 로그인 가이드에서 Bearer JWT 유효성을 검사하는 방법의 추가 예시를 확인할 수 있습니다. JWT 검증에 도움이 되는 클라이언트 라이브러리 목록을 포함하여 OpenID Connect 가이드에서 OpenID 토큰에 대한 광범위한 개요를 확인할 수 있습니다.

다른 Google Cloud 서비스에서 인증

Cloud Run, App Engine, Cloud Functions는 Pub/Sub에서 생성한 토큰을 확인하여 Pub/Sub에서 HTTP 호출을 인증합니다. 유일하게 필요한 구성은 호출자 계정에 필요한 IAM 역할을 부여하는 것입니다.

이러한 서비스의 여러 사용 사례는 다음 가이드와 튜토리얼을 참조하세요.

Cloud Run

Pub/Sub push에서 트리거: push 인증 서비스 계정에는 해당 Cloud Run 서비스를 호출하기 위해 roles/run.invoker 역할이 있어야 하고 Cloud Run에 결합되어야 합니다.
Cloud Run에 Pub/Sub 사용 튜토리얼

App Engine

Pub/Sub 메시지 쓰기 및 응답

Cloud Functions

HTTP 트리거: push 인증 서비스 계정에는 Pub/Sub push 요청을 함수에 대한 HTTP 트리거로 사용하려는 경우 함수를 호출하려면 roles/cloudfunctions.invoker 역할이 있어야 합니다.
Google Cloud Pub/Sub 트리거: Pub/Sub 트리거를 사용하여 함수를 호출하면 IAM 역할 및 권한이 자동으로 구성됩니다.

참고: 1세대 App Engine 런타임에서는 동일한 프로젝트 내 양식 /_ah/push-handlers/.*의 엔드포인트 URL로 push 요청이 관리자로 승인되었습니다. 이 ACL 메커니즘은 2세대 App Engine 런타임에서 더 이상 지원되지 않습니다. 2세대 App Engine 런타임에서 push 구독이 구성된 push 인증 서비스 계정에 관리자용 IAM 역할을 부여합니다. 자세한 내용은 사용자 인증 및 액세스 제어 이해를 참조하세요.