Skip to content

Commit 92c7c88

Browse files
trond-snekviktrond-snekvik
committed
Add external PKI provider documentation
Splits the PKI documentation out into multiple pages, adding documentation for how to set up AWS as an external PKI provider. The local PKI guide is also split into a separate page, which gets linked to from the main PKI page, alongside a link to the AWS page. Signed-off-by: Trond Snekvik <[email protected]>
1 parent 51c326b commit 92c7c88

File tree

8 files changed

+396
-212
lines changed

8 files changed

+396
-212
lines changed

‎docs/connectivity/2-credentials/1-pki.md‎

Lines changed: 0 additions & 212 deletions
This file was deleted.

‎docs/connectivity/2-credentials/1-pki/1-aws.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: "AWS Private CA"
3+
---
4+
5+
To allow Golioth to use your AWS Private Certificate Authority service as a PKI
6+
provider for your project, you need to go through a few steps in the AWS Console
7+
before you can configure a connection from Golioth.
8+
9+
For information about how you can establish a CA in AWS Private CA and issue
10+
end-entity certificates, please refer to [the official AWS
11+
documentation](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html).
12+
13+
## Configuring AWS
14+
15+
To allow Golioth to securely connect directly to your AWS Private CA service,
16+
you'll need to create an IAM policy with the required permissions, then assign
17+
that to a user.
18+
19+
### 1. Create a policy
20+
21+
Golioth requires a few permissions in the AWS Private CA service to be able to
22+
authenticate devices and rotate certificates.
23+
24+
As none of the default policies fit the permissions requirements exactly, we'll
25+
start by creating a new policy specifically for the integration with Golioth.
26+
27+
As an admin or an IAM user with the required permissions, navigate to the [IAM
28+
Policy section](https://console.aws.amazon.com/iamv2/home#/policies), and click
29+
**Create Policy**. Using the JSON Policy editor, add the following policy:
30+
31+
```json
32+
{
33+
"Version": "2012-10-17",
34+
"Statement": [
35+
{
36+
"Effect": "Allow",
37+
"Action": [
38+
"acm-pca:ListCertificateAuthorities",
39+
"acm-pca:GetCertificateAuthorityCertificate",
40+
"acm-pca:GetCertificate"
41+
],
42+
"Resource": "*"
43+
},
44+
{
45+
"Effect": "Allow",
46+
"Action": [
47+
"acm-pca:IssueCertificate"
48+
],
49+
"Resource": "arn:aws:acm-pca:*:*:certificate-authority/*",
50+
"Condition": {
51+
"ArnLike": {
52+
"acm-pca:TemplateArn": [
53+
"arn:aws:acm-pca:*:*:template/EndEntityClientAuthCertificate_APIPassthrough/V*"
54+
]
55+
}
56+
}
57+
}
58+
]
59+
}
60+
```
61+
62+
The first statement in this policy enables Golioth to iterate through your
63+
certificate authorities, and retrieve their certificates. The second statement
64+
allows Golioth to issue device certificates using the
65+
[`EndEntityClientAuthCertificate_APIPassthrough/V1`
66+
template](https://docs.aws.amazon.com/privateca/latest/userguide/template-definitions.html#EndEntityClientAuthCertificate_APIPassthrough).
67+
68+
:::tip
69+
If you do not need certificate rotation capabilities, the
70+
**AWSPrivateCAReadOnly** standard policy can be used instead.
71+
:::
72+
73+
Save this policy with a recognizable name and description.
74+
75+
### 2. Create an IAM user
76+
77+
Golioth connects to your AWS Private CA service as an IAM user. Although it's
78+
possible for Golioth to authenticate as an existing user, we strongly recommend
79+
establishing a dedicated user to maintain a narrow set of permissions.
80+
81+
As an admin or an IAM user with the required permissions, navigate to the [IAM
82+
User Management Dashboard](https://console.aws.amazon.com/iamv2/home#/users) in
83+
the AWS Console, and click **Create User**.
84+
85+
![Create a user](./assets/aws-user.png)
86+
87+
Pick a recognizable user name, and click **Next** to go to the permissions
88+
screen.
89+
90+
### 3. Attach the policy to the user
91+
92+
In the "Set Permissions" screen, select **Attach policies directly**, and search
93+
for the policy created in [step 1](#1-create-a-policy). Select the policy, and
94+
click **Next** to go the final user creation page.
95+
96+
![Attaching the AWSPrivateCAReadOnly policy](./assets/aws-policy.png)
97+
98+
Policies can either be attached to the user directly when you create it, or by
99+
assigning the user to a user group with the required permissions.
100+
101+
### 4. Create an access key
102+
103+
Once the user is created with the required permissions, you'll need to create an
104+
access key that Golioth can use to authenticate as that user.
105+
106+
Follow [the AWS
107+
documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html)
108+
for instructions on how to create an access key for an IAM user. Note that the
109+
secret access key is only available during the creation process, and must be
110+
saved before leaving the page.
111+
112+
## Connecting to AWS from the Golioth Console
113+
114+
Once you have an AWS IAM user with the required permissions, you can configure
115+
Golioth's connection to the AWS Private CA from the Golioth Console. Navigate to
116+
the PKI Providers section in the sidebar, and click **Add Provider**. In the
117+
modal window, select _AWS Private Certificate Authority_, and the correct region
118+
for your AWS instance. Add the Access Key ID and Secret Access Key that you
119+
created in the AWS Console, and click **Connect**. The provider will be added to
120+
the list of known providers, and a provider status check will run.
121+
122+
If everything is configured correctly, the provider status should change to
123+
"Connected", and list the number of available certificate authorities.
124+
125+
![Configured Provider](./assets/configured-provider.png)
126+
127+
## Issuing Device Certificates
128+
129+
Device certificates are [End Entity
130+
Certificates](https://docs.aws.amazon.com/privateca/latest/userguide/PcaIssueCert.html)
131+
in AWS.
132+
133+
As outlined in the [Certificate ID section](./README.md#certificate-ids),
134+
the device certificate subject needs to include the following attributes:
135+
136+
- `Organization`: the device's project ID
137+
- `CommonName`: a unique device certificate ID
138+
139+
Other subject attributes are ignored.
140+
141+
When performing certificate rotation, Golioth will submit certificate signing
142+
requests to the AWS Private CA with the
143+
[`EndEntityClientAuthCertificate_APIPassthrough/V1`
144+
template](https://docs.aws.amazon.com/privateca/latest/userguide/template-definitions.html#EndEntityClientAuthCertificate_APIPassthrough).
145+
The request will be submitted with an API passthrough value containing the
146+
subject attributes above.

0 commit comments

Comments
 (0)