Skip to content

Document AWS PKI WebIdentity authentication workflow #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
trond-snekvik wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document AWS PKI WebIdentity authentication workflow #486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 164 additions & 29 deletions docs/connectivity/2-credentials/1-pki/1-aws.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
title: "AWS Private CA"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

To allow Golioth to use your AWS Private Certificate Authority service as a PKI
provider for your project, you need to go through a few steps in the AWS Console
before you can configure a connection from Golioth.
Expand All @@ -12,9 +15,140 @@ documentation](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome

## Configuring AWS

To allow Golioth to securely connect directly to your AWS Private CA service,
you'll need to create an IAM policy with the required permissions, then assign
that to a user.
Golioth supports two authentication methods for connecting to AWS Private CA: [Web
Identity](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)
Comment on lines +18 to +19
Copy link
Contributor

@hasheddan hasheddan Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@trond-snekvik we use "Web Identity" throughout this documentation, but despite the fact that we choose "Web Identity" as the trusted entity type, I think it is probably more accurate (and perhaps more familiar to users) to refer to this capability as "OIDC" or "OIDC Federation". What do you think?

Copy link
Contributor Author

@trond-snekvik trond-snekvik Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AWS appear to be struggling to decide what to name it themselves, and the docs will use "OIDC federation", "OpenID Connect", "Web identity provider", "AssumeRoleWithWebIdentity", "Assume Role", "Web Identity" and "Identity Provider based authentication" depending on which docs page, console section or context you find yourself in.

(They'll also refer to it as "OIDC 联合身份验证" sometimes, as the entire documentation sidebar randomly changes to Chinese, but that probably shouldn't be a source of inspiration for our docs) image

I went with "Web Identity" as it would allow users that don't know what OIDC is to parse it as plain English -- after all, they don't really have to know or care about what OIDC is or how it works to use it in this scenario. It also overlaps more with the naming in IAM, where "OIDC" actually isn't used at all - it's just "OpenID Connect" that appears as an option for the provider type once you've entered the Add Identity Provider page.

image

"Web Identity" is the corresponding option you need to select when you (in step 3) choose the "Trusted entity type" in the Create Role page.

image

This is referred to as "Web Identity" in the console as well at this point, so we would have to go in and change it there as well. IMO it's not worthwhile to go back and change it, as this feels like a subjective "either works" type of scenario to me, but I'll let you decide.

If we really were to change it, I would actually prefer to change it to "Identity Provider based authentication", which matches the IAM language better, but I still prefer with the original choice of "Web Identity", as it works better in the console.

Copy link
Contributor

@hasheddan hasheddan Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also overlaps more with the naming in IAM, where "OIDC" actually isn't used at all - it's just "OpenID Connect" that appears as an option for the provider type once you've entered the Add Identity Provider page.

The use of "OpenID Connect" as the Identity Provider is actually more motivation to me to use OIDC (or OpenID Connect), as is the fact that the docs we are linking to here are using "OIDC Federation" as the feature name. Confusingly it also seems that AWS seems to distinguish "Web Identity" and "OIDC" as separate auth options, though then they link to OIDC federation for web identity. I suspect that the history here is that web identity was a generic term and as OIDC became standardized they moved towards using it to be more explicit.

I don't think the fact that it is currently called "Web Identity" in the console / API should influence decision here (though I certainly should have raised this earlier, my apologies for that). Really the main goal in my mind is being consistent with future providers. I could see two ways of doing that: use OIDC everywhere or use a term for each PKI provider that most closely maps to what they call it. If we use "Web Identity" here we are going with the latter, which I think is very reasonable as it is likely to better resonate with folks that are familiar with AWS, which is presumably who would be using this integration. For GCP, for example, we would use Workload Identity Federation. This is in contrast to how something like GitHub describes a similar feature (i.e. they say this how clouds work with our feature, rather than how we work with this cloud feature), but I think there are merits to it, especially based on how the PKI provider docs are organized here.

TL;DR: your arguments resonate with me, and if we are on the same page with future plans then I am good with moving forward here!

and [Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). We strongly recommend using Web Identity, as this will allow Golioth to authenticate against your Private CA without storing long term credentials.

Select your preferred authentication method below to read more about how to set up your AWS instance to allow Golioth to authenticate against it.

<Tabs
groupId="aws-auth"
defaultValue="webidentity"
values={[
{label: 'Web Identity', value: 'webidentity'},
{label: 'Access key', value: 'accesskey'},
]}>
<TabItem value="webidentity">

To allow Golioth to securely connect directly to your AWS Private CA service with
an identity provider, you'll need to create an IAM policy with the required
permissions, then assign that to a role. The role will be verified by the Golioth OpenID Connect (OIDC) Identity Provider.

### 1. Create a policy

Golioth requires a few permissions in the AWS Private CA service to be able to
authenticate devices and rotate certificates.

As none of the default policies fit the permissions requirements exactly, we'll
start by creating a new policy specifically for the integration with Golioth.

As an admin or an IAM user with the required permissions, navigate to the [IAM
Policy section](https://console.aws.amazon.com/iamv2/home#/policies), and click
**Create Policy**. Using the JSON Policy editor, add the following policy:

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"acm-pca:ListCertificateAuthorities",
"acm-pca:GetCertificateAuthorityCertificate",
"acm-pca:GetCertificate"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": ["acm-pca:IssueCertificate"],
"Resource": "arn:aws:acm-pca:*:*:certificate-authority/*",
"Condition": {
"ArnLike": {
"acm-pca:TemplateArn": [
"arn:aws:acm-pca:*:*:template/EndEntityClientAuthCertificate_APIPassthrough/V*"
]
}
}
}
]
}
```

### 2. Register ID Provider

Once we have created a policy, we'll need to register the Golioth identity provider as a trusted Identity Provider. In the [IAM
Identity Providers section](https://console.aws.amazon.com/iamv2/home#/identity_providers), click **Add Provider**.

Under Provider type, select _OpenID Connect_, then set the Provider URL to `https://api.golioth.io/oidc`, and the Audience to `sts.amazonaws.com`.

Click **Add Provider** to save the new provider.

### 3. Create a role

Next, we need to create a role that Golioth can assume when it connects to AWS.
In the [IAM Roles section](https://console.aws.amazon.com/iamv2/home#/roles),
click **Create Role**.

Under Trusted entity type, select _Web identity_, and select the Identity provider and audience you created in the previous step.

Add a condition by clicking **Add Condition**. Under **Key**, select `api.golioth.dev/oidc:sub`. Set **Condition** to `StringEquals`, and **Value** to match the following format:

```
project:<golioth-org>/<golioth-project>
```

Here, `<golioth-org>/<golioth-project>` is the organization and project slugs for your project, as seen in the Golioth Console. For instance, if the Golioth Console URI for your project is `https://console.golioth.io/org/myorg/project/myproject`, Golioth will use `project:myorg/myproject` as its token subject when connecting to AWS.

:::warning
The condition is the mechanism that allows AWS to control which Golioth
projects are allowed to connect to the Private CA. It is crucial that the
condition is included in the role definition, as failing to add this will allow
any Golioth project in any organization to connect to the Private CA.
:::

![Create a role](./assets/aws-role.png)

Click Next to move to the "Add Permissions" screen.

### 4. Attach the policy to the role

In the "Add Permissions" screen, search for the policy created in [step
1](#1-create-a-policy). Select the policy, and click **Next** to go the final
role creation page.

![Attaching the policy](./assets/aws-role-policy.png)

Finally, give the new role a name and an optional description and click **Create
Role**.

## Connecting to AWS from the Golioth Console

Once you have an AWS IAM role with the required permissions, you can configure
Golioth's connection to the AWS Private CA from the Golioth Console. Navigate to
the PKI Providers section in the sidebar, and click **Add Provider**. In the
modal window, select _AWS Private Certificate Authority_, and the correct region
for your AWS instance. Under _Authentication_, select _Web Identity_, and add the
ARN of the role you created in the AWS Console, then click **Connect**. The
provider will be added to the list of known providers, and a provider status
check will run.

AWS usually takes a couple of minutes to deploy your policy, and the status check
may report `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity
status code: 403` or a similar error while your changes are being processed.

Once everything is configured correctly and your policy is deployed, the provider
status should change to "Connected", and list the number of available certificate
authorities.

![Configured Provider](./assets/configured-webidentity-provider.png)

</TabItem>
<TabItem value="accesskey">

To allow Golioth to securely connect directly to your AWS Private CA service with
an access key, you'll need to create an IAM policy with the required permissions,
then assign that to a user.

### 1. Create a policy

Expand All @@ -30,32 +164,30 @@ Policy section](https://console.aws.amazon.com/iamv2/home#/policies), and click

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"acm-pca:ListCertificateAuthorities",
"acm-pca:GetCertificateAuthorityCertificate",
"acm-pca:GetCertificate"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"acm-pca:IssueCertificate"
],
"Resource": "arn:aws:acm-pca:*:*:certificate-authority/*",
"Condition": {
"ArnLike": {
"acm-pca:TemplateArn": [
"arn:aws:acm-pca:*:*:template/EndEntityClientAuthCertificate_APIPassthrough/V*"
]
}
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"acm-pca:ListCertificateAuthorities",
"acm-pca:GetCertificateAuthorityCertificate",
"acm-pca:GetCertificate"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": ["acm-pca:IssueCertificate"],
"Resource": "arn:aws:acm-pca:*:*:certificate-authority/*",
"Condition": {
"ArnLike": {
"acm-pca:TemplateArn": [
"arn:aws:acm-pca:*:*:template/EndEntityClientAuthCertificate_APIPassthrough/V*"
]
}
]
}
}
]
}
```

Expand Down Expand Up @@ -93,7 +225,7 @@ In the "Set Permissions" screen, select **Attach policies directly**, and search
for the policy created in [step 1](#1-create-a-policy). Select the policy, and
click **Next** to go the final user creation page.

![Attaching the AWSPrivateCAReadOnly policy](./assets/aws-policy.png)
![Attaching the policy](./assets/aws-policy.png)

Policies can either be attached to the user directly when you create it, or by
assigning the user to a user group with the required permissions.
Expand Down Expand Up @@ -124,6 +256,9 @@ If everything is configured correctly, the provider status should change to

![Configured Provider](./assets/configured-provider.png)

</TabItem>
</Tabs>

## Issuing Device Certificates

Device certificates are [End Entity
Expand Down
Binary file added docs/connectivity/2-credentials/1-pki/assets/aws-role-policy.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/connectivity/2-credentials/1-pki/assets/aws-role.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/connectivity/2-credentials/1-pki/assets/configured-webidentity-provider.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.