You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guides/workload_identity_federation.md
+105-6Lines changed: 105 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
-
page_title: "Workload Identity Federation with GitHub Actions"
2
+
page_title: "Workload Identity Federation"
3
3
---
4
4
5
5
# Workload Identity Federation with GitHub Actions
6
6
7
7
Workload Identity Federation (WIF) allows you to authenticate the STACKIT Terraform provider without using long-lived Service Account keys.
8
8
This is particularly useful in CI/CD environments like **GitHub Actions**, **GitLab CI**, or **Azure DevOps**, where you can use short-lived
9
-
OIDC tokens. This guide focuses on using WIF with GitHub Actions, but the principles may apply to other CI/CD platforms that support OIDC.
9
+
OIDC tokens. This guide focuses on using WIF with GitHub Actions and Azure DevOps, but the principles may apply to other CI/CD platforms that support OIDC.
10
10
11
11
## Prerequisites
12
12
@@ -16,8 +16,13 @@ Before using Workload Identity Federation flow, you need to:
16
16
## Setup Workload Identity Federation
17
17
18
18
WIF can be configured to trust any public OIDC provider following the [docs page](https://docs.stackit.cloud/platform/access-and-identity/service-accounts/how-tos/manage-service-account-federations/#create-a-federated-identity-provider)
19
-
but for the purpose of this guide we will focus on GitHub Actions as OIDC provider. GitHub Actions supports OIDC authentication using
20
-
the public issuer "https://token.actions.githubusercontent.com" (for GH Enterprise you should check your issuer URL) and setting repository and action information
19
+
but for the purpose of this guide we will focus on GitHub Actions and AzureDevOps as OIDC providers.
20
+
21
+
> Important: You should use the most restrictive assertions possible by validating all available data from the OIDC token. This prevents security risks associated with trusting tokens issued outside the specific context of your CI/CD pipeline.
22
+
23
+
### GitHub Actions assertions
24
+
25
+
GitHub Actions supports OIDC authentication using the public issuer "https://token.actions.githubusercontent.com" (for GH Enterprise you should check your issuer URL) and setting repository and action information
21
26
as part of the OIDC token claims. [More info here](https://docs.github.com/es/actions/concepts/security/openid-connect).
22
27
23
28
Using this provider [repository](https://github.com/stackitcloud/terraform-provider-stackit) (stackitcloud/terraform-provider-stackit) as example and assuming that we want to
@@ -28,7 +33,27 @@ execute terraform on the main branch, we will configure the service account "Fed
28
33
-**sub**->equals->repo:stackitcloud/terraform-provider-stackit:ref:refs/heads/main # This is the repository and branch where the action will run
29
34
-**aud**->equals->sts.accounts.stackit.cloud # Mandatory value
30
35
31
-
> Note: You can use more fine-grained assertions just adding them. More info about OIDC token claims in [GitHub](https://docs.github.com/en/actions/reference/security/oidc)
36
+
> Note: You can use more fine-grained assertions by adding them. More info about OIDC token claims in [GitHub](https://docs.github.com/en/actions/reference/security/oidc)
37
+
38
+
### Azure DevOps assertions
39
+
40
+
Azure DevOps supports OIDC authentication using the public issuer "https://vstoken.azure.com" (for Azure DevOps Server you should check your issuer URL) and setting information like organization, project, and pipeline
41
+
as part of the OIDC token claims.
42
+
43
+
Using a hypothetical pipeline named `terraform-ado-oidc` inside the project 'https://myorg.azure.com/project-abc` as example and assuming that we want to
44
+
execute terraform on the main branch, we will configure the service account "Federated identity Provider" with the following configuration:
45
+
-**Provider Name**: AzureDevOps # This is just an example, you can choose any name you want
46
+
-**Issuer URL**: https://vstoken.dev.azure.com/{ORGANIZATION_ID} # This is the public issuer for Azure DevOps OIDC tokens
47
+
- For most organizations, the URL uses `vstoken.dev.azure.com`, but some legacy organizations might use 'vstoken.azure.com'. To be 100% sure, you can inspect the `iss` claim in a decoded OIDC token from your pipeline.
48
+
- How to find your ORGANIZATION_ID?
49
+
- Via Browser: Go to https://dev.azure.com/{YOUR_ORG_NAME}/_apis/connectionData and copy the value of instanceId.
50
+
- Via Pipeline: Add a script step echo $(System.CollectionId) to print it during a run.
51
+
-**Assertions**:
52
+
-**aud**->equals->api://AzureADTokenExchange # Mandatory value
53
+
-**sub**->equals->p://myorg/project-abc/terraform-ado-oidc # This is the pipeline where the process is running
54
+
-**rpo_ref**->equals->refs/heads/main # This is the branch where the pipeline will run
55
+
56
+
> Note: This is just an example, you can use more or less fine-grained assertions.
32
57
33
58
## Provider Configuration
34
59
@@ -50,7 +75,9 @@ provider "stackit" {
50
75
In most CI/CD scenarios, the cleanest way is to set the `STACKIT_SERVICE_ACCOUNT_EMAIL` environment variable as well as `STACKIT_USE_OIDC="1"` to enable the WIF flow. This way you don't need to
51
76
change your provider configuration and the provider will automatically fetch the OIDC token and exchange it for a short-lived access token.
52
77
53
-
## Example GitHub Actions Workflow
78
+
## Examples
79
+
80
+
### GitHub Actions Workflow
54
81
55
82
> Note: To request OIDC tokens, you need to [grant this permission to the GitHub Actions workflow](https://docs.github.com/en/actions/reference/security/oidc#required-permission).
Copy file name to clipboardExpand all lines: docs/index.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -74,7 +74,7 @@ When using Workload Identity Federation (WIF), you don't need a static service a
74
74
75
75
WIF can be configured to trust any public OIDC provider following the [official documentation](https://docs.stackit.cloud/platform/access-and-identity/service-accounts/how-tos/manage-service-account-federations/#create-a-federated-identity-provider).
76
76
77
-
To use WIF, set the `use_oidc` flag to `true` and provide an OIDC token for the exchange. While you can provide the token directly via `service_account_federated_token`, this is **not recommended for GitHub Actions**, as the provider will automatically fetch the token from the environment. For a complete setup, see our [Workload Identity Federation guide](./guides/workload_identity_federation.md).
77
+
To use WIF, set the `use_oidc` flag to `true` and provide an OIDC token for the exchange. While you can provide the token directly via `service_account_federated_token`, this is **not recommended for GitHub Actions or Azure DevOps**, as the provider will automatically fetch the token from the environment. For a complete setup, see our [Workload Identity Federation guide](./docs/guides/workload_identity_federation.md).
78
78
79
79
In addition to this, you must set the `service_account_email` to specify which service account to impersonate.
// This can be set to the ID of the service connection to restrict the token exchange to that connection, not supported by default to avoid additional configuration
567
+
// for users that don't need it, can be added as an additional provider config parameter in the future if there is demand
0 commit comments