From 3d32990b6f4b57be77455e3ca89e6e21cd0c06b3 Mon Sep 17 00:00:00 2001
From: minherz <minherz@users.noreply.github.com>
Date: Tue, 27 Jul 2021 18:28:25 +0300
Subject: [PATCH] chore(docs): add Authorization section to Java README
 template (#1161)

as a part of the PR 582 for java-logging an authorization section is added to the Java README template.

Fixing googleapis/java-logging#570.
---
 synthtool/gcp/templates/java_library/README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/synthtool/gcp/templates/java_library/README.md b/synthtool/gcp/templates/java_library/README.md
index 4bbdde8e0..0b033ab79 100644
--- a/synthtool/gcp/templates/java_library/README.md
+++ b/synthtool/gcp/templates/java_library/README.md
@@ -1,6 +1,7 @@
 {% set group_id = metadata['repo']['distribution_name'].split(':')|first -%}
 {% set artifact_id = metadata['repo']['distribution_name'].split(':')|last -%}
 {% set repo_short = metadata['repo']['repo'].split('/')|last -%}
+
 # Google {{ metadata['repo']['name_pretty'] }} Client for Java
 
 Java idiomatic client for [{{metadata['repo']['name_pretty']}}][product-docs].
@@ -16,10 +17,12 @@ Java idiomatic client for [{{metadata['repo']['name_pretty']}}][product-docs].
 > Note: This client is a work-in-progress, and may occasionally
 > make backwards-incompatible changes.
 {% endif %}
+
 ## Quickstart
 
 {% if 'snippets' in metadata and metadata['snippets'][metadata['repo']['name'] + '_install_with_bom'] -%}
 If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file
+
 ```xml
 {{ metadata['snippets'][metadata['repo']['name'] + '_install_with_bom'] }}
 ```
@@ -28,6 +31,7 @@ If you are using Maven without BOM, add this to your dependencies:
 {% else %}
 If you are using Maven, add this to your pom.xml file:
 {% endif %}
+
 ```xml
 {% if 'snippets' in metadata and metadata['snippets'][metadata['repo']['name'] + '_install_without_bom'] -%}
 {{ metadata['snippets'][metadata['repo']['name'] + '_install_without_bom'] }}
@@ -42,6 +46,7 @@ If you are using Maven, add this to your pom.xml file:
 
 {% if 'snippets' in metadata and metadata['snippets'][metadata['repo']['name'] + '_install_with_bom'] -%}
 If you are using Gradle 5.x or later, add this to your dependencies
+
 ```Groovy
 implementation platform('com.google.cloud:libraries-bom:{{metadata['latest_bom_version']}}')
 
@@ -50,11 +55,13 @@ compile '{{ group_id }}:{{ artifact_id }}'
 {% endif -%}
 
 If you are using Gradle without BOM, add this to your dependencies
+
 ```Groovy
 compile '{{ group_id }}:{{ artifact_id }}:{{ metadata['latest_version'] }}'
 ```
 
 If you are using SBT, add this to your dependencies
+
 ```Scala
 libraryDependencies += "{{ group_id }}" % "{{ artifact_id }}" % "{{ metadata['latest_version'] }}"
 ```
@@ -63,6 +70,10 @@ libraryDependencies += "{{ group_id }}" % "{{ artifact_id }}" % "{{ metadata['la
 
 See the [Authentication][authentication] section in the base directory's README.
 
+## Authorization
+
+The client application making API calls must be granted [authorization scopes][auth-scopes] required for the desired {{metadata['repo']['name_pretty']}} APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the {{metadata['repo']['name_pretty']}} API calls.
+
 ## Getting Started
 
 ### Prerequisites
@@ -175,6 +186,7 @@ This library follows [Semantic Versioning](http://semver.org/).
 It is currently in major version zero (``0.y.z``), which means that anything may change at any time
 and the public API should not be considered stable.
 {% endif %}{% endif %}
+
 ## Contributing
 
 {% if 'partials' in metadata and metadata['partials']['contributing'] -%}
@@ -188,6 +200,7 @@ Please note that this project is released with a Contributor Code of Conduct. By
 this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more
 information.
 {% endif %}
+
 ## License
 
 Apache 2.0 - See [LICENSE][license] for more information.
@@ -220,6 +233,9 @@ Java is a registered trademark of Oracle and/or its affiliates.
 [maven-version-image]: https://img.shields.io/maven-central/v/{{ group_id }}/{{ artifact_id }}.svg
 [maven-version-link]: https://search.maven.org/search?q=g:{{ group_id }}%20AND%20a:{{ artifact_id }}&core=gav
 [authentication]: https://github.com/googleapis/google-cloud-java#authentication
+[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
+[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles
+[iam-policy]: https://cloud.google.com/iam/docs/overview#cloud-iam-policy
 [developer-console]: https://console.developers.google.com/
 [create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects
 [cloud-sdk]: https://cloud.google.com/sdk/