hcp iam workload-identity-providers create-oidc

Command: hcp iam workload-identity-providers create-oidc

The hcp iam workload-identity-providers create-oidc command creates a new OIDC based workload identity provider.

Common OIDC providers include Azure, GCP, Kubernetes Clusters, HashiCorp Vault, GitHub, GitLab, and more.

When creating an OIDC provider, you must specify the issuer URL, the conditional access statement, and optionally the allowed audiences.

The issuer URL is the URL of the OIDC provider that is allowed to exchange workload identities. The URL must be a valid URL that is reachable from the HCP control plane, and must match the issuer set in the response to the OIDC discovery endpoint (${issuer_url}/.well-known/openid-configuration).

The conditional access statement must be set and is used to restrict which tokens issued by the OIDC provider are allowed to exchange their identity for an HCP access token. The condtional access statement is a hashicorp/go-bexpr string that is evaluated when exchanging tokens. It has access to all the claims in the external identity token and they can be accessed via the "jwt_claims.<claim_name>" syntax. An example conditional access statement that restricts access to a specific subject claim is 'jwt_claims.sub == "example"'.

If unset, the allowed audiences will default to the resource name of the provider. The format will be: iam/project/PROJECT_ID/service-principal/SP_NAME/workload-identity-provider/WIP_NAME. If set, the presented access token must have an audience that is contained in the set of allowed audiences.

Usage

$ hcp iam workload-identity-providers create-oidc PROVIDER_NAME
  --conditional-access=STATEMENT --issuer=URI --service-principal=RESOURCE_NAME
  [Optional Flags]

Examples

Azure - Allow exchanging a User Managed Identity:

$ hcp iam workload-identity-providers create-oidc azure-example-user-managed \
  --service-principal=iam/project/PROJECT/service-principal/example-sp \
  --issuer=https://sts.windows.net/AZURE_AD_TENANT_ID/ \
  --allowed-audience=MANAGED_IDENTITY_CLIENT_ID \
  --conditional-access='jwt_claims.sub == "MANAGED_IDENTITY_OBJECT_PRINCIPAL_ID"' \
  --description="Azure User Managed Identity Example"

GCP - Allow exchanging a Service Account Identity

Full List of claims:

$ hcp iam workload-identity-providers create-oidc gcp-example-service-account \
  --service-principal=iam/project/PROJECT/service-principal/example-sp \
  --issuer=https://accounts.google.com \
  --conditional-access='jwt_claims.sub == "SERVICE_ACCOUNT_UNIQUE_ID"' \
  --description="GCP Service Account Example"

GitLab - Allow exchanging a GitLab

Full list of claims:

$ hcp iam workload-identity-providers create-oidc gcp-example-service-account \
  --service-principal=iam/project/PROJECT/service-principal/example-sp \
  --issuer=https://gitlab.com \
  --conditional-access='jwt_claims.project_path == "example-org/example-repo" and jwt_cliams.job_id == 302' \
  --description="GitLab example-repo access for job 302"

Positional arguments

PROVIDER_NAME - The name of the provider to create.

Required flags

--conditional-access=STATEMENT - The conditional access statement is a hashicorp/go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.
The conditional_access statement can access any claim from the external identity token using the jwt_claims.<claim_name> syntax. As an example, access the subject claim with jwt_claims.sub.
--issuer=URI - The URL of the OIDC Issuer that is allowed to exchange workload identities.
--service-principal=RESOURCE_NAME - The resource name of the service principal to create the provider for.

Optional flags

--allowed-audience=AUD [Repeatable] - The set of audiences set on the access token that are allowed to exchange identities. The access token must have an audience that is contained in this set.
If no audience is set, the default allowed audience will be the resource name of the provider. The format will be: iam/project/PROJECT_ID/service-principal/SP_NAME/workload-identity-provider/WIP_NAME.
--description=TEXT - A description of the provider.