From 38c76215fa78efc78b1992c0feca453550745b63 Mon Sep 17 00:00:00 2001 From: James Parsons Date: Mon, 8 Jul 2024 14:50:07 -0700 Subject: [PATCH] Add documentation about OIDC and Federated Credentials (#37) * Add documentation about OIDC * Update README.md * Update README.md Co-authored-by: Rafael Rivera * Update OIDC.md * Update README.md Co-authored-by: Rafael Rivera * Update README.md --------- Co-authored-by: Rafael Rivera --- README.md | 11 ++++++++--- docs/OIDC.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 3 deletions(-) create mode 100644 docs/OIDC.md diff --git a/README.md b/README.md index 11e68bc..659eb1d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +

+ Trusted Signing +

+ # Trusted Signing The Trusted Signing Action allows you to digitally sign your files using a Trusted Signing certificate during a GitHub Actions run. @@ -50,14 +54,15 @@ jobs: ``` ## Usage -> [!IMPORTANT] -> Please review [Common error codes and mitigations](https://learn.microsoft.com/en-us/azure/trusted-signing/faq#common-error-codes-and-mitigations) before filing an issue. +Please review [Common error codes and mitigations](https://learn.microsoft.com/azure/trusted-signing/faq#common-error-codes-and-mitigations) before filing an issue. ### Authentication Behind the scenes, the Action uses [DefaultAzureCredential](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) as the primary method of authentication to Azure. The [EnvironmentCredential](https://learn.microsoft.com/dotnet/api/azure.identity.environmentcredential?view=azure-dotnet) variables are exposed as inputs and then set to Action-scoped environment variables. Each credential type supported by `DefaultAzureCredential` can be disabled using the Action inputs. > [!NOTE] -> [Trusted Signing Certificate Profile Signer](https://learn.microsoft.com/en-us/azure/trusted-signing/concept-trusted-signing-resources-roles#supported-roles) role is required to successfully sign by using Trusted Signing +> [Trusted Signing Certificate Profile Signer](https://learn.microsoft.com/azure/trusted-signing/concept-trusted-signing-resources-roles#supported-roles) role is required to successfully sign with Trusted Signing + +It is reccomended to use OpenID Connect for authentication with the Trusted Signing service. See [Authenticating with OpenID Connect](docs/OIDC.md) for details on how to configure your GitHub pipeline with OIDC and Federated Credentials. #### App Registration ```yaml diff --git a/docs/OIDC.md b/docs/OIDC.md new file mode 100644 index 0000000..6d4bbb5 --- /dev/null +++ b/docs/OIDC.md @@ -0,0 +1,50 @@ +# Authenticating with OpenID Connect +Follow the steps below to authenticate with [Open ID Connect](https://www.microsoft.com/security/business/security-101/what-is-openid-connect-oidc): + +1. [Create a Microsoft Entra application and service principal](https://learn.microsoft.com/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#create-a-microsoft-entra-application-and-service-principal) +1. [Add federated credentials](https://learn.microsoft.com/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#add-federated-credentials) +1. [Create GitHub secrets](https://learn.microsoft.com/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#create-github-secrets) + +1. Assign the [Trusted Signing Certificate Profile Signer](https://learn.microsoft.com/azure/trusted-signing/concept-trusted-signing-resources-roles#supported-roles) role to your service principal. + 1. Open your Trusted Signing Account in the Azure portal. + 1. **Note:** You can assign the role from your Resource Group or Subscription if you have multiple Trusted Signing accounts. + 1. Navigate to the Access Control (IAM) tab. + 1. Click 'Add role assignment'. + 1. Select 'Trusted Signing Certificate Profile Signer'. + 1. Next. + 1. Assign access to your 'User, group, or service principal' or 'Managed identity'. + 1. Review + assign. + +1. Adapt the following yaml to your GitHub pipeline: + ```yaml + permissions: + id-token: write + contents: read + + jobs: + sign: + runs-on: windows-latest + + steps: + - name: Azure login + uses: azure/login@v1 + with: + client-id: ${{ secrets.AZURE_CLIENT_ID }} + tenant-id: ${{ secrets.AZURE_TENANT_ID }} + subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + + - name: Trusted Signing + uses: azure/trusted-signing-action@vx.y.z + with: + ... + exclude-environment-credential: true + exclude-workload-identity-credential: true + exclude-managed-identity-credential: true + exclude-shared-token-cache-credential: true + exclude-visual-studio-credential: true + exclude-visual-studio-code-credential: true + exclude-azure-cli-credential: false + exclude-azure-powershell-credential: true + exclude-azure-developer-cli-credential: true + exclude-interactive-browser-credential: true + ```