OpenAI

OpenAI / GCP EKM Integration Instructions

Step-by-step instructions to provision GCP and activate EKM

Updated: 13 days ago

Overview

Enterprise Key Management (EKM) allows OpenAI to encrypt data using a master key that you control. This document shows how to set up your GCP account to give OpenAI limited permissions on your KMS.

Diagram of OpenAI GCP EKM integration flow using STS token exchange and KMS encrypt or decrypt requests

Steps

1. Create a federated identity for OpenAI

OpenAI will be issuing an identity token from an OpenAI-owned GCP account that looks something like this.

  • The azp and sub are OpenAI's service account ID in GCP

  • The aud is your OpenAI organization ID. You can also pick another audience such as your OpenAI project ID - see the instructions below

{
  "aud": "org-xxxx",
  "azp": "105900137572174660365",
  "exp": 1747876928,
  "iat": 1747873328,
  "iss": "https://accounts.google.com",
  "sub": "105900137572174660365"
}

This step recognizes the claims made by that identity token and enables your GCP STS to issue an access token when that identity token is supplied.

  1. Go to IAM & Admin -> Workload Identity Federation and click on Create Pool

    GCP IAM & Admin with Workload Identity Federation selected

  2. In the step Create an identity pool, enter anything for the pool name.

    1. Remember this for later - you'll need to register this with OpenAI

  3. In the step Add a provider to pool:

    1. In Select a provider, select OpenID Connect (OIDC)

    2. Enter anything for the provider name.

    3. In the Issuer (URL) section, enter https://accounts.google.com

    4. In the Audiences section

      1. Select Allowed audiences

      2. Enter the audience that OpenAI should indicate when we pass you a token.

        1. For ChatGPT or API: You can put the OpenAI API organization ID (org-xxx)

        2. For API: you can put a specific API project id for more granularity.

          GCP Workload Identity Provider edit page with Allowed audiences selected and Audience 1 entered

    5. In the Attribute mapping section

      1. for google.subject enter assertion.sub

        Google Cloud attribute mapping with Google 1 google.subject mapped to OIDC 1 assertion.sub

    6. In the Attribute conditions section

      1. put assertion.sub == "105900137572174660365"

  4. Now you should see your workload identity pool and workload identity provider listed in the https://console.cloud.google.com/iam-admin/workload-identity-pools page

    1. Workload identity pool id

      GCP Workload Identity Pools page highlighting the provider ID value needed for OpenAI EKM setup

    2. Workload identity provider ID

      GCP Workload Identity Provider edit page with the provider ID field highlighted

2. Ensure KMS is enabled

Go to https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview to enable KMS. You are not required to create your KMS in the same GCP project where you recognized OpenAI's federated identity; however, if the projects differ, the KMS product must at least be enabled in both projects.

3. Create a new KMS Key

  1. Go to Security -> Data Protection > Key Management

  2. Under the Overview tab click on Create key ring

    1. Choose any name for your key ring

    2. For Purpose and algorithm, select Symmetric encrypt/decrypt

      GCP Key Management Overview page with the Create Key Ring button highlighted

    3. Once you’ve created a key ring, it should be listed in the Key Rings tab. Click on the key ring.

    4. In the key ring details, click on Create Key

      1. Choose any name for your key

4. Create a limited role for encrypt/decrypt operations on the KMS

  1. Go to IAM & Admin -> Roles -> Create role

  2. Enter anything for the role title and ID

  3. Click Add Permissions, then add the following

    1. cloudkms.cryptoKeyVersions.useToDecrypt

    2. cloudkms.cryptoKeyVersions.useToEncrypt

5. Assign OpenAI’s federated identity to the limited KMS role for encrypt/decrypt operations

  1. Go to Security -> Data Protection > Key Management

  2. Click on your key ring name, then click on your key name to get to your key details page.

    1. If you don’t have this, go back to the section Create a KMS

  3. Click on the Permissions tab, then click the button Grant Access

    Google Cloud KMS key details page with Permissions tab open and Grant Access highlighted

  4. Assign the OpenAI federated identity to the custom role you previously created

    1. For the Add principals section, enter principal://iam.googleapis.com/projects/<YOUR_GCP_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<YOUR_GCP_WORKLOAD_IDENTITY_POOL>/subject/105900137572174660365

      1. YOUR_GCP_PROJECT_NUMBER here is the project in which you recognized OpenAI's federated identity by creating a YOUR_GCP_WORKLOAD_IDENTITY_POOL. It can be, but is not required to be, in the same project where your KMS lives.

      2. If the projects differ, make sure that KMS is at least enabled on the other project by going to https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview

    2. In the Assign roles section, select the custom role you created in the previous step for limited EKM permissions

6. Apply any additional restrictions in line with your own security practices

Above is the minimum required information OpenAI needs to set up EKM. You are free to apply additional key policies or restrictions in line with your own internal security practices, as long as OpenAI is able to call encrypt and decrypt operations on your KMS. When you call the key registration endpoint with OpenAI that's described below, we will validate your setup.

After completing the above steps

ChatGPT Enterprise

Please reach out to your OpenAI contact and share the following:

  • "workload_identity_project_number": "123456789012",

    • The 12-digit GCP project number where you registered OpenAI's workload identity

  • "workload_identity_pool_id": "openai-azure",

    • The pool containing the Workload Identity provider that you registered for OpenAI

  • "workload_identity_provider_id": "openai-ekm-service-role",

    • The Workload Identity provider that you registered for OpenAI

  • "kms_project_id": "adjective-noun-12345",

    • The name of the GCP project where your KMS lives

  • "kms_key_name": "openai-kms-key",

    • The name of the Key Management System master key

  • "kms_key_ring_name": "openai-kms-key-ring",

    • The Key Management System key ring containing the master key you manage

  • "kms_key_location": "us-east1"

    • The region where your Key Management System master key is located

We will enable EKM for your ChatGPT organization/workspace.

API

Register your external key with OpenAI

Follow the instructions in this API reference External Keys in the Management API

  • First, register your external key at the OpenAI organization level, which will generate an external key id.

  • In this step, we will validate your setup on GCP by checking that we can auth to your KMS.

  • This won't add EKM to your OpenAI project yet.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
   "type": "gcp",
   "name": "GCP EKM Config",
   "workload_identity_project_number": "123456789012",
   "workload_identity_pool_id": "openai-azure",
   "workload_identity_provider_id": "openai-ekm-service-role",
   "audience": <your org id or project id>,
   "kms_project_id": "adjective-noun-12345",
   "kms_key_name": "openai-kms-key",
   "kms_key_ring_name": "openai-kms-key-ring",
   "kms_key_location": "us-east1"
}'

Then, create an OpenAI project associated with the external key. After this, EKM is activated on your project.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
   "name": "Some Project",

   "external_key_id": "extkey_xxxx"

}'

Was this article helpful?