HashiCorp Cloud Platform
Federate workload identity with other OIDC providers
This page describes how to set up workload identity federation to authenticate using an identity token from an identity provider (IdP). Authenticated workloads can interact with HCP services without storing any HCP service principal keys.
Prerequisites
You must complete the following steps before configuring a workload identity provider:
- You must have the
Admin
role on the HCP project. - Create a service principal in the desired project and grant it access to the HCP resources your workload requires.
- Install the HCP CLI or use the HCP Terraform Provider based on your desired configuration workflow.
Identity provider prerequisites
The IdP you use must meet the following requirements:
- Support OpenID Connect 1.0.
- Have a publicly accessible OIDC metadata and JWKS endpoint. The endpoint must be secured with SSL and TLS and begin with
https://
.
Configure an external workload identity provider
To create an HCP workload identity provider for a custom OIDC IdP, you must provide the following configuration values:
- The issuer URI
- The expected audience
- A conditional access statement
Audience
By default, an OIDC workload identity provider verifies that the incoming token has an aud
field equal to the resource name of the workload identity provider. This behavior ensures that the token was intended to be exchanged with HCP.
The format for this value is:
`iam/project/<PROJECT_ID>/service-principal/<SERVICE_PRINCIPAL_NAME>/workload-identity-provider/<NAME>`
The following example identifies my_sp
as the HCP service principal and oidc-example
as the name of the workload identity provider that uses the service principal.
`iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-sp/workload-identity-provider/oidc-example`.
If you do not define an expected audience when you create the workload identity provider, ensure that the token the workload ultimately receives has its aud
set to the formatted resource name.
You can also configure the provider to expect a custom aud
claim.
Conditional access statement
When federating workload identity, one of the requirements is a conditional access statement. This statement is a boolean expression that has access to the identity claims and restricts which external identities are allowed.
When exchanging an identity token for access to HCP, the conditional access statement has access to all the claims in the token with the jwt_claims.
prefix. The following example lists the fields and names for a JWT token and then describes conditional access statements that use the information from this token.
{
"jti": "example-id",
"sub": "env:prod::namespace:my-namespace::service:my-workload",
"namespace": "my-namespace",
"service": "my-workload",
"env": "prod",
"aud": "iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-sp/workload-identity-provider/oidc-example",
"iss": "https://custom-oidc-idp.com",
"nbf": 1632492967,
"exp": 1632493867,
"iat": 1632493567
}
In the following example, HCP only allows access to workloads when the token's sub
field is “env:prod::namespace:my-namespace::service:my-workload”
.
`jwt_claims.sub == “env:prod::namespace:my-namespace::service:my-workload”`
In the following example, HCP allows workloads that have the service name my-workload
and the namspace my-namespace
, regardless of environment where the workload originates.
`jwt_claims.sub matches “^env:.+::namespace:my-namespace::service:my-workload$”`
In the following example, HCP allows workloads in my-namespace
namespace of the prod
enviornment.
`jwt_claims.env == “prod” and jwt_claims.namespace == “my-namespace”`
For more information about formatting conditional access statements, refer to OIDC providers.
Create the workload identity provider
After you compile the information you need to create the workload identity provider, create the workload identity provider.
Use the hcp iam workload-identity-providers create-oidc
command:
$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
--service-principal=<SP_RESOURCE_NAME> \
--issuer=<ISSUER_URI> \
--conditional-access=<CONDITION> \
--allowed-audience=<CUSTOM_AUDIENCE_1> \
--allowed-audiences=<CUSTOM_AUDIENCE_2> \
--description=<DESCRIPTION>
This command requires the following information that is specific to your HCP and IdP accounts:
<PROVIDER_NAME>
: The name of workload identity provider to create.<SP_RESOURCE_NAME>
:The service principal’s resource name, in the formatiam/project/<PROJECT_ID>/service-principal/<NAME>
.<ISSUER_URI>
: The issuer URI for your IdP. Must start withhttps://
.<CONDITION>
: The conditional access statement that restricts access to the specified workload.<CUSTOM_AUDIENCE>
: Expected audience of the ID tokens. When you use the default expected audience, omit the flags.<DESCRIPTION>
: An optional description for the provider.
Authenticate the workload's credentials
You can use the HCP CLI, HCP Terraform Provider, or HCP Go SDK to automatically retrieve external credentials and exchange them for an HCP access token. This process uses a credential file that contains the information required to obtain external credentials and the workload identity provider to exchange them with.
For more information, refer to credential files.
Create the credential file for a custom IdP
Use the hcp iam workload-identity-providers create-cred-file
command.
$ hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME> \
--source-[<TOKEN_SOURCE>]
--output-file=credentials.json
This command requires the following information that is specific to your HCP account:
<PROVIDER_NAME>
: The name of workload identity provider to exchange credentials with, in the formatiam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME>
.<TOKEN_SOURCE>
: Credential files can retrieve the workload’s token from an environment variable, a file, or URL. Select the appropriate flag and reference the command's documentation and examples.
Ensure the credential file exists in the runtime environment. Because the credential file contains no secret values, you can store the credential file in the VM or container. Alternatively, you can generate it at runtime.
To use the credential file to authenticate, you can use the HCP CLI, the HCP Terraform provider, or the HCP Go SDK. Refer to use a credential file to authenticate for more information.