Skip to content

Commit 2e2de78

Browse files
author
Chris Cho
authored
DOCSP-12575: Python CSFLE updates for Azure (#684)
* DOCSP-12575: add Azure instructions for Python
1 parent 566c9bb commit 2e2de78

6 files changed

+526
-241
lines changed

‎source/includes/steps-fle-convert-to-a-remote-master-key.yaml renamed to ‎source/includes/steps-fle-convert-to-a-remote-master-key-aws.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,11 @@ content: |
181181
)
182182
data_key_id = client_encryption.create_data_key("aws")
183183
184+
.. note::
185+
186+
To use AWS KMS, you must use `pymongocrypt <https://pypi.org/project/pymongocrypt/>`__
187+
version 1.0 or later in your application's environment.
188+
184189
---
185190
title: Update the Automatic Encryption JSON Schema
186191
ref: update-the-json-schema

‎source/includes/steps-fle-convert-to-a-remote-master-key-azure.yaml

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
title: Register an Azure Application
2+
ref: create-an-azure-user
3+
content: |
4+
Register a new application in Azure Active directory if you do not already
5+
have one for this CSFLE-enabled client. See the Azure documentation on
6+
`Applications and service principals <https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals>`__
7+
for more information.
8+
9+
Once you register the application, take note of the following credentials
10+
needed to authenticate for access to the Key Vault:
11+
12+
- **tenant id**
13+
- **client id**
14+
- **client secret**
15+
16+
---
17+
title: Create the Master Key
18+
ref: create-the-master-key
19+
content: |
20+
21+
The following diagram shows the process of creating a **master key** on
22+
a KMS provider:
23+
24+
.. image:: /figures/CSFLE_Master_Key_KMS.png
25+
:alt: Diagram that describes creating a master key on a KMS provider
26+
27+
You can create a master key with the Azure CLI by following Microsoft's
28+
`Secrets Guide <https://docs.microsoft.com/en-us/azure/key-vault/secrets/about-secrets>`__.
29+
Follow the instructions in one of the :guilabel:`Quickstarts` sections that
30+
corresponds to your preferred method to create and configure your key.
31+
For example, the `Portal Quickstart <https://docs.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal>`__
32+
demonstrates how to create a new vault and key.
33+
34+
Make sure you provide the ``list`` and ``read`` permissions to the
35+
principal used by your client application.
36+
37+
.. important::
38+
39+
The client user *should not* have administrative permissions for the
40+
master key.
41+
---
42+
title: Specify the Azure Credentials
43+
ref: specify-the-azure-credentials
44+
content: |
45+
Unlike the local key provider, the Azure Key Vault does not read the
46+
master key directly from the client application. Instead, it retrieves
47+
the key using your Azure credentials and the key vault details.
48+
49+
Configure your client application with the following authorization
50+
credentials:
51+
52+
.. list-table::
53+
:header-rows: 1
54+
:stub-columns: 1
55+
56+
* - Field
57+
- Required
58+
- Description
59+
60+
* - azure.tenantId
61+
- Yes
62+
- Identifies the organization of the account
63+
64+
* - azure.clientId
65+
- Yes
66+
- Identifies the clientId to authenticate your registered application
67+
68+
* - azure.clientSecret
69+
- Yes
70+
- Used to authenticate your registered application
71+
72+
* - azure.identityPlatformEndpoint
73+
- No
74+
- Specifies a hostname and port number for the authentication server.
75+
Defaults to login.microsoftonline.com and is only needed for
76+
non-commercial Azure instances such as a government or China account.
77+
78+
Update the KMS Provider configuration in your CSFLE-enabled client
79+
creation code:
80+
81+
.. tabs-drivers::
82+
83+
.. tab::
84+
:tabid: java-sync
85+
86+
87+
.. code-block:: java
88+
89+
// TODO: verify correctness
90+
Map<String, Object> providerDetails = new HashMap<String, Object>();
91+
92+
providerDetails.put("tenantId", new BsonString("<Azure account organization>"));
93+
providerDetails.put("clientId", new BsonString("<Azure client ID>"));
94+
providerDetails.put("clientSecret", new BsonString("<Azure client secret>"));
95+
96+
Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
97+
kmsProviders.put("azure", providerDetails);
98+
99+
.. tab::
100+
:tabid: nodejs
101+
102+
.. code-block:: javascript
103+
104+
// TODO: verify correctness
105+
kms_providers = {
106+
azure: {
107+
tenantId: "<Azure account organization>",
108+
clientId: "<Azure client ID>",
109+
clientSecret: "<Azure client secret>"
110+
}
111+
}
112+
113+
.. tab::
114+
:tabid: python
115+
116+
In ``app.py``, define the following dictionary to pass to your call to
117+
construct a ``ClientEncryption`` instance:
118+
119+
120+
.. code-block:: python
121+
122+
kms_providers = {
123+
"azure": {
124+
"tenantId": "<Azure account organization>",
125+
"clientId": "<Azure client ID>",
126+
"clientSecret": "<Azure client secret>"
127+
}
128+
}
129+
---
130+
title: Create a New Data Encryption Key
131+
ref: create-a-new-data-key
132+
content: |
133+
134+
In this step, we generate a new **data encryption key** using the
135+
**master key** in the remote KMS. The following diagram shows the
136+
requests you make from the client application to create and store a
137+
new data encryption key:
138+
139+
.. image:: /figures/CSFLE_Data_Key_KMS.png
140+
:alt: Diagram that describes creating a data encryption key when using a KMS provider
141+
142+
Provide your client with the following information to access the master key:
143+
144+
.. list-table::
145+
:header-rows: 1
146+
:stub-columns: 1
147+
148+
* - Field
149+
- Required
150+
- Description
151+
152+
* - keyName
153+
- Yes
154+
- Name of the master key
155+
156+
* - keyVersion
157+
- No
158+
- Version of the master key
159+
160+
* - keyVaultEndpoint
161+
- Yes
162+
- URL of the key vault. E.g. myVaultName.vault.azure.net
163+
164+
Once you have the required information, run the following code to
165+
generate the new data encryption key:
166+
167+
.. tabs-drivers::
168+
169+
.. tab::
170+
:tabid: java-sync
171+
172+
.. code-block:: Java
173+
174+
// TODO: update for Azure
175+
ClientEncryption clientEncryption = ClientEncryptions.create(ClientEncryptionSettings.builder()
176+
.keyVaultMongoClientSettings(MongoClientSettings.builder()
177+
.applyConnectionString(new ConnectionString("mongodb://localhost:27017"))
178+
.build())
179+
.keyVaultNamespace(keyVaultNamespace)
180+
.kmsProviders(kmsProviders)
181+
.build());
182+
183+
BsonString masterKeyRegion = new BsonString("<Master Key AWS Region>"); // e.g. "us-east-2"
184+
BsonString masterKeyArn = new BsonString("<Master Key ARN>"); // e.g. "arn:aws:kms:us-east-2:111122223333:alias/test-key"
185+
DataKeyOptions dataKeyOptions = new DataKeyOptions().masterKey(
186+
new BsonDocument()
187+
.append("region", masterKeyRegion)
188+
.append("key", masterKeyArn));
189+
190+
BsonBinary dataKeyId = clientEncryption.createDataKey("aws", dataKeyOptions);
191+
String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
192+
193+
System.out.println("DataKeyId [base64]: " + base64DataKeyId);
194+
195+
.. tab::
196+
:tabid: nodejs
197+
198+
.. code-block:: javascript
199+
200+
// TODO: update for Azure
201+
const encryption = new ClientEncryption(client, {
202+
keyVaultNamespace,
203+
kmsProviders
204+
});
205+
const key = await encryption.createDataKey('aws', {
206+
masterKey: {
207+
key: '<Master Key ARN>', // e.g. 'arn:aws:kms:us-east-2:111122223333:alias/test-key'
208+
}
209+
});
210+
211+
const base64DataKeyId = key.toString('base64');
212+
console.log('DataKeyId [base64]: ', base64DataKeyId);
213+
214+
.. tab::
215+
:tabid: python
216+
217+
In ``app.py``, define the following dictionary to pass to your call to
218+
``create_data_key()``:
219+
220+
.. code-block:: python
221+
222+
master_key = {
223+
"keyName": "<Azure key name>",
224+
"keyVersion": "<Azure key version>",
225+
"keyVaultEndpoint": "<Azure key vault endpoint>"
226+
}
227+
228+
.. note::
229+
230+
To use the Azure Key Vault, you must use `pymongocrypt <https://pypi.org/project/pymongocrypt/>`__
231+
version 1.1 or later in your application's environment.
232+
233+
---
234+
title: Update the Automatic Encryption JSON Schema
235+
ref: update-the-json-schema
236+
content: |
237+
Update your :ref:`JSON Schema <fle-define-a-json-schema>` to reference your
238+
new data encryption key id.

0 commit comments

Comments
 (0)