> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ox-integrations/3rd-party-integrations/registry/google.md).

# Google Artifact Registry

Google Cloud Artifact Registry (GAR) is a unified registry service for managing and securing software artifacts.

GAR offers:

* **Centralized hosting** for multiple artifact types like Docker images, language-specific packages (Maven, npm, Python) and OS packages.
* **Granular access control** through Cloud IAM.
* **Direct integration with Google Cloud's deployment services**, such as Cloud Run and Google Kubernetes Engine (GKE).

By connecting GAR to OX Security, you have a constant connection to GAR and scanned results are displayed in the Artifact’s BOM. OX Security scans the Docker images in every Artifact Registry location of the project you connect.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-e91f2a84b4bbf6354361ea27d51822dad248b20d%2Fartifact%20bom.png?alt=media" alt=""><figcaption></figcaption></figure>

## Prerequisites

Ensure the following requirements are met:

* You have OX Security admin permissions to set up the connection.
* In Google Cloud, you can create service accounts and service account keys, and grant IAM roles on the project that hosts your Artifact Registry repositories.
* Your organization policy allows service account key creation (the `iam.disableServiceAccountKeyCreation` constraint is not enforced for the service account's project).
* Required access:

OX Security connects with a service account key and reads your registry. It needs only the following:

| What                                                                | Where                                                                                                                                    | Why                                                                                            |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Artifact Registry Reader** role (`roles/artifactregistry.reader`) | Granted to the service account **at project level** on the project that hosts your repositories, the Project ID you enter in OX Security | OX Security lists locations, repositories and Docker images, and downloads images to scan them |
| **Cloud Resource Manager API** enabled                              | The project the service account **belongs to**                                                                                           | OX Security checks the service account's permissions when you connect                          |

{% hint style="info" %}
The service account can belong to a different project than your repositories. In that case, grant the role in the IAM page of the project that hosts the repositories, and enable the Cloud Resource Manager API in the service account's own project.
{% endhint %}

{% hint style="warning" %}
A role granted on individual repositories is not enough: OX Security lists the repositories of the whole project. OX Security does not need the Browser role, `resourcemanager.projects.get` or any write permission.
{% endhint %}

If you use a custom role instead of Artifact Registry Reader, it must include:

* `artifactregistry.locations.list`
* `artifactregistry.repositories.list`
* `artifactregistry.packages.list`
* `artifactregistry.dockerimages.list`
* `artifactregistry.repositories.downloadArtifacts`

## Connection overview

These steps summarize the connection process.

1. [Enable the Cloud Resource Manager API.](#step-1-enable-the-cloud-resource-manager-api)
2. [Create a service account.](#step-2-create-a-service-account)
3. [Grant the Artifact Registry Reader role on the project that hosts your repositories.](#step-3-grant-the-artifact-registry-reader-role-on-the-project-that-hosts-your-repositories)
4. [Create a JSON key for the service account.](#step-4-create-a-json-key-for-the-service-account)
5. [Base64-encode the key.](#step-5-base64-encode-the-key)
6. [Pass the credentials to OX Security.](#step-6-pass-the-credentials-to-ox-security)

## Connection steps

To connect GAR to OX Security, follow these steps:

### Step 1: Enable the Cloud Resource Manager API

<mark style="color:$warning;">Do this in the project the service account belongs to. If you have not created the service account yet, use the project you will create it in.</mark>

1. From the dashboard, use the search bar to find **API & Services** and click **Enable API & Services**. This opens the **API Library** page.<br>

   <div align="left"><figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-6a025de47c23b6976a86454282c391bbec7acb47%2Fenable%20api%20services.png?alt=media" alt=""><figcaption></figcaption></figure></div>
2. From the **API Library** page, use the search bar to find **Cloud Resource Manager API** and click the **Cloud Resource Manager API** link.<br>

   <figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-63ac5ea93bc768f0dbeba82867ddf991a52c532d%2Fcloud%20resource%20manager.png?alt=media" alt=""><figcaption></figcaption></figure>
3. Verify that the **API is enabled**. If not, click **Manage** to enable it.<br>

   <figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-5ea4c37f7f73881150fa82c7c63d05ee879b26bf%2Fcloud%20resource%20manager%20enabled.png?alt=media" alt=""><figcaption></figcaption></figure>
4. Alternatively, run:

```bash
gcloud services enable cloudresourcemanager.googleapis.com --project=SERVICE_ACCOUNT_PROJECT_ID
```

***

### Step 2: Create a service account

You can skip this step and use an existing service account.

1. From the Google Cloud dashboard menu, select **IAM & Admin > Service Accounts** and click **Create service account**.<br>

   <figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-b3785ae3275b7c375754e6dcfe7161477652c65b%2Fcreate%20service%20account%20button.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Enter a **Service account name** and **Service account description** (the **Service account ID** is auto-generated). Then click **Create and continue**.<br>

   <div align="left"><figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-8eea39ea21f873f72bf2f38c933b7e8a9032c436%2Fcreate%20service%20account%20with%20details.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>
3. If your repositories are in this same project, you can grant the role here: open **Select a role**, choose **Artifact Registry > Artifact Registry Reader**, and click **Continue**. Otherwise, click **Continue** without a role and grant it in Step 3.
4. Leave the **Principals with access** as is. To complete the creation of the service account, click **Done**.<br>

   <div align="left"><figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-9f9ddbbaae1482d92cf2a9458d8a40d046ee3d1b%2Fcreate%20service%20account%20leave%20principals.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>
5. Copy the service account's email address (for example, `ox-gar-reader@my-project.iam.gserviceaccount.com`). You need it in Step 3.

***

### Step 3: Grant the Artifact Registry Reader role on the project that hosts your repositories

Skip this step if you granted the role in Step 2 and your repositories are in the service account's project.

1. In the Google Cloud console's project picker, select the project that hosts your Artifact Registry repositories.
2. Select **IAM & Admin > IAM** and click **Grant access**.
3. In **New principals**, enter the service account's email address.
4. In **Select a role**, choose **Artifact Registry > Artifact Registry Reader**.
5. Click **Save**.
6. Alternatively, run:

```bash
gcloud projects add-iam-policy-binding REPOSITORIES_PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/artifactregistry.reader"
```

To scan several projects, repeat this step for each one. You can use the same service account and key for all of them.

***

### Step 4: Create a JSON key for the service account

1. From **IAM & Admin > Service Accounts**, select the service account and open the **Keys** tab.<br>

   <figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-77a338494853159c87539ae486378962eb2378b7%2Fservice%20account%20keys.png?alt=media" alt=""><figcaption></figcaption></figure>
2. On the **Keys** tab, click **Add key** and select **JSON** as the key type.<br>

   <div align="left"><figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-32f67df164af20ce2ed3ffed283fe53d81f49fa1%2Fprivate%20key%20json.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>
3. Read the warning about data security.

   <figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-133577711fa0398f1778cf9a87a55ff0106ac4ba%2Fprivate%20key%20warning%20saved.png?alt=media" alt=""><figcaption></figcaption></figure>
4. To complete, click **Close**. The JSON key is now saved to your computer.

***

### Step 5: Base64-encode the key

Encode the whole JSON key file, unchanged. Do not paste the raw JSON, an access token or an API key.

* macOS:

  ```bash
  base64 -i key.json
  ```
* Linux:

  ```bash
  base64 -w 0 key.json
  ```
* Windows (PowerShell):

  ```powershell
  [Convert]::ToBase64String([IO.File]::ReadAllBytes("$PWD\key.json"))
  ```

***

### Step 6: Connect Google Artifact Registry to OX Security

Use the credentials generated in the previous steps to connect Google Artifact Registry to OX Security.

**To connect Google Artifact Registry:**

1. Sign in to OX Security.
2. Go to the **OX Connectors** page and open the **GAR** connector.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-b6522b3958d9a6a24a3776844945fa3a7a65897b%2Fgoogle_artifact_registry.png?alt=media" alt=""><figcaption></figcaption></figure>

3. Enter the following details:

<table data-header-hidden><thead><tr><th width="302.75"></th><th></th></tr></thead><tbody><tr><td>Field</td><td>Description</td></tr><tr><td>Project ID</td><td>The ID of the Google Cloud project that hosts your repositories. Use the project ID, not the project name.</td></tr><tr><td>API Token</td><td>The Base64-encoded string generated in Step 5.</td></tr></tbody></table>

4. Click **Connect**. If the credentials are valid, a success message appears.

To scan repositories in another project, create an additional connection using that project's ID.

## Post-setup checks

Use either or both of these steps.

* From the OX Connectors page open the GAR connector and click **Verify Connectivity**.
* From the same screen, click **Settings**. This displays a list of all images.

## Logs and alerts

If your credentials are not accepted, an error message shows on the connection screen.

## Troubleshooting

| Message                                                                                     | What to check                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The API Token must be the JSON key of a Google service account, Base64-encoded…             | The API Token is not a Base64-encoded service account key. Encode the whole JSON key file as shown in [Step 5](#step-5-base64-encode-the-key).                                                                  |
| Authentication failed. Please check your credentials and try again.                         | Google rejected the key: it was deleted or disabled, or the service account was deleted. Create a new key (Step 4).                                                                                             |
| Google denied access to the project…                                                        | The Project ID is wrong, the service account does not have the Artifact Registry Reader role on that project (Step 3), or the Cloud Resource Manager API is disabled in the service account's project (Step 1). |
| The service account has none of the Artifact Registry permissions OX needs on this project… | Grant the Artifact Registry Reader role on the project (Step 3).                                                                                                                                                |
| Invalid credentials type not supported                                                      | Shown by earlier versions of OX Security for any of the cases above. Check Steps 1 to 5.                                                                                                                        |

If the connection succeeds but no images appear, check that your repositories are Docker repositories and that the role is granted at project level, not on individual repositories.

If your credentials are valid but you still can’t connect to GAR, reach out to Customer Support.

## Disconnection

To disconnect, open the GAR connector and select **DELETE**.

To reconnect, re-enter the Project ID and API token.

add link to ArtifactBOM


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/ox-integrations/3rd-party-integrations/registry/google.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.