Skip to content

Commit 9187539

Browse files
author
Keyfactor
committed
Update generated docs
1 parent 2703a7e commit 9187539

2 files changed

Lines changed: 191 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 185 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ The AWSPCA CA Gateway AnyCA Gateway REST plugin is supported by Keyfactor for K
4747
4848
## Requirements
4949

50-
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.
50+
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.
5151

5252
## Installation
5353

@@ -108,6 +108,190 @@ This integration is tested and confirmed as working for Anygateway REST 25.4 and
108108
3. Follow the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Keyfactor.htm) to add each defined Certificate Authority to Keyfactor Command and import the newly defined Certificate Templates.
109109
110110
111+
## Authentication (Access Key + Secret)
112+
113+
The CAPlugin currently supports **one** authentication method: **AWS Access Key ID + Secret Access Key**.
114+
**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***.
115+
116+
### What you need ready
117+
118+
Before configuring the CAPlugin, have the following prepared:
119+
120+
#### 1) IAMUserAccessKey and IAMUserAccessSecret
121+
- **Access Key ID** (example format: `AKIAIOSFODNN7EXAMPLE`)
122+
- **Secret Access Key** (example format: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`)
123+
124+
#### 2) A target IAM Role the connector will run as (recommended)
125+
Example:
126+
- `arn:aws:iam::123456789012:role/Keyfactor-AnyGateway-AcmPcaRole`
127+
128+
**Role expectations:**
129+
- The role must have permissions for:
130+
- **ACM PCA operations** (Issue/Get/Revoke/Describe + CA certificate chain retrieval)
131+
- **Audit report creation & status polling** (Create/Describe audit reports)
132+
- **S3 bucket access** to read/write audit report objects
133+
134+
#### 3) Permissions on the assumed role
135+
The assumed role must have permissions for the AWS services the Gateway needs. This typically includes:
136+
- `acm-pca:*` actions required for enrollment + revocation workflows
137+
- Audit report actions (`acm-pca:CreateCertificateAuthorityAuditReport`, `acm-pca:DescribeCertificateAuthorityAuditReport`)
138+
- S3 bucket and object access for the audit report destination bucket
139+
140+
**See the example IAM policies below in this README section**
141+
142+
#### 4) Region
143+
Know the **AWS region** the connector should use (for service endpoints), e.g.:
144+
- `us-east-1`
145+
146+
> Region must match the region of your **ACM Private CA**.
147+
148+
#### 5) CA ARN
149+
Have the **Certificate Authority ARN** for the PCA you want to integrate with.
150+
151+
Example format:
152+
- `arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>`
153+
154+
Example:
155+
- `arn:aws:acm-pca:us-east-2:123456789012:certificate-authority/11111111-2222-3333-4444-555555555555`
156+
157+
#### 6) S3 Bucket
158+
Choose an S3 bucket to store / retrieve ACM PCA audit reports.
159+
160+
You should have:
161+
- **Bucket name** (example: `keyfactor-acmpca-audit-reports`, not the full bucket ARN!)
162+
163+
164+
> The role needs `s3:ListBucket` / `s3:GetBucketLocation` at the bucket ARN, and `s3:GetObject` / `s3:PutObject` on the object ARN pattern.
165+
166+
#### 7) PCA Root Cert
167+
Download the **PCA root certificate** from AWS and have it ready to import into the Gateway **in `.pem` format**.
168+
169+
### Enabling all this in the Gateway Configuration Portal
170+
171+
#### 1) Register the Gateway CA and upload the Root CA certificate
172+
1. Navigate to **Gateway Registration**.
173+
2. Upload the **Root CA Certificate** you downloaded earlier (PEM).
174+
175+
#### 2) Configure the CA connection settings
176+
1. Navigate to **CAConnection**.
177+
2. Populate:
178+
- `RoleArn` (example: `arn:aws:iam::123456789012:role/Keyfactor-AnyGateway-AcmPcaRole`)
179+
- `Region` (example: `us-east-2`)
180+
- `CAArn` (example: `arn:aws:acm-pca:us-east-2:123456789012:certificate-authority/11111111-2222-3333-4444-555555555555`)
181+
- `S3Bucket` (example: `keyfactor-acmpca-audit-reports`)
182+
- `IAMUserAccessKey` (example: `AKIA...`)
183+
- `IAMUserAccessSecret` (example: `wJalrXU...`)
184+
185+
3. Set these auth toggles:
186+
- `UseDefaultSdkAuth` = `false`
187+
- `UseOAuth` = `false`
188+
- `UseIAM` = `true`
189+
190+
---
191+
192+
### Example IAM policies for the assumed role
193+
194+
The following examples are intended as **copy/adapt templates**.
195+
196+
#### Example 1: Minimal PCA issuance/retrieval/revocation
197+
198+
```json
199+
{
200+
"Version": "2012-10-17",
201+
"Statement": [
202+
{
203+
"Sid": "PrivateCABasicOps",
204+
"Effect": "Allow",
205+
"Action": [
206+
"acm-pca:IssueCertificate",
207+
"acm-pca:GetCertificate",
208+
"acm-pca:RevokeCertificate",
209+
"acm-pca:DescribeCertificateAuthority",
210+
"acm-pca:GetCertificateAuthorityCertificate"
211+
],
212+
"Resource": "arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
213+
}
214+
]
215+
}
216+
```
217+
218+
#### Example 2: PCA issuance + audit reports + S3 audit bucket access
219+
220+
```json
221+
{
222+
"Version": "2012-10-17",
223+
"Statement": [
224+
{
225+
"Sid": "PrivateCAIssueAndFetch",
226+
"Effect": "Allow",
227+
"Action": [
228+
"acm-pca:IssueCertificate",
229+
"acm-pca:GetCertificate",
230+
"acm-pca:DescribeCertificateAuthority",
231+
"acm-pca:GetCertificateAuthorityCertificate"
232+
],
233+
"Resource": [
234+
"arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
235+
]
236+
},
237+
{
238+
"Sid": "PrivateCAAuditReportOps",
239+
"Effect": "Allow",
240+
"Action": [
241+
"acm-pca:CreateCertificateAuthorityAuditReport",
242+
"acm-pca:DescribeCertificateAuthorityAuditReport"
243+
],
244+
"Resource": "*"
245+
},
246+
{
247+
"Sid": "AuditReportBucketAccessForCaller",
248+
"Effect": "Allow",
249+
"Action": [
250+
"s3:GetBucketLocation",
251+
"s3:ListBucket"
252+
],
253+
"Resource": "arn:aws:s3:::<audit-bucket-name>"
254+
},
255+
{
256+
"Sid": "AuditReportObjectAccessForCaller",
257+
"Effect": "Allow",
258+
"Action": [
259+
"s3:GetObject",
260+
"s3:PutObject"
261+
],
262+
"Resource": "arn:aws:s3:::<audit-bucket-name>/*"
263+
}
264+
]
265+
}
266+
```
267+
---
268+
269+
### Example policy for bucket
270+
```json
271+
{
272+
"Version": "2012-10-17",
273+
"Statement": [
274+
{
275+
"Sid": "AllowACMPCAWriteAuditReports",
276+
"Effect": "Allow",
277+
"Principal": {
278+
"Service": "acm-pca.amazonaws.com"
279+
},
280+
"Action": "s3:PutObject",
281+
"Resource": "arn:aws:s3:::<audit-bucket-name>/*",
282+
"Condition": {
283+
"StringEquals": {
284+
"aws:SourceAccount": "<account-id>"
285+
},
286+
"ArnLike": {
287+
"aws:SourceArn": "arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
288+
}
289+
}
290+
}
291+
]
292+
}
293+
```
294+
111295
112296
## License
113297

‎docsource/configuration.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ Download the **PCA root certificate** from AWS and have it ready to import into
8787

8888
---
8989

90-
### Example IAM policies for the assumed role
90+
### Example IAM policies for the assumed role
9191

9292
The following examples are intended as **copy/adapt templates**.
9393

@@ -189,3 +189,8 @@ The following examples are intended as **copy/adapt templates**.
189189
]
190190
}
191191
```
192+
193+
## Gateway Registration
194+
195+
TODO Gateway Registration is a required section
196+

0 commit comments

Comments
 (0)