Skip to content

Commit 307410e

Browse files
mkachkmkachk
committed
Improved readme.
1 parent ac1a8e4 commit 307410e

1 file changed

Lines changed: 182 additions & 1 deletion

File tree

‎docsource/configuration.md‎

Lines changed: 182 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,188 @@ This integration allows for the Synchronization, Enrollment, and Revocation of c
44

55
## Requirements
66

7-
This integration is tested and confirmed as working for Anygateway REST 25.4 and above. Notice: Keyfactor Anygateway REST 25.4 requires the use of .Net 8.
7+
This integration is tested and confirmed as working for Anygateway REST 24.4 and above. Notice: Keyfactor Anygateway REST 24.4 requires the use of .Net 8.
88

9+
## Authentication (Access Key + Secret)
910

11+
The CAPlugin currently supports **one** authentication method: **AWS Access Key ID + Secret Access Key**.
12+
**OAuth** and **Default SDK authentication** will be enabled in later updates. There is functionality present via the **Keyfactor AWS Authentication** library, but these alternate methods are currently ***untested***.
1013

14+
### What you need ready
15+
16+
Before configuring the CAPlugin, have the following prepared:
17+
18+
#### 1) IAMUserAccessKey and IAMUserAccessSecret
19+
- **Access Key ID** (example format: `AKIAIOSFODNN7EXAMPLE`)
20+
- **Secret Access Key** (example format: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`)
21+
22+
#### 2) A target IAM Role the connector will run as (recommended)
23+
Example:
24+
- `arn:aws:iam::123456789012:role/Keyfactor-AnyGateway-AcmPcaRole`
25+
26+
**Role expectations:**
27+
- The role must have permissions for:
28+
- **ACM PCA operations** (Issue/Get/Revoke/Describe + CA certificate chain retrieval)
29+
- **Audit report creation & status polling** (Create/Describe audit reports)
30+
- **S3 bucket access** to read/write audit report objects
31+
32+
#### 3) Permissions on the assumed role
33+
The assumed role must have permissions for the AWS services the Gateway needs. This typically includes:
34+
- `acm-pca:*` actions required for enrollment + revocation workflows
35+
- Audit report actions (`acm-pca:CreateCertificateAuthorityAuditReport`, `acm-pca:DescribeCertificateAuthorityAuditReport`)
36+
- S3 bucket and object access for the audit report destination bucket
37+
38+
**See the example IAM policies below in this README section**
39+
40+
#### 4) Region
41+
Know the **AWS region** the connector should use (for service endpoints), e.g.:
42+
- `us-east-1`
43+
44+
> Region must match the region of your **ACM Private CA**.
45+
46+
#### 5) CA ARN
47+
Have the **Certificate Authority ARN** for the PCA you want to integrate with.
48+
49+
Example format:
50+
- `arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>`
51+
52+
Example:
53+
- `arn:aws:acm-pca:us-east-2:123456789012:certificate-authority/11111111-2222-3333-4444-555555555555`
54+
55+
#### 6) S3 Bucket
56+
Choose an S3 bucket to store / retrieve ACM PCA audit reports.
57+
58+
You should have:
59+
- **Bucket name** (example: `keyfactor-acmpca-audit-reports`, not the full bucket ARN!)
60+
61+
62+
> The role needs `s3:ListBucket` / `s3:GetBucketLocation` at the bucket ARN, and `s3:GetObject` / `s3:PutObject` on the object ARN pattern.
63+
64+
#### 7) PCA Root Cert
65+
Download the **PCA root certificate** from AWS and have it ready to import into the Gateway **in `.pem` format**.
66+
67+
### Enabling all this in the Gateway Configuration Portal
68+
69+
#### 1) Register the Gateway CA and upload the Root CA certificate
70+
1. Navigate to **Gateway Registration**.
71+
2. Upload the **Root CA Certificate** you downloaded earlier (PEM).
72+
73+
#### 2) Configure the CA connection settings
74+
1. Navigate to **CAConnection**.
75+
2. Populate:
76+
- `RoleArn` (example: `arn:aws:iam::123456789012:role/Keyfactor-AnyGateway-AcmPcaRole`)
77+
- `Region` (example: `us-east-2`)
78+
- `CAArn` (example: `arn:aws:acm-pca:us-east-2:123456789012:certificate-authority/11111111-2222-3333-4444-555555555555`)
79+
- `S3Bucket` (example: `keyfactor-acmpca-audit-reports`)
80+
- `IAMUserAccessKey` (example: `AKIA...`)
81+
- `IAMUserAccessSecret` (example: `wJalrXU...`)
82+
83+
3. Set these auth toggles:
84+
- `UseDefaultSdkAuth` = `false`
85+
- `UseOAuth` = `false`
86+
- `UseIAM` = `true`
87+
88+
---
89+
90+
### Example IAM policies for the assumed role
91+
92+
The following examples are intended as **copy/adapt templates**.
93+
94+
#### Example 1: Minimal PCA issuance/retrieval/revocation
95+
96+
```json
97+
{
98+
"Version": "2012-10-17",
99+
"Statement": [
100+
{
101+
"Sid": "PrivateCABasicOps",
102+
"Effect": "Allow",
103+
"Action": [
104+
"acm-pca:IssueCertificate",
105+
"acm-pca:GetCertificate",
106+
"acm-pca:RevokeCertificate",
107+
"acm-pca:DescribeCertificateAuthority",
108+
"acm-pca:GetCertificateAuthorityCertificate"
109+
],
110+
"Resource": "arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
111+
}
112+
]
113+
}
114+
```
115+
116+
#### Example 2: PCA issuance + audit reports + S3 audit bucket access
117+
118+
```json
119+
{
120+
"Version": "2012-10-17",
121+
"Statement": [
122+
{
123+
"Sid": "PrivateCAIssueAndFetch",
124+
"Effect": "Allow",
125+
"Action": [
126+
"acm-pca:IssueCertificate",
127+
"acm-pca:GetCertificate",
128+
"acm-pca:DescribeCertificateAuthority",
129+
"acm-pca:GetCertificateAuthorityCertificate"
130+
],
131+
"Resource": [
132+
"arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
133+
]
134+
},
135+
{
136+
"Sid": "PrivateCAAuditReportOps",
137+
"Effect": "Allow",
138+
"Action": [
139+
"acm-pca:CreateCertificateAuthorityAuditReport",
140+
"acm-pca:DescribeCertificateAuthorityAuditReport"
141+
],
142+
"Resource": "*"
143+
},
144+
{
145+
"Sid": "AuditReportBucketAccessForCaller",
146+
"Effect": "Allow",
147+
"Action": [
148+
"s3:GetBucketLocation",
149+
"s3:ListBucket"
150+
],
151+
"Resource": "arn:aws:s3:::<audit-bucket-name>"
152+
},
153+
{
154+
"Sid": "AuditReportObjectAccessForCaller",
155+
"Effect": "Allow",
156+
"Action": [
157+
"s3:GetObject",
158+
"s3:PutObject"
159+
],
160+
"Resource": "arn:aws:s3:::<audit-bucket-name>/*"
161+
}
162+
]
163+
}
164+
```
165+
---
166+
167+
### Example policy for bucket
168+
```json
169+
{
170+
"Version": "2012-10-17",
171+
"Statement": [
172+
{
173+
"Sid": "AllowACMPCAWriteAuditReports",
174+
"Effect": "Allow",
175+
"Principal": {
176+
"Service": "acm-pca.amazonaws.com"
177+
},
178+
"Action": "s3:PutObject",
179+
"Resource": "arn:aws:s3:::<audit-bucket-name>/*",
180+
"Condition": {
181+
"StringEquals": {
182+
"aws:SourceAccount": "<account-id>"
183+
},
184+
"ArnLike": {
185+
"aws:SourceArn": "arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
186+
}
187+
}
188+
}
189+
]
190+
}
191+
```

0 commit comments

Comments
 (0)