Machina gives you the ability to enforce powerful data access policy with just a few lines of code, providing a consistent, seamless way to assure the ongoing security of data underlying your applications. This article will provide instructions for using Machina data protection keys and policy controls inside Google Cloud Platform (GCP) via the Google Cloud External Key Manager (EKM) integration.
1. Create or identify GCP account and Ionic tenant to use for the integration
To configure External Key Manager keys, you need the following:
- An existing or new GCP project. To create a new Google Cloud account and project, visit: https://cloud.google.com/gcp/
- A Machina account. To create a new account, visit https://ionic.com/start-for-free/, or reach out to our support team via our contact form at: https://support.ionic.com/hc/en-us/requests/new
Note that you can configure External Key Manager keys for multiple GCP projects using a single Machina instance. You are not required to create a new instance for each GCP project.
Note also that GCP services integrating with External Key Manager include BigQuery (BQ) and Google Compute Engine (GCE), so you will need to use those services to exercise External Key Manager capabilities. Further, we recommend launching any services integrating with External Key Manager in the us-west1 region for optimal performance (refer to Deploy Machina for Google External Key Manager).
2. Locate Key Management Service (KMS) account for GCP project
Once you enable the KMS API in your GCP project, a KMS service account with id “service-[PROJECT-NUMBER]@gcp-sa-ekms.iam.gserviceaccount.com” is automatically created for you, and GCP KMS is granted access to assume that role.
Note that [PROJECT-NUMBER] is the project number for your GCP project, which can be found in the GCP Web Console on the “Home” tab under the “Project Info” section.
3. Configure the Machina instance
In your Machina instance, create two users with the following details:
- User 1 (aka device owner, aka “Ionic GCP Connector User”):
- First name: GCP EKM
- Last name: Connector
- Username: gcp-ekm
- Email: <any email address you own>
- Groups: <none>
- Roles: <API Administrator, Dashboard Administrator>
- User 2 (aka delegatee, aka “GCP Service Account User”):
- First name: GCP EKM
- Last name: “service-[PROJECT-NUMBER]”
- Username: “service-[PROJECT-NUMBER]”
- External id: <the service account id from step 2>
- Email: <none>
- Domain UPN: <none>
- Groups: <none>
- Roles: <none>
Next, set up data access policies and settings for your instance, including:
- A data policy called “own-data” that always allows the creator of the key to request keys.
- This is required because we are using delegated requests for the EKM integration, where User 1 is the delegator and User 2 is the delegatee.
- A user group called “GCP Integration Users” with User 2 added to this group.
- A data marking called “ionic-for-application” with a data marking value “GCP-EKM”
- A data policy called “GCP EKM application” that allows requests for keys when the data marking "ionic-for-application" has the value "GCP-EKM", and the requesting user is in the group “GCP Integration Users”.
Note that you will only need to create User 1 once per instance; however, you will need to create User 2 per GCP project you wish to integrate with.
4. Register the device and create the key
Using the email address provided for the User 1 account, check for the “Welcome” email. Click the password reset link.
ionic-profiles create \
--keyspace ABcd \
--auth-method ionic-authentication \
--ionic-user-name gcp-ekm \
--persistor plaintext \
Note that this new device profile will be used in the EKM integration. Requests will come through as delegated requests with User 1 as the delegator and User 2 as the delegatee.
5. Send device profile to Ionic support
During the Beta release, the device profile saved in `profile.pt` contains secrets used to authenticate to Machina APIs, and as such this information should be closely guarded. To send this information to Ionic customer support in a secure manner, submit a request to Ionic customer support requesting configuration of the GCP External Key Manager integration. In the request, please include the GCP KMS service account id you will use for the integration (from step 2).
Ionic support will respond with a secure upload link from Box which you can use to upload the plaintext device profile created in step 4. Upload the profile using the provided link. Customer support will inform you when the integration is ready for the next step.
6. Create Machina key for each GCP External Key Manager key
In this integration, each GCP External Key Manager key is backed by a Machina key.
Create EKM keys using the device associated with User 1. Use the data marking “ionic-for-application” set to the value “GCP-EKM”. You can do this using any of the Ionic SDKs (download). You will need to grab the keytag of this key. Sample code for creating this key and grabbing the key tag using the Ionic Machina Python SDK is shown below.
pt = ionicsdk.DeviceProfilePersistorPlaintextFile("profiles.pt")
a = ionicsdk.Agent(profilepersistor=pt)
Feel free to apply additional markings to keys at creation time to allow additional policy controls.
7. Map Machina key to External Key Manager URI
The GCP External Key Manager integration requires entering a valid External Key Manager URI in the GCP KMS console. This URI should be: https://ekm.ionic.com/v0/<keytag>
Replace “<keytag>” with the keytag of the key created in step 6.
8. Create External Key Management key in the GCP KMS console
Create a KMS keyring and External Key Manager key in the GCP console in the us-west1 region following documentation and using the URI from step 7.
After creating a keyring “mykeyring” and key “mykey”, the gcloud cli command for creating a new EKM Crypto Key Version (CKV) backed by the Ionic key created in step 6 would be:
gcloud beta kms keys versions create \
--key mykey \
--keyring mykeyring \
--location us-west1 \
--external-key-uri https://ekm.ionic.com/v0/<keytag> \
Again, replace “<keytag>” in this command with the keytag of the key created in step 6.