docs(samples): added auth samples and tests

samples/snippets/pom.xml

@@ -0,0 +1,101 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.google.auth.samples</groupId>
+  <artifactId>authsamples</artifactId>
+  <version>1.0.0</version>
+  <name>auth-samples</name>
+
+
+  <!--
+    The parent pom defines common style checks and testing strategies for our samples.
+    Removing or replacing it should not affect the execution of the samples in anyway.
+  -->
+  <parent>
+    <groupId>com.google.cloud.samples</groupId>
+    <artifactId>shared-configuration</artifactId>
+    <version>1.2.0</version>
+  </parent>
+
+  <properties>
+    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
+  <!-- START dependencies -->
+  <!--  Using libraries-bom to manage versions.
+  See https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM -->
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>com.google.cloud</groupId>
+        <artifactId>libraries-bom</artifactId>
+        <version>25.0.0</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+
+  <dependencies>
+<!--    OAuth dependency-->
+    <dependency>
+      <groupId>com.google.auth</groupId>
+      <artifactId>google-auth-library-oauth2-http</artifactId>
+      <version>1.3.0</version>
+    </dependency>
+
+<!--    IAM dependency-->
+    <dependency>
+      <groupId>com.google.apis</groupId>
+      <artifactId>google-api-services-iam</artifactId>
+      <version>v1-rev20220509-1.32.1</version>
+    </dependency>
+    <dependency>
+      <groupId>com.google.apis</groupId>
+      <artifactId>google-api-services-iamcredentials</artifactId>
+      <version>v1-rev20211203-1.32.1</version>
+    </dependency>
+
+<!--    JWT dependency-->
+    <dependency>
+      <groupId>com.auth0</groupId>
+      <artifactId>java-jwt</artifactId>
+      <version>3.16.0</version>
+    </dependency>
+    <dependency>
+      <groupId>com.auth0</groupId>
+      <artifactId>jwks-rsa</artifactId>
+      <version>0.18.0</version>
+    </dependency>
+
+<!--    GCloud dependency-->
+    <dependency>
+      <artifactId>google-cloud-compute</artifactId>
+      <groupId>com.google.cloud</groupId>
+      <version>1.8.1</version>
+    </dependency>
+    <dependency>
+      <groupId>com.google.cloud</groupId>
+      <artifactId>google-cloud-storage</artifactId>
+    </dependency>
+
+<!--    Test dependencies-->
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.13.1</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <artifactId>truth</artifactId>
+      <groupId>com.google.truth</groupId>
+      <scope>test</scope>
+      <version>1.1.3</version>
+    </dependency>
+
+  </dependencies>
+
+</project>
+

samples/snippets/src/main/java/AuthWithCredentialsFromMetadataServer.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2022 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import com.google.api.gax.paging.Page;
+import com.google.auth.oauth2.ComputeEngineCredentials;
+import com.google.auth.oauth2.GoogleCredentials;
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+
+public class AuthWithCredentialsFromMetadataServer {
+
+  public static void main(String[] args) throws IOException, GeneralSecurityException {
+    // TODO(Developer):
+    //  1. Replace the below variable.
+    //  2. Make sure you have the necessary permission to list storage buckets
+    // "storage.buckets.list"
+    String projectId = "your-google-cloud-project-id";
+
+    authWithCredentialsFromMetadataServer(projectId);
+  }
+
+  // Authenticating using Client libraries can be done in one of the following ways:
+  // 1. Implicit authentication with ADC (Application Default Credentials)
+  // 2. Explicit authentication by specifying the service account
+  // 3. Authentication with service account credentials obtained from a metadata server, like,
+  // Compute Engine or App Engine etc.,
+  // 4. Bring your own (BYO) access token
+  // 5. Using API keys (for libraries that support)
+  //
+  // In this snippet, we demonstrate "Authentication with service account credentials
+  // obtained from a metadata server".
+  public static void authWithCredentialsFromMetadataServer(String project) {
+
+    // This snippet demonstrates how to initialize Cloud Storage and list buckets.
+    // Note that the credentials are requested from the ComputeEngine metadata server.
+    Storage storage = initService(project);
+
+    System.out.println("Buckets:");
+    Page<Bucket> buckets = storage.list();
+    for (Bucket bucket : buckets.iterateAll()) {
+      System.out.println(bucket.toString());
+    }
+    System.out.println("Authentication complete.");
+  }
+
+  // Initialize the Storage client by getting the Service account credentials
+  // from a Metadata server.
+  private static Storage initService(String projectId) {
+    // Explicitly request the service account credentials from the ComputeEngine metadata server.
+    GoogleCredentials credentials = ComputeEngineCredentials.create();
+
+    // Alternately, if executing within AppEngine, you can get credentials as follows:
+    // GoogleCredentials credentials = AppEngineCredentials.getApplicationDefault();
+
+    // Construct the Storage client.
+    // Note that, here we explicitly specify the service account to use.
+    return StorageOptions.newBuilder()
+        .setCredentials(credentials)
+        .setProjectId(projectId)
+        .build()
+        .getService();
+  }
+}

samples/snippets/src/main/java/AuthenticateExplicit.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2022 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import com.google.api.gax.paging.Page;
+import com.google.auth.oauth2.GoogleCredentials;
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+import com.google.common.collect.Lists;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+
+public class AuthenticateExplicit {
+
+  public static void main(String[] args) throws IOException, GeneralSecurityException {
+    // TODO(Developer):
+    //  1. Replace the below variable.
+    //  2. Make sure you have the necessary permission to list storage buckets
+    // "storage.buckets.list"
+    String projectId = "your-google-cloud-project-id";
+
+    // Path to the service account json credential file.
+    String jsonCredentialPath = "path-to-json-credential-file";
+
+    // Provide the scopes that you might need to request to access Google APIs,
+    // depending on the level of access you need.
+    // Example: The following scope lets you view and manage Pub/Sub topics and subscriptions.
+    // For more information, see: https://developers.google.com/identity/protocols/oauth2/scopes
+    String scope = "https://www.googleapis.com/auth/devstorage.full_control";
+
+    authenticateExplicit(projectId, jsonCredentialPath, scope);
+  }
+
+  // Authenticating using Client libraries can be done in one of the following ways:
+  // 1. Implicit authentication with ADC (Application Default Credentials)
+  // 2. Explicit authentication by specifying the service account
+  // 3. Authentication with service account credentials obtained from metadata server, like,
+  // Compute Engine or App Engine etc.,
+  // 4. Bring your own (BYO) access token
+  // 5. Using API keys (for libraries that support)
+  //
+  // In this snippet, we demonstrate "Explicit authentication by specifying the service account".
+  public static void authenticateExplicit(String project, String jsonCredentialPath, String scope)
+      throws IOException {
+
+    // This snippet demonstrates how to initialize Cloud Storage and list buckets.
+    // Note that the credentials are explicitly specified when constructing the client.
+    Storage storage = initService(project, jsonCredentialPath, scope);
+
+    System.out.println("Buckets:");
+    Page<Bucket> buckets = storage.list();
+    for (Bucket bucket : buckets.iterateAll()) {
+      System.out.println(bucket.toString());
+    }
+    System.out.println("Authentication complete.");
+  }
+
+  // Initialize the Storage client by explicitly setting the Service account to use.
+  private static Storage initService(String projectId, String jsonCredentialPath, String scope)
+      throws IOException {
+    // Construct the GoogleCredentials object which accepts the service account json file and
+    // scope as the input parameters.
+    GoogleCredentials credentials =
+        GoogleCredentials.fromStream(new FileInputStream(jsonCredentialPath))
+            .createScoped(Lists.newArrayList(scope));
+
+    // Construct the Storage client.
+    // Note that, here we explicitly specify the service account to use.
+    return StorageOptions.newBuilder()
+        .setCredentials(credentials)
+        .setProjectId(projectId)
+        .build()
+        .getService();
+  }
+}

samples/snippets/src/main/java/AuthenticateImplicitWithAdc.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2022 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import com.google.cloud.compute.v1.Instance;
+import com.google.cloud.compute.v1.InstancesClient;
+import java.io.IOException;
+
+public class AuthenticateImplicitWithAdc {
+
+  public static void main(String[] args) throws IOException {
+    // TODO(Developer):
+    //  1. Set the following environment variable before running the code.
+    //  APPLICATION_DEFAULT_CREDENTIALS="path-to-the-service-account-json-credential-file"
+    //  2. Replace the below variable.
+    //  3. Make sure you have the necessary permission "compute.instances.list"
+    String projectId = "your-google-cloud-project-id";
+    authenticateImplicitWithAdc(projectId);
+  }
+
+  // Authenticating using Client libraries can be done in one of the following ways:
+  // 1. Implicit authentication with ADC (Application Default Credentials)
+  // 2. Explicit authentication by specifying the service account
+  // 3. Authentication with service account credentials obtained from metadata server, like,
+  // Compute Engine or App Engine etc.,
+  // 4. Bring your own (BYO) access token
+  // 5. Using API keys (for libraries that support)
+  //
+  // In this snippet, we demonstrate "Implicit authentication with ADC".
+  // ADC - Application Default Credentials
+  // When interacting with Google Cloud Client libraries, the library can auto-detect the
+  // credentials to use, if the "APPLICATION_DEFAULT_CREDENTIALS" is set.
+  // This APPLICATION_DEFAULT_CREDENTIALS is an environment variable/ configuration.
+  // This configuration can be made available to the code in various ways depending upon where the
+  // code is executed.
+  // Examples:
+  // 1. If running your code in local development environment, just set the following environment
+  // variable:
+  //      APPLICATION_DEFAULT_CREDENTIALS="path-to-the-service-account-json-file"  OR
+  // You can also set the ADC with gcloud if you have the gcloud installed:
+  //      gcloud auth application-default login
+  //
+  // 2. When you use a Google Cloud cloud-based development environment such as Cloud Shell or
+  // Cloud Code, the tool uses the credentials you provided when you logged in,
+  // and manages any authorizations required.
+  //
+  // For more environments, see:
+  // https://cloud.devsite.corp.google.com/docs/authentication/provide-credentials-adc
+  //
+  // ADC detection is independent of the client library and language and works with all Cloud Client
+  // libraries.
+  public static void authenticateImplicitWithAdc(String project) throws IOException {
+
+    String zone = "us-central1-a";
+    // This snippet demonstrates how to initialize Cloud Compute Engine and list instances.
+    // Note that the credentials are not specified when constructing the client.
+    // Hence, the client library will look for credentials via the
+    // environment variable GOOGLE_APPLICATION_CREDENTIALS.
+    try (InstancesClient instancesClient = InstancesClient.create()) {
+      // Set the project and zone to retrieve instances present in the zone.
+      System.out.printf("Listing instances from %s in %s:", project, zone);
+      for (Instance zoneInstance : instancesClient.list(project, zone).iterateAll()) {
+        System.out.println(zoneInstance.getName());
+      }
+      System.out.println("####### Listing instances complete #######");
+    }
+  }
+}