Skip to content

Commit e6f6c47

Browse files
NicoletaComanNicoletaComan
authored
Merge pull request #9905 from mendix/kk-pmp-aws
PMP - AWS Secret Manager
2 parents 53fd651 + ac370ac commit e6f6c47

File tree

1 file changed

+310
-0
lines changed

1 file changed

+310
-0
lines changed

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

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
---
2+
title: "Configuring External Secret Management with AWS Secret Manager"
3+
url: /private-mendix-platform/configure-aws-secret-manager/
4+
description: "Documents the configuration of AWS Secret Manager 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 [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) 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 AWS Secrets Manager, credentials are instead stored in AWS Secrets Manager and accessed securely via IAM roles for improved security, centralized management, and compliance with enterprise security policies. This document describes how you can configure AWS Secrets Manager integration for your Private Mendix Platform project.
11+
12+
## Prerequisites
13+
14+
Before configuring AWS Secrets Manager integration, prepare the following:
15+
16+
* An AWS account with appropriate permissions to create and manage secrets
17+
* IAM permissions to create roles and policies for AWS Secrets Manager access
18+
* Access to the PPrivate Mendix Platform project admin panel with administrative privileges
19+
* Basic knowledge of AWS services, IAM roles, and Kubernetes (if using EKS deployment)
20+
* An existing EKS cluster (if your PMP deployment runs on Kubernetes)
21+
22+
## Configuring External Secret Management
23+
24+
To configure external secret management, you must first create a secret in AWS Secret Manager, configure the IAM permissions and service accounts, 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 AWS Secret Manager, perform the following steps:
29+
30+
1. Log in to the AWS Management Console.
31+
2. Navigate to the **AWS Secrets Manager** service.
32+
3. Click **"Store a new secret**.
33+
4. Choose the type of secret as **Other type of secret**.
34+
5. Select the **JSON** format for storing secrets.
35+
6. Enter the key-value pairs for your secrets using the Private Mendix Platform [naming convention](#naming-convention).
36+
7. Click **Next**.
37+
8. Enter a descriptive name for your secret, for example, *PMP-Production-Credentials*.
38+
9. Optional: Add a description and tags for better organization and compliance tracking.
39+
10. Click **Next** to review your secret settings.
40+
11. Review the details and click **Store** to create the secret.
41+
42+
{{% alert color="info" %}}
43+
Make note of the secret name and ARN. You will need these when configuring Private Mendix Platform to use the secret.
44+
{{% /alert %}}
45+
46+
#### Naming Convention for Key Properties {#naming-convention}
47+
48+
When creating a property to use as a key for external secret storage, use the following naming conventions:
49+
50+
* All the key names are read-only. You should not change them.
51+
* Create the keys in the external secret storage with the same names as in the Private Mendix Platform configuration.
52+
* The mappings are as follows:
53+
54+
* VCS
55+
56+
* Bitbucket
57+
58+
* **VCS.BitbucketProjectAdminPAT** - Personal access token for the Bitbucket project admin
59+
* **VCS.BitbucketAdminPassword** - Password for the Bitbucket admin user
60+
61+
* GitLab
62+
63+
* **VCS.GitlabGroupOwnerPAT** - Personal access token for the GitLab group owner
64+
* **VCS.GitlabAdminPAT** - Personal access token for the GitLab admin
65+
66+
* GitHub
67+
68+
* **VCS.GithubOrgOwnerPAT** - Personal access token for the GitHub organization owner
69+
* **VCS.GithubAdminPAT** - Personal access token for the GitHub admin
70+
* **VCS.GithubEnterpriseClientSecret** - Client secret for the GitHub Enterprise app
71+
72+
* Azure
73+
74+
* **VCS.AzureDevOpsOrgAdminPAT** - Personal access token for the Azure DevOps organization owner
75+
* **VCS.AzureAuthSecret** - Currently unused
76+
77+
* Kubernetes Build Settings
78+
79+
* BuildPackage
80+
81+
* fileServerBasic
82+
83+
* **BuildPackage.FileBasicAuthPassword** - Password for the file server
84+
85+
* AwsAKSK
86+
87+
* **BuildPackage.AwsSecretAccessKey** - AWS secret access key for the file server
88+
89+
* RuntimeBaseImage
90+
91+
* privateRegistry
92+
93+
* **RuntimeBaseImage.PrivateRegistryPassword** - Base image for the runtime
94+
95+
* S3compatibleAccessKey
96+
97+
* **RuntimeBaseImage.S3CompatibleAccessKey** - S3-compatible access key for the base image
98+
99+
* MDAStorage
100+
101+
* fileServerBasic
102+
103+
* **MDAStorage.FileBasicAuthPassword** - Password for the file server
104+
105+
* awsAKSK
106+
107+
* **MDAStorage.AwsSecretAccessKey** - AWS secret access key for the MDA storage
108+
109+
* OCIRegistry
110+
111+
* privateRegistry
112+
113+
* **OCIRegistry.PrivateRegistryPassword** - Password for the private registry
114+
115+
* S3compatibleAccessKey
116+
117+
* **OCIRegistry.S3CompatibleAccessKey** - S3 compatible access key for the OCI registry
118+
119+
* Build Cluster Settings
120+
121+
* **kubernetesConfigureToken**
122+
* **BuildCluster.KubernetesConfigureToken** - Token for the Kubernetes cluster configuration
123+
* **JenkinsConfigureAPIToken**
124+
* **CIAdmin.JenkinsConfigureAPIToken** - Token for the Jenkins configuration
125+
* **CIAdmin.JenkinsTriggerAuthToken** - Token for the Jenkins trigger configuration
126+
* **CIAdmin.AzureOrgAdminPAT** - Personal access token for the Azure DevOps configuration
127+
* **CIAdmin.AzureBlobStorageToken** - SAS token for the Azure Blob Storage
128+
* **CIAdmin.AzureAwsS3SK** - Name of the Azure DevOps organization
129+
130+
* Cluster Manager
131+
132+
* **ClusterManager.KubernetesApiToken** - Token for the Kubernetes admin user
133+
* **ClusterSettings.KubernetesAdminPassword** - Password for the Kubernetes admin user
134+
* **ClusterSettings.GrafanaAPIKey** - Password for the Grafana admin user
135+
* **ClusterSettings.MDAAWSS3AccessKey** - Password for the Prometheus admin user
136+
* **ClusterSettings.OCIRegistryPassword** - Password for the Prometheus admin user
137+
138+
* Marketplace
139+
140+
* **Marketplace.ImportCDNPassword** - Personal access token for the Marketplace admin
141+
142+
* Email
143+
144+
* **Email.SMTPPassword** - Password for the SMTP server
145+
146+
The following is a JSON template. Copy this template into your secret, and set the values that you want to use. Leave those you do not want to use empty.
147+
148+
```json
149+
{
150+
"VCS": {
151+
"BitbucketProjectAdminPAT": "",
152+
"BitbucketAdminPassword": "",
153+
"GitlabGroupOwnerPAT": "",
154+
"GitlabAdminPAT": "",
155+
"GithubOrgOwnerPAT": "",
156+
"GithubAdminPAT": "",
157+
"GithubEnterpriseClientSecret": "",
158+
"AzureDevOpsOrgAdminPAT": "",
159+
"AzureAuthSecret": ""
160+
},
161+
"BuildPackage": {
162+
"FileBasicAuthPassword": "",
163+
"AwsSecretAccessKey": ""
164+
},
165+
"RuntimeBaseImage": {
166+
"PrivateRegistryPassword": "",
167+
"S3CompatibleAccessKey": ""
168+
},
169+
"MDAStorage": {
170+
"FileBasicAuthPassword": "",
171+
"AwsSecretAccessKey": ""
172+
},
173+
"OCIRegistry": {
174+
"PrivateRegistryPassword": "",
175+
"S3CompatibleAccessKey": ""
176+
},
177+
"BuildCluster": {
178+
"KubernetesConfigureToken": ""
179+
},
180+
"CIAdmin": {
181+
"JenkinsConfigureAPIToken": "",
182+
"JenkinsTriggerAuthToken": "",
183+
"AzureOrgAdminPAT": "",
184+
"AzureBlobStorageToken": "",
185+
"AzureAwsS3SK": ""
186+
},
187+
"ClusterManager": {
188+
"KubernetesApiToken": ""
189+
},
190+
"ClusterSettings": {
191+
"KubernetesAdminPassword": "",
192+
"GrafanaAPIKey": "",
193+
"MDAAWSS3AccessKey": "",
194+
"OCIRegistryPassword": ""
195+
},
196+
"Marketplace": {
197+
"ImportCDNPassword": ""
198+
},
199+
"Email": {
200+
"SMTPPassword": ""
201+
}
202+
}
203+
```
204+
205+
### Configuring IAM Permissions and Service Accounts
206+
207+
Private Mendix Platform uses [IRSA (IAM Roles for Service Accounts)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to securely access AWS Secrets Manager without storing AWS credentials. This provides a secure, auditable way to access secrets. To enable this functionality, you must first create an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), and then configure the service account.
208+
209+
#### Creating an IAM Role
210+
211+
To create an IAM role, perform the following steps:
212+
213+
1. Navigate to the IAM service in the AWS Management Console.
214+
2. Click **Create role** and configure the following:
215+
216+
* **Trusted entity** - Select **Web identity**
217+
* **Identity provider** - Choose your EKS cluster's OIDC provider
218+
* **Audience** - `sts.amazonaws.com`
219+
220+
3. Click **Next** to proceed to permissions.
221+
4. Create or attach a custom policy with the following permissions:
222+
223+
```yaml
224+
{
225+
"Version": "2012-10-17",
226+
"Statement": [
227+
{
228+
"Effect": "Allow",
229+
"Action": [
230+
"secretsmanager:GetSecretValue",
231+
"secretsmanager:DescribeSecret"
232+
],
233+
"Resource": "arn:aws:secretsmanager:*:*:secret:PMP-*"
234+
}
235+
]
236+
}
237+
```
238+
239+
5. Name the role, for example, *PMP-SecretsManager-Role*.
240+
6. Make a note of the **Role ARN** for the next steps.
241+
242+
#### Configuring the EKS Service Account
243+
244+
To configure the EKS service account, perform the following steps:
245+
246+
1. Navigate to your EKS cluster in the AWS Management Console.
247+
2. In the **Configuration** tab, select **Service accounts**.
248+
3. Click **Create** to create a new service account.
249+
4. Enter a name for the service account, for example, *pmp-secrets-access*.
250+
5. Under **IAM role**, select the role you created above.
251+
6. Click **Create** to finalize the service account creation.
252+
7. Update your Kubernetes deployment to use the new service account by adding the following annotation to your deployment YAML:
253+
254+
```text
255+
apiVersion: apps/v1
256+
kind: Deployment
257+
metadata:
258+
name: pmp-deployment
259+
annotations:
260+
eks.amazonaws.com/role-arn: arn:aws:iam::<your-account-id>:role/pmp-secret-access
261+
spec:
262+
template:
263+
spec:
264+
serviceAccountName: pmp-secret-access
265+
```
266+
267+
8. Apply the changes to your Kubernetes cluster using the following command: `kubectl apply -f <your-deployment-file>.yaml`.
268+
9. Verify that the service account is correctly configured by checking the logs of your application.
269+
270+
It should be able to access the secrets stored in AWS Secret Manager.
271+
272+
### Configuring the Credentials
273+
274+
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.
275+
276+
#### Example Configuration - AWS Secrets Manager and VCS PAT
277+
278+
The following example shows how you can configure Private Mendix Platform to work with AWS Secrets Manager and VCS PAT.
279+
280+
1. Navigate to the Private Mendix Platform administrator panel.
281+
2. Go to the **Version Control** settings.
282+
3. Select the service which you want to configure (for example, GitHub, GitLab, or Bitbucket).
283+
4. Enter all required configuration details.
284+
5. In the **Credentials** section, select **AWS Secrets Manager**.
285+
6. Enter the name of the secret that you created earlier, for example, *PMP-Credentials*.
286+
287+
The **Key name** field displays the auto-generated key path in read-only format.
288+
289+
7. Ensure that your AWS Secrets Manager secret contains the credential using the proper key structure.
290+
291+
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.
292+
293+
The secret template contains a sample key structure which you can use:
294+
295+
```text
296+
{ //...other keys
297+
"VCS": {
298+
// ...other keys
299+
"BitbucketProjectAdminPAT": "your-bitbucket-pat",
300+
// ...other keys
301+
},
302+
// ...other keys
303+
}
304+
```
305+
306+
8. Repeat the process for other credentials as needed, ensuring you follow the naming conventions for each service.
307+
308+
## Storing the Credentials Directly in the Database
309+
310+
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)