Merge pull request #271257 from microsoftshawarma/main

Fixing small changes in versioning and adding questions to FAQ

Author: Stacyrch140

articles/trusted-signing/TOC.yml

@@ -10,6 +10,10 @@
     items:
     - name: Signing Integrations with Trusted Signing
       href: how-to-signing-integrations.md
+  - name: How-To
+    items:
+    - name: Sign CI Policies with Trusted Signing
+      href: how-to-sign-ci-policy.md
   - name: Quickstart
     items:
     - name: Quickstart onboarding

articles/trusted-signing/faq.yml

@@ -17,7 +17,7 @@ summary: |
 sections:
   - name: Onboarding
     questions:
-      - question: What Windows versions does Trusted Signing support? # Question.
+      - question: What Windows versions do Trusted Signing support? # Question.
         answer: | 
           Refer to the [Trusted Signing Program Windows Support](https://support.microsoft.com/topic/kb5022661-windows-support-for-the-azure-code-signing-program-4b505a31-fa1e-4ea6-85dd-6630229e8ef4) page for details about Windows support for Trusted Signing.
           The service is supported on all currently supported versions of:
@@ -47,6 +47,12 @@ sections:
       - question: What if I fail identity validation?
         answer: | 
           If more documentation is required for identity validation, you're asked to provide those documents on the Azure portal. Otherwise, we recommend checking for an email sent to the listed address for email validation. However, if your organization fails identity validation we can't onboard you to Trusted Signing. We recommend you delete your Trusted Signing account so you don't get billed for unused resources.
+      - question: What is the cost of using Trusted Signing?
+        answer: | 
+          For the beginning of Public Preview until June 2024 Trusted Signing is free. You'll still be prompted to select a Basic or Premium SKU when you create your account and we throttle signing requests.
+      - question: What are my support options when onboarding to Trusted Signing?
+        answer: | 
+          If you're a managed customer on Azure, and have a support plan you can create a support ticket with the service on the Azure portal and be assisted by Azure customer support. Otherwise, we recommend you go to Microsoft Q&A or StackOverflow under the tag Trusted-Signing to ask questions.  
   - name: Certificate Profiles
     questions:
       - question: What if my Trusted Signing subject name is different than my old cert and my MSIX's package name is now different? 

articles/trusted-signing/how-to-sign-ci-policy.md

@@ -0,0 +1,69 @@
+---
+title: Signing CI Policies #Required; page title is displayed in search results. Include the brand.
+description: Learn how to sign new CI policies with Trusted Signing. #Required; article description that is displayed in search results. 
+author: microsoftshawarma #Required; your GitHub user alias, with correct capitalization.
+ms.author: rakiasegev #Required; microsoft alias of author; optional team alias.
+ms.service: azure-code-signing #Required; service per approved list. slug assigned by ACOM.
+ms.topic: how-to #Required; leave this attribute/value as-is.
+ms.date: 04/04/2024 #Required; mm/dd/yyyy format.
+ms.custom: template-how-to-pattern #Required; leave this attribute/value as-is.
+---
+
+# Sign CI Policies with Trusted Signing
+
+To sign new CI policies with the service first install several prerequisites. 
+
+
+Prerequisites: 
+* A Trusted Signing account, Identity Validation, and Certificate Profile.
+* Ensure there are proper individual or group role assignments for signing (“Trusted Signing Certificate Profile Signer” role).
+* [Azure PowerShell on Windows](https://learn.microsoft.com/powershell/azure/install-azps-windows) installed 
+* [Az.CodeSigning](https://learn.microsoft.com/powershell/module/az.codesigning/) module downloaded
+
+Overview of steps:
+1. ⁠Unzip the Az.CodeSigning module to a folder
+2. ⁠Open Windows PowerShell [PowerShell 7](https://github.com/PowerShell/PowerShell/releases/latest)
+3. In the Az.CodeSigning folder, run 
+```
+Import-Module .\Az.CodeSigning.psd1
+``` 
+4. Optionally you can create a `metadata.json` file:
+```
+Endpoint "https://scus.codesigning.azure.net/" 
+CodeSigningAccountName "youracsaccount" 
+CertificateProfileName "youracscertprofile" 
+```
+5. [Get the root certificate](https://learn.microsoft.com/powershell/module/az.codesigning/get-azcodesigningrootcert) to be added to the trust store
+```
+Get-AzCodeSigningRootCert -AccountName TestAccount -ProfileName TestCertProfile -EndpointUrl https://xxx.codesigning.azure.net/ -Destination c:\temp\root.cer
+```
+Or using a metadata.json
+```
+Get-AzCodeSigningRootCert -MetadataFilePath C:\temp\metadata.sample.scus.privateci.json https://xxx.codesigning.azure.net/ -Destination c:\temp\root.cer 
+```
+6. To get the EKU (Extended Key Usage) to insert into your policy:
+```
+Get-AzCodeSigningCustomerEku -AccountName acstestcanary -ProfileName acstestcanaryCert1 -EndpointUrl https://xxx.codesigning.azure.net/ 
+```
+Or
+
+```
+Get-AzCodeSigningCustomerEku -MetadataFilePath C:\temp\metadata.sample.scus.privateci.json 
+```
+7. To sign your policy, you run the invoke command:
+``` 
+Invoke-AzCodeSigningCIPolicySigning -accountName acstestcanary -profileName acstestcanaryCert1 -endpointurl "https://xxx.codesigning.azure.net/" -Path C:\Temp\defaultpolicy.bin -Destination C:\Temp\defaultpolicy_signed.bin -TimeStamperUrl: http://timestamp.acs.microsoft.com 
+```
+ 
+Or use a `metadata.json` file and the following command: 
+
+```
+Invoke-AzCodeSigningCIPolicySigning -MetadataFilePath C:\temp\metadata.sample.scus.privateci.json -Path C:\Temp\defaultpolicy.bin -Destination C:\Temp\defaultpolicy_signed.bin -TimeStamperUrl: http://timestamp.acs.microsoft.com 
+```
+
+## Creating and Deploying a CI Policy
+
+For steps on creating and deploying your CI policy refer to:
+* [Use signed policies to protect Windows Defender Application Control against tampering](https://learn.microsoft.com/windows/security/application-security/application-control/windows-defender-application-control/deployment/use-signed-policies-to-protect-wdac-against-tampering)
+* [Windows Defender Application Control design guide](https://learn.microsoft.com/windows/security/application-security/application-control/windows-defender-application-control/design/wdac-design-guide)
+

articles/trusted-signing/how-to-signing-integrations.md

@@ -5,7 +5,7 @@ author: microsoftshawarma #Required; your GitHub user alias, with correct capita
 ms.author: rakiasegev #Required; microsoft alias of author; optional team alias.
 ms.service: azure-code-signing #Required; service per approved list. slug assigned by ACOM.
 ms.topic: how-to #Required; leave this attribute/value as-is.
-ms.date: 03/21/2024 #Required; mm/dd/yyyy format.
+ms.date: 04/04/2024 #Required; mm/dd/yyyy format.
 ms.custom: template-how-to-pattern #Required; leave this attribute/value as-is.
 ---
 
@@ -17,7 +17,8 @@ Trusted Signing currently supports the following signing integrations:
 * ADO Task
 * PowerShell for Authenticode
 * Azure PowerShell - App Control for Business CI Policy
-We constantly work to support more signing integrations and will update the above list if/when more are available. 
+
+We constantly work to support more signing integrations and update the above when more become available. 
 
 This article explains how to set up each of the above Trusted Signing signing integrations.
 
@@ -66,7 +67,7 @@ The components that SignTool.exe uses to interface with Trusted Signing require
 
 ### Download and install Trusted Signing Dlib package
 Complete these steps to download and install the Trusted Signing Dlib package (.ZIP):
-1.	Download the [Trusted Signing Dlib package](https://www.nuget.org/packages/Azure.CodeSigning.Client). 
+1.	Download the [Trusted Signing Dlib package](https://www.nuget.org/packages/Microsoft.Trusted.Signing.Client). 
 
 2.	Extract the Trusted Signing Dlib zip content and install it onto your signing node in a directory of your choice. You’re required to install it onto the node you’ll be signing files from with SignTool.exe.
 
@@ -113,12 +114,12 @@ Trusted Signing certificates have a 3-day validity, so timestamping is critical
 ## Use other signing integrations with Trusted Signing 
 This section explains how to set up other not [SignTool](#set-up-signtool-with-trusted-signing) signing integrations with Trusting Signing.
 
-* GitHub Action – To use the GitHub action for Trusted Signing, visit [Azure Code Signing · Actions · GitHub Marketplace](https://github.com/marketplace/actions/azure-code-signing) and follow the instructions to set up and use GitHub action.
+* GitHub Action – To use the GitHub action for Trusted Signing, visit [Trusted Signing · Actions · GitHub Marketplace](https://github.com/azure/trusted-signing-action) and follow the instructions to set up and use GitHub action.
 
-* ADO Task – To use the Trusted Signing AzureDevOps task, visit [Azure Code Signing - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=VisualStudioClient.AzureCodeSigning) and follow the instructions for setup.
+* ADO Task – To use the Trusted Signing AzureDevOps task, visit [Trusted Signing - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=VisualStudioClient.TrustedSigning&ssr=false#overview) and follow the instructions for setup.
 
-* PowerShell for Authenticode – To use PowerShell for Trusted Signing, visit [PowerShell Gallery | AzureCodeSigning 0.2.15](https://www.powershellgallery.com/packages/AzureCodeSigning/0.2.15) to install the PowerShell module. 
+* PowerShell for Authenticode – To use PowerShell for Trusted Signing, visit [PowerShell Gallery | Trusted Signing 0.3.8](https://www.powershellgallery.com/packages/TrustedSigning/0.3.8) to install the PowerShell module. 
 
-* Azure PowerShell – App Control for Business CI Policy - App Control for Windows [link to CI policy signing tutorial].
+* Azure PowerShell: App Control for Business CI Policy – To use Trusted Signing for CI policy signing follow the instructions at [Signing a New CI policy](./how-to-sign-ci-policy.md) and visit the [Az.CodeSigning PowerShell Module](https://learn.microsoft.com/powershell/azure/install-azps-windows).
 
 * Trusted Signing SDK – To create your own signing integration our [Trusted Signing SDK](https://www.nuget.org/packages/Azure.CodeSigning.Sdk) is publicly available.

articles/trusted-signing/index.yml

@@ -24,6 +24,12 @@ landingContent:
         links:
           - text: Implement Signing Integrations with Trusted Signing
             url: how-to-signing-integrations.md
+  - title: CI Policy Signing
+    linkLists:
+      - linkListType: how-to-guide
+        links:
+          - text: Sign CI Policies with Trusted Signing
+            url: how-to-sign-ci-policy.md
   - title: Overview
     linkLists:
         - linkListType: overview

articles/trusted-signing/tutorial-assign-roles.md

@@ -27,11 +27,18 @@ The Identity Verified role specifically is needed to manage Identity Validation
 
 ## Assign roles in Trusting Signing
 Complete the following steps to assign roles in Trusted Signing.
+
 1.	Navigate to your Trusted Signing account on the Azure portal and select the **Access Control (IAM)** tab in the left menu. 
 2.	Select on the **Roles** tab and search "Trusted Signing". You can see in the screenshot below the two custom roles.
 ![Screenshot of Azure portal UI with the Trusted Signing custom RBAC roles.](./media/trusted-signing-rbac-roles.png)
 
-3. To assign these roles, select on the **Add** drop down and select **Add role assignment**. Follow the [Assign roles in Azure](../role-based-access-control/role-assignments-portal.md) guide to assign the relevant roles to your identities.
+3. To assign these roles, select on the **Add** drop down and select **Add role assignment**. Follow the [Assign roles in Azure](https://docs.microsoft.com/azure/role-based-access-control/role-assignments-portal?tabs=current) guide to assign the relevant roles to your identities. _You'll need at least a Contributor role to create a Trusted Signing account and certificate profile._
+4. For more granular access control on the certificate profile level, you can use the Azure CLI to assign roles. The following commands can be used to assign the _Code Signing Certificate Profile Signer_ role to users/service principles to sign files. 
+```
+az role assignment create --assignee <objectId of user/service principle> 
+--role "Code Signing Certificate Profile Signer" 
+--scope "/subscriptions/<subscriptionId>/resourceGroups/<resource-group-name>/providers/Microsoft.CodeSigning/codeSigningAccounts/<codesigning-account-name>/certificateProfiles/<profileName>" 
+```
 
 ## Related content 
 * [What is Azure role-based access control (RBAC)?](../role-based-access-control/overview.md)