GCP Authenticator

This topic describes how to configure a Google Cloud Platform (GCP) Authenticator.

Overview

The GCP Authenticator is a secure method for applications running on the Google Cloud Platform to authenticate to Conjur using a unique identity token signed by Google.

A Conjur identity can be established at varying granularity, allowing for a collection of resources to be identified to Conjur as one, or for individual workloads to be uniquely identified.

curl -G -H "Metadata-Flavor: Google" \
--data-urlencode "audience=<audience>"
--data-urlencode "format=<format>" \
"http://metadata/computeMetadata/v1/instance/service-accounts/default/identity"

curl -G -H "Metadata-Flavor: Google" \
--data-urlencode "audience=conjur/myorg/host/gcp-app/test-app"
--data-urlencode "format=full" \
"http://metadata/computeMetadata/v1/instance/service-accounts/default/identity"

{
  "aud": "conjur/myorg/host/myapps/test-app",
  "azp": "177777777777777778",
  "email": "sa-name@project-id.iam.gserviceaccount.com",
  "email_verified": true,
  "exp": 1595160638,
  "google": {
    "compute_engine": {
      "instance_creation_timestamp": 1595766,
      "instance_id": "43405087601530",
      "instance_name": "vm-for-gce",
      "project_id": "eng-serenity-2313",
      "project_number": 7161458341,
      "zone": "us-central1-a"
    }
  },
  "iat": 1595157038,
  "iss": "https://accounts.google.com",
  "sub": "177777777777777778"
}

import requests

def get_id_token():
  audience = 'conjur/myorg/host/myapps/test-app'
  token_response = requests.get(f'http://metadata/computeMetadata/v1/instance/service/accounts/default/identity?audience={audience}', headers={'Metadata-Flavor': 'Google'})
  return token_response.text

{
 "aud": "conjur/myorg/host/myapps/test-app",
 "azp": "117042636860576770546",
 "email": "716149141-compute@developer.gserviceaccount.com",
 "email_verified": true,
 "exp": 1601375923,
 "iat": 1601372323,
 "iss": "https://accounts.google.com",
 "sub": "117042636860576770546"
}

Configure the GCP Authenticator

To communicate with and retrieve secrets from Conjur, the application running on the Google Cloud service needs to authenticate to Conjur and receive a Conjur access token.

This section describes how to configure the GCP Authenticator, and how to define applications to use the GCP Authenticator to authenticate to Conjur.

1. Before you begin

   Before you begin, collect the following details about the Google Cloud service:

   What you need	Description
   Instance name	For GCE only. The name of the GCE instance to which this token belongs.
   Project ID	For GCE only. The ID for the project where you created the GCE instance.
   Service account ID	The subject of the token. This is the unique ID for the service account that you associated with the Google Cloud service.
   Service account email	The service account's name is a unique ID. This appears in the service account's email address that is provisioned during creation. Example: sa-name@project-id.iam.gserviceaccount.com. For more information about service accounts, see the Google Cloud documentation.

2. Define GCP Authenticator policy

   In this step you define the GCP Authenticator in policy, and detail a group of Conjur hosts (applications) that have permission to use the GCP Authenticator to authenticate to Conjur.

   The GCP Authenticator name must be conjur/authn-gcp. Only one GCP Authenticator can be defined in Conjur.

   1. Copy the following policy:

      - !policy id: conjur/authn-gcp body: - !webservice - !group id: apps annotations: description: Group of hosts that can authenticate using the authn-gcp authenticator - !permit role: !group apps privilege: [ read, authenticate ] resource: !webservice

   2. Save the policy as authn-gcp.yml, and load it into root:

      conjur policy load -b root -f authn-gcp.yml

3. Define the GCP resource as a Conjur host in policy

   In this step, you give a Conjur identity to an application running inside the Google Cloud service. The Conjur identity is represented as a host in Conjur. In the host role, you define the resource authentication details. These details are defined as host annotations.

   Use the following guidelines when defining the host annotations:

   • The annotation prefix must be the authenticator ID. For the GCP Authenticator, the annotation prefix is authn-gcp/.

   • Use at least one of the following annotations:

     • authn-gcp/instance-name (GCE only)

     • authn-gcp/project-id (GCE only)

     • authn-gcp/service-account-id

     • authn-gcp/service-account-email

   • The correlation between the annotations is an AND correlation.

   • The annotations are validated against the claims in the Google identity token as follows:

     Google Cloud service	Host annotation	JWT claim	Description
     GCE only	instance-name	google/compute_engine/instance_name	The name of the GCE instance to which this token belongs.
     GCE only	project-id	google/compute_engine/project_id	The ID for the GCP project where you created the GCE instance.
     GCE; GCF	service-account-email	email	The Google Cloud service account's name is a unique identifier; it appears in the service account's email address that is provisioned during creation Example: sa-name@project-id.iam.gserviceaccount.com
     GCE; GCF	service-account-id	sub	The subject of the token. That is, the unique ID for the Google Cloud service account that you associated with the Google Cloud service.

   To define the Google Cloud service as a host in Conjur:

   1. Copy the following policy, and substitute the parameters with the values you collected at the beginning of this procedure:

      - !policy id: <policy-id> body: - !group - &hosts - !host id: <host-id> annotations: authn-gcp/instance-name: <instance-name> authn-gcp/project-id: <project-id> authn-gcp/service-account-id: <service-account-id> authn-gcp/service-account-email: <service-account-email> - !grant role: !group members: *hosts

      If you are loading the policy into root, make sure to EXCLUDE the slash (/) preceding the path in: role: !group [/]conjur/authn-gcp/apps. The path is already rooted, so the slash would be redundant.

      For example:

      - !policy id: gcp-apps body: - !group - &hosts - !host id: test-app annotations: authn-gcp/service-account-id: 177777777777777778 authn-gcp/service-account-email: 177777777777777778-compute@developer.gserviceaccount.com - !grant role: !group members: *hosts - !grant role: !group /conjur/authn-gcp/apps member: !group gcp-apps

   2. Save the policy as authn-gcp-hosts.yml, and load the policy file into any policy level:

      conjur policy load -b <policy-path> -f authn-gcp-hosts.yml

      For example:

      $ conjur policy load -b my/policy/path -f authn-gcp-hosts.yml

4. Define secrets and access for Google services

   1. Define Conjur secrets and a group that has permissions on the secrets.

      In the following example, all members of the consumers group are granted permissions on the test-variable secret.

      - !policy id: secrets body: - !group consumers - !variable test-variable - !permit role: !group consumers privilege: [ read, execute ] resource: !variable test-variable - !grant role: !group secrets/consumers member: !group gcp-apps

   2. Save the policy as authn-gcp-secrets.yml.

   3. Load the policy file into root:

      conjur policy load -b root -f authn-gcp-secrets.yml

   4. Populate the secret with a value. For example:

      $ conjur variable set -i secrets/test-variable -v mySecret

5. Enable the GCP Authenticator

   This step describes how to enable the GCP Authenticator in Conjur.

   Set the CONJUR_AUTHENTICATORS variable as an environment variable, for example:

   CONJUR_AUTHENTICATORS=authn-gcp

   For more information about enabling authenticators in Conjur, see Configure authenticators.
6. Check the authenticator status

   Check that the GCP Authenticator is configured correctly. For details, see Authenticator Status Webservice.