diff --git a/docs/wiki/Azure-Pipelines.md b/docs/wiki/Azure-Pipelines.md index 59b09580..f2a2ed45 100644 --- a/docs/wiki/Azure-Pipelines.md +++ b/docs/wiki/Azure-Pipelines.md @@ -54,7 +54,7 @@ The PowerShell script below will set up a new project or use an existing if it a - Before running the commands below, any `` needs to be replaced with your values -> If you are running self-hosted build agents in Azure with Managed Identity enabled set the value for `$ARM_CLIENT_ID` and `$ARM_CLIENT_SECRET` to `''`. +> If you are running self-hosted build agents in Azure with Managed Identity enabled. Remove the variables `$ARM_CLIENT_ID` and `$ARM_CLIENT_SECRET` from `credentials` variable group. ```PowerShell # Configuration, make sure to replace with your values @@ -99,6 +99,7 @@ $CredentialVariableGroup = @( @{Name = 'ARM_TENANT_ID'; Value = $TenantId; IsSecret = $false } @{Name = 'ARM_SUBSCRIPTION_ID'; Value = $SubscriptionId; IsSecret = $false } @{Name = 'ARM_CLIENT_ID'; Value = $ARM_CLIENT_ID; IsSecret = $false } + @{Name = 'ARM_SERVICE_CONNECTION'; Value = ''; IsSecret = $false } ) if ($ARM_CLIENT_SECRET) { $CredentialVariableGroup += @{Name = 'ARM_CLIENT_SECRET'; Value = $ARM_CLIENT_SECRET; IsSecret = $true } @@ -186,11 +187,12 @@ foreach ($pipeline in 'AzOps - Push', 'AzOps - Pull', 'AzOps - Validate') { - Add the variables from the `Service Principal` creation to the `credentials Variable group`. - > If you are running self-hosted build agents in Azure with Managed Identity enabled set the value for `ARM_CLIENT_ID` and `ARM_CLIENT_SECRET` to `null`. + > If you are running self-hosted build agents in Azure with Managed Identity enabled, skip adding `ARM_CLIENT_ID` and `ARM_CLIENT_SECRET`. ```shell ARM_CLIENT_ID ARM_CLIENT_SECRET + ARM_SERVICE_CONNECTION ARM_SUBSCRIPTION_ID ARM_TENANT_ID ``` diff --git a/docs/wiki/GitHub-Actions.md b/docs/wiki/GitHub-Actions.md index 5a3764b1..ba3c5fc7 100644 --- a/docs/wiki/GitHub-Actions.md +++ b/docs/wiki/GitHub-Actions.md @@ -3,9 +3,9 @@ - [Prerequisites](#prerequisites) - [Further reading](#further-reading) - [Important Repository Link to refer](#important-repository-link-to-refer) -- [Two ways to configure AzOps](#Two-ways-to-configure-AzOps) -- [Configure AzOps via Portal](#Configure-AzOps-via-Portal) -- [Configure via command-line](#Configure-via-command-line) +- [Two ways to configure AzOps](#two-ways-to-configure-azops) +- [Configure AzOps via Portal](#configure-azops-via-portal) +- [Configure via command-line](#configure-via-command-line) ## Prerequisites @@ -43,7 +43,7 @@ If you are using GitHub Enterprise Server, you need to [import the repository](h ![GIT-Project](./Media/Actions/GIT-Project.PNG) 3. Review the information you entered, then click Begin import. ![GIT-Repository](./Media/Actions/GIT-Repository.PNG) -4. Navigate to Settings -> Secrets -> Actions and create the required secrets as depicted below. Note that `ARM_CLIENT_SECRET` is not required when using [federated credentials](https://github.com/azure/azops/wiki/github-oidc). +4. Navigate to Settings -> Secrets -> Actions and create the required secrets as depicted below. Note that `ARM_CLIENT_SECRET` is not required when using [federated credentials](https://github.com/azure/azops/wiki/oidc). ![GIT-Secret](./Media/Actions/GIT-Secret.PNG) 5. Untick `Allow merge commits` and `Allow rebase merging` under Settings -> General -> Pull Requests ![GIT-Merge](./Media/Actions/GIT-Merge.PNG) @@ -70,7 +70,7 @@ gh repo create '' --template azure/azops-accelerator --private --confirm gh secret set 'ARM_TENANT_ID' -b "" gh secret set 'ARM_SUBSCRIPTION_ID' -b "" gh secret set 'ARM_CLIENT_ID' -b "" -gh secret set 'ARM_CLIENT_SECRET' -b "" # Not required when using federated credentials((https://github.com/azure/azops/wiki/github-oidc) +gh secret set 'ARM_CLIENT_SECRET' -b "" # Not required when using federated credentials((https://github.com/azure/azops/wiki/oidc) ``` - Disable Allow Merge commits and Allow rebase merging diff --git a/docs/wiki/Media/Pipelines/Library.png b/docs/wiki/Media/Pipelines/Library.png index f627c4d8..76750f82 100644 Binary files a/docs/wiki/Media/Pipelines/Library.png and b/docs/wiki/Media/Pipelines/Library.png differ diff --git a/docs/wiki/Media/oidc/add.png b/docs/wiki/Media/oidc/add.png deleted file mode 100644 index ea255e24..00000000 Binary files a/docs/wiki/Media/oidc/add.png and /dev/null differ diff --git a/docs/wiki/Media/oidc/addcreds.png b/docs/wiki/Media/oidc/addcreds.png deleted file mode 100644 index 2ef6f0c5..00000000 Binary files a/docs/wiki/Media/oidc/addcreds.png and /dev/null differ diff --git a/docs/wiki/Media/oidc/connect_github_account.png b/docs/wiki/Media/oidc/connect_github_account.png deleted file mode 100644 index d91dc522..00000000 Binary files a/docs/wiki/Media/oidc/connect_github_account.png and /dev/null differ diff --git a/docs/wiki/Media/oidc/credential_details.png b/docs/wiki/Media/oidc/credential_details.png deleted file mode 100644 index 8d51dda4..00000000 Binary files a/docs/wiki/Media/oidc/credential_details.png and /dev/null differ diff --git a/docs/wiki/Media/oidc/remove-ado-arm_cs.png b/docs/wiki/Media/oidc/remove-ado-arm_cs.png new file mode 100644 index 00000000..4e820e2a Binary files /dev/null and b/docs/wiki/Media/oidc/remove-ado-arm_cs.png differ diff --git a/docs/wiki/Media/oidc/spn_addcreds.jpg b/docs/wiki/Media/oidc/spn_addcreds.jpg deleted file mode 100644 index 2f1b3267..00000000 Binary files a/docs/wiki/Media/oidc/spn_addcreds.jpg and /dev/null differ diff --git a/docs/wiki/Media/oidc/spn_addcreds2.png b/docs/wiki/Media/oidc/spn_addcreds2.png deleted file mode 100644 index 570b7285..00000000 Binary files a/docs/wiki/Media/oidc/spn_addcreds2.png and /dev/null differ diff --git a/docs/wiki/Media/oidc/uami.png b/docs/wiki/Media/oidc/uami.png deleted file mode 100644 index 2bcb4123..00000000 Binary files a/docs/wiki/Media/oidc/uami.png and /dev/null differ diff --git a/docs/wiki/GitHub-OIDC.md b/docs/wiki/OIDC.md similarity index 50% rename from docs/wiki/GitHub-OIDC.md rename to docs/wiki/OIDC.md index 73f66183..8bafd0fa 100644 --- a/docs/wiki/GitHub-OIDC.md +++ b/docs/wiki/OIDC.md @@ -1,82 +1,65 @@ -# Use Workload identity federation with the AzOps GitHub Actions +# Use Workload identity federation with the AzOps - [Introduction](#introduction) - [Configure](#configure) + - [GitHub](#github) + - [Azure Pipelines](#azure-pipelines) - [Resources](#resources) ## Introduction -GitHub Actions support OpenID Connect (OIDC) for secure deployments to Azure, which uses short-lived tokens that are automatically rotated for each deployment. +GitHub Actions and Azure Pipelines can make use of OpenID Connect (OIDC) for secure deployments to Azure, which uses short-lived tokens that are automatically rotated for each deployment. In the context of AzOps, this means we can allow the AzOps pipeline Service Principal/User-assigned managed identity to access Azure Resource Manager and Azure AD with federated credentials, eliminating the need to create/handle secrets. -This wiki explains how this feature can be configured and used in the AzOps GitHub Actions. - -> **Important**: For this feature to work with the current implementation of Workload identities, we take a dependency on [Environments for GitHub Actions](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment). *Environments are only available in public repositories for free. Access to environments in private repositories requires [GitHub Enterprise](https://docs.github.com/en/get-started/learning-about-github/githubs-products#github-enterprise).* +This wiki explains how this feature can be used and configured with AzOps. ## Configure -Before you start to configure the workload federation feature in Azure AD and changing the GitHub Actions, ensure that you have followed the instructions at and have your Service Principal/User-assigned managed identity ready with appropriate RBAC permissions. +Before you start to configure the workload federation feature in Azure AD and changing the GitHub Actions or Azure DevOps Pipelines, ensure that you have followed the instructions at and have your Service Principal/User-assigned managed identity ready with appropriate RBAC permissions. -### Federated credentials -> **Note:** Depending on if you are using a Service Principal or User-assigned managed identity the wording and visuals might differ. -1. **For Service Principal:** In Azure AD, find your AzOps service principal and navigate to Certificates & Secrets -> Federated credentials, click on `Add credential`. -![Add creds](./Media/oidc/spn_addcreds.jpg) +### GitHub +> **Important**: For this feature to work with the current implementation of Workload identities, we take a dependency on [Environments for GitHub Actions](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment). *Environments are only available in public repositories for free. Access to environments in private repositories requires [GitHub Enterprise](https://docs.github.com/en/get-started/learning-about-github/githubs-products#github-enterprise).* - **For User-assigned managed identity:** In Azure Portal, find your AzOps User-assigned managed identity and navigate to Federated credentials, click on `Add Credential`. - ![Add creds](./Media/oidc/uami.png) +How to setup GitHub Actions with workload identity federation: -2. There are three sections requiring input, enter your values in each highlighted field. +- [Create a Microsoft Entra application and service principal](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#create-a-microsoft-entra-application-and-service-principal) - 1. **Federated credential scenario:** +- [Add federated credentials](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#add-federated-credentials) - | Setting | Value | - |---|---| - | `Federated credential scenario` | select `GitHub Actions deploying Azure resources` | +> +> **Note:** The starter GitHub pipelines in [AzOps-Accelerator](https://github.com/azure/azops-accelerator) have been updated to support federated credentials. Consider performing an update using the [update](https://github.com/azure/azops/wiki/updates) pipeline. - Click on `Select scenario` and choose `GitHub Actions deploying Azure resources`. - ![Add creds](./Media/oidc/addcreds.png) - 2. **Connect your GitHub account:** +1. Validate that you have the latest version (post february 2023) of [sharedSteps/action.yml](https://github.com/Azure/AzOps-Accelerator/tree/main/.github/actions/sharedSteps), [pull.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/pull.yml), [push.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/push.yml), [redeploy.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/redeploy.yml) and [validate.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/validate.yml). +2. Uncomment the line with environment definition in [pull.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/pull.yml), [push.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/push.yml), [redeploy.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/redeploy.yml) and [validate.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/validate.yml). Change the environment name to reflect your environment names. - | Setting | Value | - |---|---| - | `Organization` | {replace with your organization} | - | `Repository` | {replace with your repository} | - | `Entity type` | select `Environment` | - | `GitHub environment name` | {replace with your environment name} | + ```yaml + environment: prod # Environment if using Federated Credentials (https://github.com/azure/azops/wiki/oidc) + ``` - ![Add creds](./Media/oidc/connect_github_account.png) - 3. **Credential details:** +3. Remove all references to `ARM_CLIENT_SECRET` from the repository/environment secrets. If `ARM_CLIENT_SECRET` exists, the pipeline will try to connect with the secret instead. - | Setting | Value | - |---|---| - | `Name` | {replace with your name} | + ![Overview](./Media/oidc/arm_client_secret.png) +4. Test the Pull, Push and Validate pipelines to ensure authentication works with federated credential. - ![Add creds](./Media/oidc/credential_details.png) +### Azure Pipelines - Click `Add` to complete Federated credentials configuration section. +How to setup Azure DevOps Pipelines with workload identity federation: - ![Overview](./Media/oidc/add.png) +- [Connect to Microsoft Azure with an ARM service connection](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops) - Overview of the accelerator example, where 'prod' is used as the `environment name`. +- [Manually configure Azure Resource Manager workload identity service connections](https://learn.microsoft.com/en-us/azure/devops/pipelines/release/configure-workload-identity?view=azure-devops) - ![Overview](./Media/oidc/spn_addcreds2.png) -### GitHub Actions > -> **Note:** The starter GitHub pipelines in [AzOps-Accelerator](https://github.com/azure/azops-accelerator) have been updated to support federated credentials. If you haven't updated the pipelines recently, consider performing an update using the [update](https://github.com/azure/azops/wiki/updates) pipeline. +> **Note:** The starter Azure Pipelines in [AzOps-Accelerator](https://github.com/azure/azops-accelerator) have been updated to support federated credentials. Consider performing an update using the [update](https://github.com/azure/azops/wiki/updates) pipeline. -1. Validate that you have the latest version (post february 2023) of [sharedSteps/action.yml](https://github.com/Azure/AzOps-Accelerator/tree/main/.github/actions/sharedSteps), [pull.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/pull.yml), [push.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/push.yml), [redeploy.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/redeploy.yml) and [validate.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/validate.yml). -2. Uncomment the line with environment definition in [pull.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/pull.yml), [push.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/push.yml), [redeploy.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/redeploy.yml) and [validate.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.github/workflows/validate.yml). Change the environment name to reflect your environment names. +1. Validate that you have the latest version (post october 2023) of [templates/sharedSteps.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.pipelines/.templates/sharedSteps.yml) and [templates/vars.yml](https://github.com/Azure/AzOps-Accelerator/blob/main/.pipelines/.templates/vars.yml). - ```yaml - environment: prod # Environment if using Federated Credentials (https://github.com/azure/azops/wiki/github-oidc) - ``` - -3. Remove all references to `ARM_CLIENT_SECRET` from the repository/environment secrets. If `ARM_CLIENT_SECRET` exists, the pipeline will try to connect with the secret instead. +3. Remove the `ARM_CLIENT_SECRET` variable from the `credentials` variable group. If `ARM_CLIENT_SECRET` exists, the pipeline will try to connect with the secret instead. - ![Overview](./Media/oidc/arm_client_secret.png) + ![Overview](./Media/oidc/remove-ado-arm_cs.png) 4. Test the Pull, Push and Validate pipelines to ensure authentication works with federated credential. ## Resources @@ -85,3 +68,4 @@ Read more about the functionality in the official docs below: - [Azure AD Workload identity federation](https://learn.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation) - [GitHub Actions: Secure cloud deployments with OpenID Connect](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/) +- [Azure DevOps Pipelines: Workload Identity federation for Azure Deployments](https://learn.microsoft.com/en-us/azure/devops/release-notes/roadmap/2022/secret-free-deployments) diff --git a/docs/wiki/Prerequisites.md b/docs/wiki/Prerequisites.md index dc531da3..d97178ab 100644 --- a/docs/wiki/Prerequisites.md +++ b/docs/wiki/Prerequisites.md @@ -26,7 +26,7 @@ The Azure Active Directory [Directory Readers](https://learn.microsoft.com/azure ### Create Service Principal If you intend to run AzOps with hosted agents a Service Principal is required. Perform the steps below to create the Service Principal in Azure AD. If you plan to run with self-hosted agents and want to use a managed identity skip to the next step. -If using GitHub Enterprise Cloud, consider using [federated credentials](https://github.com/azure/azops/wiki/github-oidc) to eliminate secrets management. +If using GitHub Enterprise Cloud or Azure DevOps Pipelines, consider using [federated credentials](https://github.com/azure/azops/wiki/oidc) to eliminate secrets management. ```powershell # Install module diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 034c2b2b..dbc3d845 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -7,8 +7,8 @@ * [Sovereign Clouds](https://github.com/azure/azops/wiki/sovereign-clouds) * [Services](https://github.com/azure/azops/wiki/services) * [GitHub Actions](https://github.com/azure/azops/wiki/github-actions) - * [Workload identity federation](https://github.com/azure/azops/wiki/github-oidc) * [Azure Pipelines](https://github.com/azure/azops/wiki/azure-pipelines) + * [Workload Identity Federation](https://github.com/azure/azops/wiki/oidc) ## Documentation