Document AWS PKI WebIdentity authentication workflow

[trond-snekvik]

Splits the configuration steps for setting up the AWS PKI provider based on the authentication method used.

[github-actions]

Visit the preview URL for this PR (updated for commit 448578c):

https://golioth-docs-dev--pr486-aws-oidc-thhv6xmk.web.app

_{(expires Thu, 05 Mar 2026 13:58:48 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: f53b02bdc98ce6f5593931ec4c339aa96bac84df}

[hasheddan]

@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?

[trond-snekvik]

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)

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.

"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.

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.

[hasheddan]

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!

[hasheddan]

Going ahead and approving here as I'm aligned with current direction, @trond-snekvik feel free to re-request if any thinking has changed based on conversation 👍🏻