Skip to content

Commit 724e9d0

Browse files
katarzyna-koltun-mxkatarzyna-koltun-mx
authored
Merge pull request #10268 from mendix/kk-azure-key-vault-pmp
PMP - azure key vault
2 parents 479ad53 + fce402f commit 724e9d0

File tree

2 files changed

+282
-2
lines changed

2 files changed

+282
-2
lines changed

‎content/en/docs/private-platform/configuration/pmp-configure-aws-secret.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,9 +118,7 @@ When creating a property to use as a key for external secret storage, use the fo
118118

119119
* Build Cluster Settings
120120

121-
* **kubernetesConfigureToken**
122121
* **BuildCluster.KubernetesConfigureToken** - Token for the Kubernetes cluster configuration
123-
* **JenkinsConfigureAPIToken**
124122
* **CIAdmin.JenkinsConfigureAPIToken** - Token for the Jenkins configuration
125123
* **CIAdmin.JenkinsTriggerAuthToken** - Token for the Jenkins trigger configuration
126124
* **CIAdmin.AzureOrgAdminPAT** - Personal access token for the Azure DevOps configuration

‎content/en/docs/private-platform/configuration/pmp-configure-azure-key-vault.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
---
2+
title: "Configuring External Secret Management with Azure Key Vault"
3+
url: /private-mendix-platform/configure-azure-key-vault/
4+
description: "Documents the configuration of Azure Key Vault for the Private Mendix Platform."
5+
weight: 40
6+
---
7+
8+
## Introduction
9+
10+
The Private Mendix Platform offers enhanced security and flexibility for credential management by supporting [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault) as an external secret management solution, alongside the traditional database storage option. In the legacy database storage approach, the credentials are encrypted and stored directly in the Private Mendix Platform database. With Azure Key Vault, credentials are instead stored in a secure vault and accessed securely via for improved security, centralized management, and compliance with enterprise security policies. This document describes how you can configure Azure Key Vault integration for your Private Mendix Platform project.
11+
12+
## Prerequisites
13+
14+
Before configuring Azure Key Vault integration, prepare the following:
15+
16+
* An Azure subscription with appropriate permissions to create and manage Key Vaults.
17+
* Permissions in Azure Active Directory (Azure AD) to create User-Assigned Managed Identities and grant role assignments.
18+
* Access to the Private Mendix Platform project admin panel with administrative privileges.
19+
* Basic knowledge of Azure services, Azure AD, and Kubernetes (if using AKS deployment).
20+
* An existing AKS (Azure Kubernetes Service) cluster with the OIDC Issuer feature enabled.
21+
22+
## Configuring External Secret Management
23+
24+
To configure external secret management, you must first create a Key Vault and store your sensitive credentials as secrets, configure Azure AD Workload Identity, and then configure the required credentials in the Private Mendix Platform administrator panel. For more information, refer to the sections below.
25+
26+
### Creating a Secret
27+
28+
To create a secret in Azure Key Vault, perform the following steps:
29+
30+
1. Log in to the Azure Portal.
31+
2. Navigate to the **Key Vaults** service.
32+
3. Click **Create** and configure a new Key Vault:
33+
34+
1. Select your **Subscription** and **Resource Group**.
35+
2. Enter a Key Vault name (for example, *PMP-Production-Vault*). This name must be globally unique.
36+
3. Select a **Region**.
37+
4. On the **Access configuration** tab, select **Azure role-based access control (RBAC)** as the permission model.
38+
39+
4. Review and create the Key Vault.
40+
5. Once deployed, navigate to your new Key Vault.
41+
6. Go to the **Secrets** section and click **Generate/Import**.
42+
7. Enter a **Name** for your secret (for example, *PMP-Credentials*).
43+
8. Click **Create** to store the secret.
44+
45+
{{% alert color="info" %}}
46+
Make note of the Vault Name (for example, *PMP-Production-Vault*). You will need this when configuring Private Mendix Platform.
47+
{{% /alert %}}
48+
49+
#### Naming Convention for Key Properties {#naming-convention}
50+
51+
When creating the JSON structure for your secret, you must use a flat key-value format. The key names use a hyphen to separate the module from the credential name (for example, *Email-SMTPPassword*).
52+
53+
* All the key names are read-only. You should not change them.
54+
* Create the keys in the external secret storage with the same names as in the Private Mendix Platform configuration.
55+
* The mappings are as follows:
56+
57+
* VCS
58+
59+
* Bitbucket
60+
61+
* **VCS.BitbucketProjectAdminPAT** - Personal access token for the Bitbucket project admin
62+
* **VCS.BitbucketAdminPassword** - Password for the Bitbucket admin user
63+
64+
* GitLab
65+
66+
* **VCS.GitlabGroupOwnerPAT** - Personal access token for the GitLab group owner
67+
* **VCS.GitlabAdminPAT** - Personal access token for the GitLab admin
68+
69+
* GitHub
70+
71+
* **VCS.GithubOrgOwnerPAT** - Personal access token for the GitHub organization owner
72+
* **VCS.GithubAdminPAT** - Personal access token for the GitHub admin
73+
* **VCS.GithubEnterpriseClientSecret** - Client secret for the GitHub Enterprise app
74+
75+
* Azure
76+
77+
* **VCS.AzureDevOpsOrgAdminPAT** - Personal access token for the Azure DevOps organization owner
78+
* **VCS.AzureAuthSecret** - Currently unused
79+
80+
* Kubernetes Build Settings
81+
82+
* BuildPackage
83+
84+
* fileServerBasic
85+
86+
* **BuildPackage.FileBasicAuthPassword** - Password for the file server
87+
88+
* AwsAKSK
89+
90+
* **BuildPackage.AwsSecretAccessKey** - AWS secret access key for the file server
91+
92+
* RuntimeBaseImage
93+
94+
* privateRegistry
95+
96+
* **RuntimeBaseImage.PrivateRegistryPassword** - Base image for the runtime
97+
98+
* S3compatibleAccessKey
99+
100+
* **RuntimeBaseImage.S3CompatibleAccessKey** - S3-compatible access key for the base image
101+
102+
* MDAStorage
103+
104+
* fileServerBasic
105+
106+
* **MDAStorage.FileBasicAuthPassword** - Password for the file server
107+
108+
* awsAKSK
109+
110+
* **MDAStorage.AwsSecretAccessKey** - AWS secret access key for the MDA storage
111+
112+
* OCIRegistry
113+
114+
* privateRegistry
115+
116+
* **OCIRegistry.PrivateRegistryPassword** - Password for the private registry
117+
118+
* S3compatibleAccessKey
119+
120+
* **OCIRegistry.S3CompatibleAccessKey** - S3 compatible access key for the OCI registry
121+
122+
* Build Cluster Settings
123+
124+
* **BuildCluster.KubernetesConfigureToken** - Token for the Kubernetes cluster configuration
125+
* **CIAdmin.JenkinsConfigureAPIToken** - Token for the Jenkins configuration
126+
* **CIAdmin.JenkinsTriggerAuthToken** - Token for the Jenkins trigger configuration
127+
* **CIAdmin.AzureOrgAdminPAT** - Personal access token for the Azure DevOps configuration
128+
* **CIAdmin.AzureBlobStorageToken** - SAS token for the Azure Blob Storage
129+
* **CIAdmin.AzureAwsS3SK** - Name of the Azure DevOps organization
130+
131+
* Cluster Manager
132+
133+
* **ClusterManager.KubernetesApiToken** - Token for the Kubernetes admin user
134+
* **ClusterSettings.KubernetesAdminPassword** - Password for the Kubernetes admin user
135+
* **ClusterSettings.GrafanaAPIKey** - Password for the Grafana admin user
136+
* **ClusterSettings.MDAAWSS3AccessKey** - Password for the Prometheus admin user
137+
* **ClusterSettings.OCIRegistryPassword** - Password for the Prometheus admin user
138+
139+
* Marketplace
140+
141+
* **Marketplace.ImportCDNPassword** - Personal access token for the Marketplace admin
142+
143+
* Email
144+
145+
* **Email.SMTPPassword** - Password for the SMTP server
146+
147+
### Configuring Azure AD Workload Identity
148+
149+
Private Mendix Platform uses Azure AD Workload Identity to securely access Azure Key Vault without storing credentials. This requires creating a User-Assigned Managed Identity, granting it permissions to the Key Vault, and linking it to the Kubernetes Service Account used by the Private Mendix Platform.
150+
151+
#### Creating a User-Assigned Managed Identity
152+
153+
To create a User-Assigned Managed Identity, perform the following steps:
154+
155+
1. In the Azure Portal, search for and select **Managed Identities**.
156+
2. Click **Create**.
157+
3. Select your **Subscription** and **Resource Group**.
158+
4. Choose a **Region**.
159+
5. Enter a **Name** (for example, *PMP-KeyVault-Identity*).
160+
6. Review and click **Create**.
161+
7. Once deployed, navigate to the new identity.
162+
8. From the **Overview** page, make note of the **Client ID**. This will be needed later to configure the service account.
163+
164+
#### Grant the Managed Identity Access to Key Vault
165+
166+
To grant the Managed Identity access to the Key Vault, perform the following steps:
167+
168+
1. Navigate to the Key Vault you created earlier.
169+
2. Go to the **Access control (IAM)** section.
170+
3. Click **Add > Add role assignment**.
171+
4. Select the **Key Vault Secrets User** role. This role allows Get and List operations for secrets.
172+
5. Click **Next**.
173+
6. For **Assign access to**, select **Managed identity**.
174+
7. Click **Select members** and search for the **User-Assigned Managed Identity** you created (for example, **PMP-KeyVault-Identity**).
175+
8. Select the identity, and then click **Review + assign**.
176+
177+
#### Configuring the Federated Identity
178+
179+
To configure the federated identity, perform the following steps:
180+
181+
1. Navigate back to your User-Assigned Managed Identity (for example, **PMP-KeyVault-Identity**) in the Azure Portal.
182+
2. Go to the **Federated credentials** section.
183+
3. Click **Add credential**.
184+
4. From the **Federated credential scenario** list, select **Kubernetes accessing Azure resources**.
185+
5. Enter the following details:
186+
187+
* **Kubernetes namespace** - The namespace where your Private Mendix Platform is deployed (for example, **pmp-prod**).
188+
* **Service account name** - The name of the Kubernetes service account your PMP deployment will use (for example, **pmp-secret-accessor**).
189+
* **Issuer** - The OIDC Issuer URL of your AKS cluster.
190+
191+
Click **Add**.
192+
193+
#### Modifying the Operation Configuration
194+
195+
For more information about advanced configuration settings, see [Advanced Operator Configuration](/developerportal/deploy/private-cloud-cluster/#advanced-operator-configuration).
196+
197+
To modify the configuration, perform the following steps:
198+
199+
1. Update the configuration to [use the service token](https://docs.mendix.com/developerportal/deploy/private-cloud-cluster/#advanced-deployment-settings).
200+
201+
Set `runtimeAutomountServiceAccountToken: true` to allow Mendix app pods to get a Kubernetes Service Account token.
202+
203+
```text
204+
apiVersion: privatecloud.mendix.com/v1alpha1
205+
kind: OperatorConfiguration
206+
spec:
207+
# Optional: provide Mendix app Pods to get a Kubernetes Service Account token
208+
runtimeAutomountServiceAccountToken: true
209+
```
210+
211+
2. Add a custom pod label which informs the Operator to use workload identities. For more information, see [General Pod Labels](https://docs.mendix.com/developerportal/deploy/private-cloud-cluster/#general-pod-labels).
212+
213+
```text
214+
apiVersion: privatecloud.mendix.com/v1alpha1
215+
kind: OperatorConfiguration
216+
spec:
217+
# ...
218+
# Other configuration options values
219+
# Optional: custom pod labels
220+
customPodLabels:
221+
# Optional: general pod labels (applied to all app-related pods)
222+
general:
223+
# Example: enable Azure Workload Identity
224+
azure.workload.identity/use: "true"
225+
```
226+
227+
#### Configuring the Kubernetes Service Account
228+
229+
To enable Azure AD Workload Identity, the Kubernetes Service Account used by your Private Mendix Platform application needs specific annotations to link it to the Azure User-Assigned Managed Identity. You have two options: use a dedicated custom Service Account or use the existing default Service Account in your application's namespace.
230+
231+
Using a Custom Service Account is recommended for better isolation. This involves creating a new Service Account specifically for your Mendix application to access secrets. The default service account already exists in every Kubernetes namespace. It's simpler but provides less isolation if other applications in the same namespace also use the default Service Account.
232+
233+
To configure the Kubernetes service account, perform the following steps:
234+
235+
1. Create a Kubernetes service account with the name you specified above (for example, **pmp-secret-accessor**).
236+
2. Annotate this service account to link it to your User-Assigned Managed Identity.
237+
238+
```text
239+
kubectl -n <{Kubernetes namespace}> create serviceaccount <{environment name}>
240+
kubectl -n <{Kubernetes namespace}> annotate serviceaccount <{environment name}> privatecloud.mendix.com/environment-account=true
241+
kubectl -n <{Kubernetes namespace}> annotate serviceaccount <{environment name}> azure.workload.identity/client-id=<{managed identity client id}>
242+
```
243+
244+
3. Apply this service account to your cluster by using the following command: `kubectl apply -f <your-service-account-file>.yaml`.
245+
4. Update your Private Mendix Platform deployment YAML to use this service account:
246+
247+
```text
248+
apiVersion: apps/v1
249+
kind: Deployment
250+
metadata:
251+
name: pmp-deployment
252+
spec:
253+
template:
254+
spec:
255+
serviceAccountName: pmp-secret-accessor
256+
```
257+
258+
5. Apply the changes to your deployment by using the following command: `kubectl apply -f <your-deployment-file>.yaml`.
259+
260+
### Configuring the Credentials
261+
262+
Private Mendix Platform supports multiple secret storage backends. You can configure different types of credentials (VCS PAT, email server credentials, and so on) to use your preferred secret management solution.
263+
264+
#### Example Configuration - Azure Key Vault and VCS PAT
265+
266+
The following example shows how you can configure Private Mendix Platform to work with Azure Key Vault and VCS PAT.
267+
268+
1. Navigate to the Private Mendix Platform administrator panel.
269+
2. Go to the **Version Control** settings.
270+
3. Select the service which you want to configure (for example, GitHub, GitLab, or Bitbucket).
271+
4. Enter all required configuration details.
272+
5. In the **Credentials** section, select **Azure Key Vault**.
273+
6. Enter the **Secret Name (Vault Name)** of your Key Vault (for example, **PMP-Production-Vault**).
274+
275+
The Key name field displays the auto-generated key path in read-only format. For example, if you are using Bitbucket, the key name for Project Admin PAT would be *VCS-BitbucketProjectAdminPAT*.
276+
277+
7. Ensure that your Azure Key Vault secret's **Value** contains the correct credential value for that particular key.
278+
8. Repeat the process for other credentials as needed, ensuring you follow the naming conventions for each service.
279+
280+
### Storing the Credentials Directly in the Database
281+
282+
Instead of using the Azure Key Vault, you can still use the legacy option to store the credentials in the Private Mendix Platform database. To do this, you must select **Database** from the list of storage options, and then enter the credentials directly in an input field. The credentials are encrypted and stored in the Private Mendix Platform database.

0 commit comments

Comments
 (0)