> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyless authentication in Google Cloud

> Learn how to implement keyless authentication in Google Cloud.

To enable Keyless Authentication in GCP you'll first need permissions to create service accounts and assign these accounts roles to GCP.

The workflow to enable keyless authentication is:

1. Create a service account with no permissions for federation.
2. If you do not attach a service account to compute resources or use the default service account, we recommend creating a new service account for the compute resources. Create a service account to attach to compute resources and impersonate the federation service account.
3. Create an authorization policy to allow the federation service account to authenticate to Endor Labs.
4. Provision the compute resources with the appropriate permissions.
5. Test Keyless authentication.

### Create GCP service accounts and authorization policies

To create your service accounts, first export your GCP project name as an environment variable:

```bash theme={null}
export PROJECT=<insert-gcp-project>
```

<Steps>
  <Step title="Create a federation service account">
    Create a federation service account called `endorlabs-federation`:

    ```bash theme={null}
    gcloud iam service-accounts create endorlabs-federation --description="Endor Labs Keyless Federation Service Account" --display-name="Endor Labs Federation Service Account"
    ```
  </Step>

  <Step title="Create a compute service account">
    Create a keyless authentication service account to assign to compute resources called `endorlabs-compute-service`:

    ```bash theme={null}
    gcloud iam service-accounts create endorlabs-compute-service --description="Endor Labs Service account for keyless authentication" --display-name="Endor Labs Compute Instance SA"
    ```

    This is needed if you don't already have service accounts for your compute resources. If you do, you need to modify the existing permissions to allow the existing service account to create a federation token.
  </Step>

  <Step title="Assign impersonation permissions">
    Assign the `serviceAccountOpenIdTokenCreator` role to the `endorlabs-compute-service` service account:

    ```bash theme={null}
    gcloud projects add-iam-policy-binding $PROJECT --member="serviceAccount:endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com" --role="roles/iam.serviceAccountOpenIdTokenCreator"
    ```
  </Step>

  <Step title="Create an authorization policy in Endor Labs">
    Use the following command to create an authorization policy to allow the `endorlabs-federation` account to authenticate to your Endor Labs tenant.

    <Note>
      Replace `<your-tenant>` with your Endor Labs tenant name and `<insert-your-project>` with your GCP project name.
    </Note>

    <Note>
      If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`.
    </Note>

    ```bash expandable theme={null}
    endorctl api create -r AuthorizationPolicy -d '{
        "tenant_meta": { "namespace": "<your-tenant>" },
        "meta": {
            "name": "Keyless Auth",
            "kind": "AuthorizationPolicy",
            "tags": ["gcp"]
         },
         "spec": {
            "clause": ["email=endorlabs-federation@<insert-your-project>.iam.gserviceaccount.com", "gcp"],
            "target_namespaces": ["<your-tenant>"],
            "propagate": true,
            "permissions": {
                "rules": {},
                "roles": [
                    "SYSTEM_ROLE_CODE_SCANNER"
                ]
            },
        }
    }'
    ```
  </Step>
</Steps>

You've now set up the foundation of keyless authentication. You'll now need to provision your compute resources with the appropriate GCP scopes and service account.

See [Provision and test keyless authentication for GKE workloads](#provision-and-test-keyless-authentication-for-gke-workloads) for instructions on setting up GKE for keyless authentication.

See [Provision and Test Keyless Authentication for GCP Virtual Machine Instances](#provision-and-test-keyless-authentication-for-gcp-virtual-machine-instances) for instructions on setting up a virtual machine instance for keyless authentication.

### Provision and test keyless authentication for GKE workloads

#### Prerequisites

The following prerequisites are required to setup keyless authentication on GKE workloads:

* Workload identity is enabled on the target GKE cluster. See the [GCP documentation on using workload identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) for instructions on migrating existing cluster node pools or creating new clusters to use GCP workload identity.
* The gcloud auth plugin is installed and operational on your machine. See the [GCP instructions on enabling the gcloud auth plugin](https://cloud.google.com/blog/products/containers-kubernetes/kubectl-auth-changes-in-gke) for more details.
* The kubectl CLI is installed. See [the Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/) for instructions.

#### Procedure

The following instructions require you to export these environment variables:

```bash theme={null}
export PROJECT=<Insert_GCP_Project>
export CLUSTER_NAME=<GKE_CLUSTER>
```

<Steps>
  <Step title="Create a GKE cluster with workload identity">
    Optionally, create a GKE cluster with workload identity enabled if you do not already have one:

    ```bash theme={null}
    gcloud container clusters create keyless-test --workload-pool=endor-github.svc.id.goog --scopes https://www.googleapis.com/auth/cloud-platform
    ```
  </Step>

  <Step title="Authenticate to the GKE cluster">
    ```bash theme={null}
    gcloud container clusters get-credentials $CLUSTER_NAME
    ```
  </Step>

  <Step title="Create a namespace for Endor Labs scans">
    Optionally, create a dedicated namespace:

    ```bash theme={null}
    kubectl create namespace endorlabs
    ```
  </Step>

  <Step title="Create a Kubernetes service account">
    ```bash theme={null}
    kubectl create serviceaccount endorlabs-compute-service -n endorlabs
    ```
  </Step>

  <Step title="Bind the Kubernetes service account to your GCP compute service account">
    <Note>
      Replace `<insert-your-project>` with your GCP project name.
    </Note>

    ```bash theme={null}
    gcloud iam service-accounts add-iam-policy-binding endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:<insert-your-project>.svc.id.goog[endorlabs/endorlabs-compute-service]"
    ```
  </Step>

  <Step title="Annotate the Kubernetes service account">
    <Note>
      If you created a different service account name, replace `endorlabs-compute-service` with the appropriate name.
    </Note>

    ```bash theme={null}
    kubectl annotate serviceaccount endorlabs-compute-service -n endorlabs iam.gke.io/gcp-service-account=endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com
    ```
  </Step>

  <Step title="Test a scanning workload using keyless authentication">
    Run a test scan to confirm keyless authentication is working correctly.
  </Step>
</Steps>

## Provision and Test Keyless Authentication for GCP Virtual Machine Instances

The following instructions require you to export the following environment variable:

```bash theme={null}
export PROJECT=<Insert_GCP_Project>
```

<Steps>
  <Step title="Create a virtual machine instance with the appropriate scopes">
    ```bash theme={null}
    gcloud compute instances create test-keyless --service-account endorlabs-compute-service@$PROJECT.iam.gserviceaccount.com --scopes https://www.googleapis.com/auth/cloud-platform
    ```
  </Step>

  <Step title="Download and install endorctl on the virtual machine instance">
    SSH to the virtual machine instance:

    ```bash theme={null}
    gcloud compute ssh --zone "us-west1-b" "test-keyless"  --project $PROJECT
    ```

    Then download and install the latest version of `endorctl`. See [our documentation for instructions on downloading the latest version](/developers-api/cli/install-and-configure).
  </Step>

  <Step title="Launch a test scan with keyless authentication">
    Use the `--gcp-service-account` flag for federated access to Endor Labs:

    ```bash theme={null}
    endorctl api list --gcp-service-account=endorlabs-federation@<insert-your-project>.iam.gserviceaccount.com -r Project -n <insert-your-tenant> --count
    ```

    If this scan runs successfully you've tested and scanned a project with keyless authentication to Endor Labs.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.