Add documentation about OIDC and Federated Credentials (#37)

* Add documentation about OIDC * Update README.md * Update README.md Co-authored-by: Rafael Rivera <rafael@withinwindows.com> * Update OIDC.md * Update README.md Co-authored-by: Rafael Rivera <rafael@withinwindows.com> * Update README.md --------- Co-authored-by: Rafael Rivera <rafael@withinwindows.com>
Azure · Jul 8, 2024 · 38c7621 · 38c7621
1 parent 920a5e6
commit 38c7621
Show file tree

Hide file tree

Showing 2 changed files with 58 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="icon.png" alt="Trusted Signing" />
+</p>
+
 # 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
@@ -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
+    ```