Securing Cloud Run services tutorial

Setting up gcloud defaults

To configure gcloud with defaults for your Cloud Run service:

1. Set your default project:

   gcloudconfigsetprojectPROJECT_ID

   Replace PROJECT_ID with the name of the project you created for this tutorial.

2. Configure gcloud for your chosen region:

   gcloudconfigsetrun/regionREGION

   Replace REGION with the supported Cloud Run region of your choice.

Retrieving the code sample

To retrieve the code sample for use:

1. Clone the sample app repository to your Cloud Shell or local machine:

   Node.js

   gitclonehttps://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Python

   gitclonehttps://github.com/GoogleCloudPlatform/python-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Go

   gitclonehttps://github.com/GoogleCloudPlatform/golang-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Java

   gitclonehttps://github.com/GoogleCloudPlatform/java-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   C#

   gitclonehttps://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

2. Change to the directory that contains the Cloud Run sample code:

   Node.js

   cdnodejs-docs-samples/run/markdown-preview/

   Python

   cdpython-docs-samples/run/markdown-preview/

   Go

   cdgolang-samples/run/markdown-preview/

   Java

   cdjava-docs-samples/run/markdown-preview/

   C#

   cddotnet-docs-samples/run/markdown-preview/

Reviewing the private Markdown rendering service

From the perspective of the frontend there is a simple API specification for the Markdown service:

• One endpoint at /
• Expects POST requests
• The body of the POST request is Markdown text

You may want to review all of the code for any security concerns or just to learn more about it by exploring the ./renderer/ directory. Note that the tutorial does not explain the Markdown transformation code.

Shipping the private Markdown rendering service

To ship your code, build with Cloud Build, upload to Artifact Registry, and deploy to Cloud Run:

1. Change to the renderer directory:

   Node.js

   cdrenderer/

   Python

   cdrenderer/

   Go

   cdrenderer/

   Java

   cdrenderer/

   C#

   cdSamples.Run.MarkdownPreview.Renderer/

2. Create an Artifact Registry:

   gcloudartifactsrepositoriescreateREPOSITORY\
   --repository-formatdocker\
   --locationREGION

   Replace:

   • REPOSITORY with a unique name for the repository. For each repository location in a project, repository names must be unique.
   • REGION with the Google Cloud region to be used for the Artifact Registry repository.

3. Run the following command to build your container and publish on Artifact Registry.

   Node.js

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/renderer

   Where PROJECT_ID is your Google Cloud project ID, and renderer is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be reused if desired.

   Python

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/renderer

   Where PROJECT_ID is your Google Cloud project ID, and renderer is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be reused if desired.

   Go

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/renderer

   Where PROJECT_ID is your Google Cloud project ID, and renderer is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be re-used if desired.

   Java

   This sample uses Jib to build Docker images using common Java tools. Jib optimizes container builds without the need for a Dockerfile or having Docker installed. Learn more about building Java containers with Jib.

   1. Use the gcloud credential helper to authorize Docker to push to your Artifact Registry.

      gcloudauthconfigure-docker

   2. Use the Jib Maven Plugin to build and push the container to Artifact Registry.

      mvncompilejib:build-Dimage=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/renderer

   Where PROJECT_ID is your Google Cloud project ID, and renderer is the name you want to give your service.

   Upon success, you will see a BUILD SUCCESS message. The image is stored in Artifact Registry and can be re-used if desired.

   C#

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/renderer

   Where PROJECT_ID is your Google Cloud project ID, and renderer is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be re-used if desired.

4. Deploy as a private service with restricted access.

   Cloud Run provides out-of-the-box access control and service identity features. Access control provides an authentication layer that restricts users and other services from invoking the service. Service identity allows restricting your service from accessing other Google Cloud resources by creating a dedicated service account with limited permissions.

   1. Create a service account to serve as the "compute identity" of the render service. By default this has no privileges other than project membership.

      Command line

      gcloudiamservice-accountscreaterenderer-identity

      Terraform

      To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

      resource"google_service_account""renderer"{
      account_id="renderer-identity"
      display_name="Service identity of the Renderer (Backend) service."
      }

      The Markdown rendering service does not integrate directly with anything else in Google Cloud. It needs no further permissions.

   2. Deploy with the renderer-identity service account and deny unauthenticated access.

      Command line

      gcloudrundeployrenderer\
      --imageREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/renderer\
      --service-accountrenderer-identity\
      --no-allow-unauthenticated

      Cloud Run can use the short form service account name instead of the full email address if the service account is part of the same project.

      Terraform

      To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

      resource"google_cloud_run_v2_service""renderer"{
      name="renderer"
      location="us-central1"
      deletion_protection=false # set to "true" in production
      template{
      containers{
       # Replace with the URL of your Secure Services > Renderer image.
       # gcr.io/<PROJECT_ID>/renderer
      image="us-docker.pkg.dev/cloudrun/container/hello"
      }
      service_account=google_service_account.renderer.email
      }
      }

Trying out the private Markdown rendering service

Private services cannot be directly loaded by a web browser. Instead, use curl or a similar HTTP request CLI tool that allows injecting an Authorization header.

To send some bold text to the service and see it convert the markdown asterisks to HTML <strong> tags:

1. Get the URL from the deployment output.

2. Use gcloud to derive a special development-only identity token for authentication:

   TOKEN=$(gcloudauthprint-identity-token)

3. Create a curl request that passes the raw Markdown text as a URL-escaped query string parameter:

   curl-H"Authorization: Bearer $TOKEN"\
   -H'Content-Type: text/plain'\
   -d'**Hello Bold Text**'\
   SERVICE_URL

   Replace SERVICE_URL with the URL provided after deploying the Markdown rendering service.

4. The response should be an HTML snippet:

    <strong>Hello Bold Text</strong>
   

Reviewing the integration between editor and rendering services

The editor service provides a simple text-entry UI and a space to see the HTML preview. Before continuing, review the code retrieved earlier by opening the ./editor/ directory.

Next, explore the following few sections of code that securely integrates the two services.

const{GoogleAuth}=require('google-auth-library');
constgot=require('got');
constauth=newGoogleAuth ();
letclient,serviceUrl;
// renderRequest creates a new HTTP request with IAM ID Token credential.
// This token is automatically handled by private Cloud Run (fully managed) and Cloud Functions.
constrenderRequest=asyncmarkdown=>{
if(!process.env.EDITOR_UPSTREAM_RENDER_URL)
throwError('EDITOR_UPSTREAM_RENDER_URL needs to be set.');
serviceUrl=process.env.EDITOR_UPSTREAM_RENDER_URL;
// Build the request to the Renderer receiving service.
constserviceRequestOptions={
method:'POST',
headers:{
'Content-Type':'text/plain',
},
body:markdown,
timeout:3000,
};
try{
// Create a Google Auth client with the Renderer service url as the target audience.
if(!client)client=awaitauth .getIdTokenClient (serviceUrl);
// Fetch the client request headers and add them to the service request headers.
// The client request headers include an ID token that authenticates the request.
constclientHeaders=awaitclient.getRequestHeaders();
serviceRequestOptions.headers['Authorization']=
clientHeaders['Authorization'];
}catch(err){
throwError('could not create an identity token: '+err.message);
}
try{
// serviceResponse converts the Markdown plaintext to HTML.
constserviceResponse=awaitgot(serviceUrl,serviceRequestOptions);
returnserviceResponse.body;
}catch(err){
throwError('request to rendering service failed: '+err.message);
}
};

app.post('/render',async(req,res)=>{
try{
constmarkdown=req.body.data;
constresponse=awaitrenderRequest(markdown);
res.status(200).send(response);
}catch(err){
console.error('Error rendering markdown:',err);
res.status(500).send(err);
}
});

importos
importurllib
importgoogle.auth.transport.requests
importgoogle.oauth2.id_token
defnew_request(data):
"""Creates a new HTTP request with IAM ID Token credential.
 This token is automatically handled by private Cloud Run and Cloud Functions.
 Args:
 data: data for the authenticated request
 Returns:
 The response from the HTTP request
 """
 url = os.environ.get("EDITOR_UPSTREAM_RENDER_URL")
 if not url:
 raise Exception("EDITOR_UPSTREAM_RENDER_URL missing")
 req = urllib.request.Request(url, data=data.encode())
 auth_req = google.auth.transport.requests.Request()
 target_audience = url
 id_token = google.oauth2.id_token.fetch_id_token(auth_req, target_audience)
 req.add_header("Authorization", f"Bearer {id_token}")
 response = urllib.request.urlopen(req)
 return response.read()

@app.route("/render", methods=["POST"])
defrender_handler():
"""Parse the markdown from JSON and send it to the Renderer service to be
 transformed into HTML.
 """
 body = request.get_json(silent=True)
 if not body:
 return "Error rendering markdown: Invalid JSON", 400
 data = body["data"]
 try:
 parsed_markdown = render.new_request(data)
 return parsed_markdown, 200
 except Exception as err:
 return f"Error rendering markdown: {err}", 500

import(
"bytes"
"context"
"fmt"
"io"
"net/http"
"time"
"golang.org/x/oauth2"
"google.golang.org/api/idtoken"
)
// RenderService represents our upstream render service.
typeRenderServicestruct{
// URL is the render service address.
URLstring
// tokenSource provides an identity token for requests to the Render Service.
tokenSourceoauth2.TokenSource
}
// NewRequest creates a new HTTP request to the Render service.
// If authentication is enabled, an Identity Token is created and added.
func(s*RenderService)NewRequest(methodstring)(*http.Request,error){
req,err:=http.NewRequest(method,s.URL,nil)
iferr!=nil{
returnnil,fmt.Errorf("http.NewRequest: %w",err)
}
ctx,cancel:=context.WithTimeout(context.Background(),30*time.Second)
defercancel()
// Create a TokenSource if none exists.
ifs.tokenSource==nil{
s.tokenSource,err=idtoken.NewTokenSource(ctx,s.URL)
iferr!=nil{
returnnil,fmt.Errorf("idtoken.NewTokenSource: %w",err)
}
}
// Retrieve an identity token. Will reuse tokens until refresh needed.
token,err:=s.tokenSource.Token()
iferr!=nil{
returnnil,fmt.Errorf("TokenSource.Token: %w",err)
}
token.SetAuthHeader(req)
returnreq,nil
}

varrenderClient=&http.Client{Timeout:30*time.Second}
// Render converts the Markdown plaintext to HTML.
func(s*RenderService)Render(in[]byte)([]byte,error){
req,err:=s.NewRequest(http.MethodPost)
iferr!=nil{
returnnil,fmt.Errorf("RenderService.NewRequest: %w",err)
}
req.Body=io.NopCloser(bytes.NewReader(in))
deferreq.Body.Close()
resp,err:=renderClient.Do(req)
iferr!=nil{
returnnil,fmt.Errorf("http.Client.Do: %w",err)
}
out,err:=io.ReadAll(resp.Body)
iferr!=nil{
returnnil,fmt.Errorf("ioutil.ReadAll: %w",err)
}
ifresp.StatusCode!=http.StatusOK{
returnout,fmt.Errorf("http.Client.Do: %s (%d): request not OK",http.StatusText(resp.StatusCode),resp.StatusCode)
}
returnout,nil
}

// makeAuthenticatedRequest creates a new HTTP request authenticated by a JSON Web Tokens (JWT)
// retrievd from Application Default Credentials.
publicStringmakeAuthenticatedRequest(Stringurl,Stringmarkdown){
Stringhtml="";
try{
// Retrieve Application Default Credentials
GoogleCredentialscredentials=GoogleCredentials.getApplicationDefault();
IdTokenCredentialstokenCredentials=
IdTokenCredentials.newBuilder()
.setIdTokenProvider((IdTokenProvider)credentials)
.setTargetAudience(url)
.build();
// Create an ID token
Stringtoken=tokenCredentials.refreshAccessToken().getTokenValue();
// Instantiate HTTP request
MediaTypecontentType=MediaType.get("text/plain; charset=utf-8");
okhttp3.RequestBodybody=okhttp3.RequestBody.create(markdown,contentType);
Requestrequest=
newRequest.Builder()
.url(url)
.addHeader("Authorization","Bearer "+token)
.post(body)
.build();
Responseresponse=ok.newCall(request).execute();
html=response.body().string();
}catch(IOExceptione){
logger.error("Unable to get rendered data",e);
}
returnhtml;
}

// '/render' expects a JSON body payload with a 'data' property holding plain text
// for rendering.
@PostMapping(value="/render",consumes="application/json")
publicStringrender(@RequestBodyDatadata){
Stringmarkdown=data.getData();
Stringurl=System.getenv("EDITOR_UPSTREAM_RENDER_URL");
if(url==null){
Stringmsg=
"No configuration for upstream render service: "
+"add EDITOR_UPSTREAM_RENDER_URL environment variable";
logger.error(msg);
thrownewIllegalStateException(msg);
}
Stringhtml=makeAuthenticatedRequest(url,markdown);
returnhtml;
}

privateasyncTask<string>GetAuthenticatedPostResponse(stringurl,stringpostBody)
{
// Get the OIDC access token from the service account via Application Default Credentials
GoogleCredentialcredential=awaitGoogleCredential.GetApplicationDefaultAsync();
OidcTokentoken=awaitcredential.GetOidcTokenAsync(OidcTokenOptions.FromTargetAudience(url));
stringaccessToken=awaittoken.GetAccessTokenAsync();
// Create request to the upstream service with the generated OAuth access token in the Authorization header
varupstreamRequest=newHttpRequestMessage(HttpMethod.Post,url);
upstreamRequest.Headers.Authorization=newAuthenticationHeaderValue("Bearer",accessToken);
upstreamRequest.Content=newStringContent(postBody);
varupstreamResponse=await_httpClient.SendAsync(upstreamRequest);
upstreamResponse.EnsureSuccessStatusCode();
returnawaitupstreamResponse.Content.ReadAsStringAsync();
}

publicasyncTask<IActionResult>Index([FromBody]RenderModelmodel)
{
varmarkdown=model.Data??string.Empty;
varrenderedHtml=awaitGetAuthenticatedPostResponse(_editorUpstreamRenderUrl,markdown);
returnContent(renderedHtml);
}

Shipping the public editor service

To build and deploy your code:

1. Change to the editor directory:

   Node.js

   cd../editor

   Python

   cd../editor

   Go

   cd../editor

   Java

   cd../editor

   C#

   cd../Samples.Run.MarkdownPreview.Editor/

2. Run the following command to build your container and publish on Artifact Registry.

   Node.js

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/editor

   Where PROJECT_ID is your Google Cloud project ID, and editor is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Container Registry and can be re-used if desired.

   Python

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/editor

   Where PROJECT_ID is your Google Cloud project ID, and editor is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be re-used if desired.

   Go

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/editor

   Where PROJECT_ID is your Google Cloud project ID, and editor is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be re-used if desired.

   Java

   This sample uses Jib to build Docker images using common Java tools. Jib optimizes container builds without the need for a Dockerfile or having Docker installed. Learn more about building Java containers with Jib.

   mvncompilejib:build-Dimage=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/editor

   Where PROJECT_ID is your Google Cloud project ID, and editor is the name you want to give your service.

   Upon success, you will see a BUILD SUCCESS message. The image is stored in Artifact Registry and can be reused if desired.

   C#

   gcloudbuildssubmit--tagREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/editor

   Where PROJECT_ID is your Google Cloud project ID, and editor is the name you want to give your service.

   Upon success, you will see a SUCCESS message containing the ID, creation time, and image name. The image is stored in Artifact Registry and can be re-used if desired.

3. Deploy as a private service with special access to the rendering service.

   1. Create a service account to serve as the "compute identity" of the private service. By default this has no privileges other than project membership.

      Command line

      gcloudiamservice-accountscreateeditor-identity

      Terraform

      To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

      resource"google_service_account""editor"{
      account_id="editor-identity"
      display_name="Service identity of the Editor (Frontend) service."
      }

      The Editor service does not need to interact with anything else in Google Cloud other than the Markdown rendering service.

   2. Grant access to the editor-identity compute identity to invoke the Markdown rendering service. Any service which uses this as a compute identity will have this privilege.

      Command line

      gcloudrunservicesadd-iam-policy-bindingrenderer\
      --memberserviceAccount:editor-identity@PROJECT_ID.iam.gserviceaccount.com\
      --roleroles/run.invoker

      Terraform

      To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

      resource"google_cloud_run_service_iam_member""editor_invokes_renderer"{
      location=google_cloud_run_v2_service.renderer.location
      service=google_cloud_run_v2_service.renderer.name
      role="roles/run.invoker"
      member="serviceAccount:${google_service_account.editor.email}"
      }

      Because this is given the invoker role in the context of the render service, the render service is the only private Cloud Run service the editor can invoke.

   3. Deploy with the editor-identity service account and allow public, unauthenticated access.

      Command line

      gcloudrundeployeditor--imageREGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/editor\
      --service-accounteditor-identity\
      --set-env-varsEDITOR_UPSTREAM_RENDER_URL=SERVICE_URL\
      --allow-unauthenticated

      Replace:

      • PROJECT_ID with your project ID
      • SERVICE_URL with the URL provided after deploying the Markdown rendering service.

      Terraform

      To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

      Deploy the editor service:

      resource"google_cloud_run_v2_service""editor"{
      name="editor"
      location="us-central1"
      deletion_protection=false # set to "true" in production
      template{
      containers{
       # Replace with the URL of your Secure Services > Editor image.
       # gcr.io/<PROJECT_ID>/editor
      image="us-docker.pkg.dev/cloudrun/container/hello"
      env{
      name="EDITOR_UPSTREAM_RENDER_URL"
      value=google_cloud_run_v2_service.renderer.uri
      }
      }
      service_account=google_service_account.editor.email
      }
      }

      
      

      Grant allUsers permission to invoke the service:

      data"google_iam_policy""noauth"{
      binding{
      role="roles/run.invoker"
      members=[
      "allUsers",
      ]
      }
      }
      resource"google_cloud_run_service_iam_policy""noauth"{
      location=google_cloud_run_v2_service.editor.location
      project=google_cloud_run_v2_service.editor.project
      service=google_cloud_run_v2_service.editor.name
      policy_data=data.google_iam_policy.noauth.policy_data
      }

Understanding the HTTPS traffic

There are three HTTP requests involved in rendering markdown using these services.

Trying it out

To try out the complete two-service application:

1. Navigate your browser to the URL provided by the deployment step above.

2. Try editing the Markdown text on the left and click the button to see it preview on the right.

   It should look like this:

   Screenshot of the Markdown Editor User Interface

If you choose to continue developing these services, remember that they have restricted Identity and Access Management (IAM) access to the rest of Google Cloud and will need to be given additional IAM roles to access many other services.