Skip to content

Commit bf15318

Browse files
katarzyna-koltun-mxkatarzyna-koltun-mx
committed
PMP - azure key vault
1 parent de8b1f1 commit bf15318

File tree

2 files changed

+252
-2
lines changed

2 files changed

+252
-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: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
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 a secret, 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. Navigate to the IAM service in the AWS Management Console.
156+
2. Click **Create role** and configure the following:
157+
158+
* **Trusted entity** - Select **Web identity**
159+
* **Identity provider** - Choose your EKS cluster's OIDC provider
160+
* **Audience** - `sts.amazonaws.com`
161+
162+
3. Click **Next** to proceed to permissions.
163+
4. Create or attach a custom policy with the following permissions:
164+
165+
```yaml
166+
{
167+
"Version": "2012-10-17",
168+
"Statement": [
169+
{
170+
"Effect": "Allow",
171+
"Action": [
172+
"secretsmanager:GetSecretValue",
173+
"secretsmanager:DescribeSecret"
174+
],
175+
"Resource": "arn:aws:secretsmanager:*:*:secret:PMP-*"
176+
}
177+
]
178+
}
179+
```
180+
181+
5. Name the role, for example, *PMP-SecretsManager-Role*.
182+
6. Make a note of the **Role ARN** for the next steps.
183+
184+
#### Configuring the EKS Service Account
185+
186+
To configure the EKS service account, perform the following steps:
187+
188+
1. Navigate to your EKS cluster in the AWS Management Console.
189+
2. In the **Configuration** tab, select **Service accounts**.
190+
3. Click **Create** to create a new service account.
191+
4. Enter a name for the service account, for example, *pmp-secrets-access*.
192+
5. Under **IAM role**, select the role you created above.
193+
6. Click **Create** to finalize the service account creation.
194+
7. Update your Kubernetes deployment to use the new service account by adding the following annotation to your deployment YAML:
195+
196+
```text
197+
apiVersion: apps/v1
198+
kind: Deployment
199+
metadata:
200+
name: pmp-deployment
201+
annotations:
202+
eks.amazonaws.com/role-arn: arn:aws:iam::<your-account-id>:role/pmp-secret-access
203+
spec:
204+
template:
205+
spec:
206+
serviceAccountName: pmp-secret-access
207+
```
208+
209+
8. Apply the changes to your Kubernetes cluster using the following command: `kubectl apply -f <your-deployment-file>.yaml`.
210+
9. Verify that the service account is correctly configured by checking the logs of your application.
211+
212+
It should be able to access the secrets stored in AWS Secret Manager.
213+
214+
### Configuring the Credentials
215+
216+
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.
217+
218+
#### Example Configuration - AWS Secrets Manager and VCS PAT
219+
220+
The following example shows how you can configure Private Mendix Platform to work with AWS Secrets Manager and VCS PAT.
221+
222+
1. Navigate to the Private Mendix Platform administrator panel.
223+
2. Go to the **Version Control** settings.
224+
3. Select the service which you want to configure (for example, GitHub, GitLab, or Bitbucket).
225+
4. Enter all required configuration details.
226+
5. In the **Credentials** section, select **AWS Secrets Manager**.
227+
6. Enter the name of the secret that you created earlier, for example, *PMP-Credentials*.
228+
229+
The **Key name** field displays the auto-generated key path in read-only format.
230+
231+
7. Ensure that your AWS Secrets Manager secret contains the credential using the proper key structure.
232+
233+
For example, if you are using Bitbucket, the key name for `Project Admin PAT` would be `VCS.BitbucketProjectAdminPAT`, where `VCS` is the module name, and `BitbucketProjectAdminPAT` is the credential name.
234+
235+
The secret template contains a sample key structure which you can use:
236+
237+
```text
238+
{ //...other keys
239+
"VCS": {
240+
// ...other keys
241+
"BitbucketProjectAdminPAT": "your-bitbucket-pat",
242+
// ...other keys
243+
},
244+
// ...other keys
245+
}
246+
```
247+
248+
8. Repeat the process for other credentials as needed, ensuring you follow the naming conventions for each service.
249+
250+
## Storing the Credentials Directly in the Database
251+
252+
Instead of using the AWS Secret Manager, 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 storage options dropdown, 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)