Merge pull request #238 from microsoftgraph/dkershaw10-quickstartCleanUp

dkershaw10 · web-flow · commit efec2abdd9ed · 2025-05-08T18:59:16.000+01:00
Cleaned up readmes to be consistent and update one template file to have truly optional parameters.
diff --git a/quickstart-templates/application-serviceprincipal-create-client-resource/README.md b/quickstart-templates/application-serviceprincipal-create-client-resource/README.md
@@ -1,10 +1,10 @@
 # Create client and resource apps
 
-> **Note**: Minimum Bicep version required to deploy this quickstart template is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
-
 This template allows you to create a client application and a resource application, along with their service principals.
 
-* The client application is created with an optional key credential. The key can be passed in as a parameter. [Get The Certificate Key](https://learn.microsoft.com/en-us/graph/applications-how-to-add-certificate?tabs=http#get-the-certificate-key) mentions the steps to get the certificate key for a self-signed certificate. Here's a basic script:
+## Details
+
+The client application is created with an optional key credential. The key can be passed in as a parameter. [Get The Certificate Key](https://learn.microsoft.com/en-us/graph/applications-how-to-add-certificate?tabs=http#get-the-certificate-key) mentions the steps to get the certificate key for a self-signed certificate. Here's a basic PowerShell script to create a self-signed certificate for use in the template file:
 
 ```powershell
 $certname = "AppRegTestCert"
@@ -13,10 +13,32 @@ Export-Certificate -Cert $cert -FilePath "$certname.cer"  // Exports PUBLIC cert
 [convert]::ToBase64String((Get-Content "$certname.cer" -Encoding byte))  | Out-File -FilePath "20231004.$certname.txt"
 ```
 
-* The resource application is created with an optional app role. The id for the app role can be passed in as a parameter.
+The resource application is created optionally with an app role, if an `appRoleId` (in the form of a GUID) is passed in as a parameter.
+
+> NOTE: There are two other related quickstarts: You can [create a client app with an X509 certificate from Key Vault as the credential](../create-client-app-sp-with-kv-cert/README.md) or you can [configure a secretless client app using federated identity credentials](../msi-as-a-fic-secretless/README.md) .
+
+### Prerequisites
+
+- A valid **Azure subscription**: If you don't own an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin or [deploy without an Azure subscription][no-azure-sub].
+  - An **Azure resource group** that you own under a valid Azure subscription.
+- [Bicep tools for authoring and deployment](https://learn.microsoft.com/graph/templates/quickstart-install-bicep-tools). The minimum required Bicep version is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+- Have the requisite **Microsoft Entra roles** to deploy this template:
+  - Permissions to create applications. [Users have this permission by default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#compare-member-and-guest-default-permissions). However, [admins can turn off this default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#restrict-member-users-default-permissions) in which case you need to be assigned at least the [Application Developer](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-developer) role.
+
+### Deploy the template
 
 You can deploy the template with the following Azure CLI command (replace `<resource-group>`, `<app-role-id>` and `<cert-key>` with the necessary values for your deployment):
 
+#### Az CLI
+
 ```sh
 az deployment group create --resource-group <resource-group> --template-file main.bicep --parameters appRoleId='<app-role-id>' certKey='<cert-key>'
 ```
+
+#### Az PowerShell
+
+```powershell
+New-AzResourceGroupDeployment -ResourceGroupName <resource-group> -TemplateFile .\main.bicep -appRoleId="<app-role-id>" -certKey="<cert-key>"
+```
+
+[no-azure-sub]:https://learn.microsoft.com/graph/templates/how-to-deploy-without-azure-sub?view=graph-bicep-1.0&tabs=CLI
diff --git a/quickstart-templates/application-serviceprincipal-create-client-resource/main.bicep b/quickstart-templates/application-serviceprincipal-create-client-resource/main.bicep
@@ -1,16 +1,16 @@
 extension microsoftGraphV1
 
-@description('Id of the application role to add to the resource app')
-param appRoleId string
+@description('ID of the application role to add to the resource app. Must be a GUID.')
+param appRoleId string?
 
 @secure()
-@description('Value of the key credential')
-param certKey string
+@description('Value of the key credential.')
+param certKey string?
 
 resource resourceApp 'Microsoft.Graph/applications@v1.0' = {
   uniqueName: 'ExampleResourceApp'
   displayName: 'Example Resource Application'
-  appRoles: [
+  appRoles: (!empty(appRoleId)) ? [
     {
       id: appRoleId
       allowedMemberTypes: [ 'User', 'Application' ]
@@ -19,7 +19,7 @@ resource resourceApp 'Microsoft.Graph/applications@v1.0' = {
       value: 'ResourceAppData.Read.All'
       isEnabled: true
     }
-  ]
+  ] : []
 }
 
 resource resourceSp 'Microsoft.Graph/servicePrincipals@v1.0' = {
@@ -29,14 +29,14 @@ resource resourceSp 'Microsoft.Graph/servicePrincipals@v1.0' = {
 resource clientApp 'Microsoft.Graph/applications@v1.0' = {
   uniqueName: 'ExampleClientApp'
   displayName: 'Example Client Application'
-  keyCredentials: [
+  keyCredentials: (!empty(certKey)) ? [
     {
       displayName: 'Example Client App Key Credential'
       usage: 'Verify'
       type: 'AsymmetricX509Cert'
       key: certKey
     }
-  ]
+  ] : []
 }
 
 resource clientSp 'Microsoft.Graph/servicePrincipals@v1.0' = {
diff --git a/quickstart-templates/create-client-app-sp-with-kv-cert/README.md b/quickstart-templates/create-client-app-sp-with-kv-cert/README.md
@@ -1,10 +1,25 @@
 # Create a client app with an X509 certificate from Key Vault as the credential
 
-> **Note**: Minimum Bicep version required to deploy this quickstart template is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+This template creates a client app with a key credential, created and sourced from a Key Vault.
 
-The template creates a Key Vault, through which the authorized managed identity can add an X509 certificate (if it doesn't exist) and get the certificate's public key (base64 encoded), along with the thumbprint and other metadata.
-Finally the template creates the client application resource using the certificate public key as its credential. followed
-by creation of the service principal
+## Details
+
+The template creates a Key Vault, through which the authorized managed identity can add an X509 certificate (if it doesn't exist) and get the certificate's public key (base64 encoded), along with the thumbprint and other metadata. These Key Vault operations are not currently supported in Bicep, so the template file makes use of a deployment script.
+
+Finally the template creates the client application resource using the certificate public key as its credential, followed
+by creation of the service principal.
+
+### Prerequisites
+
+- A valid **Azure subscription**: If you don't own an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
+- An **Azure resource group** that you own under the valid Azure subscription.
+- [Bicep tools for authoring and deployment](https://learn.microsoft.com/graph/templates/quickstart-install-bicep-tools). The minimum required Bicep version is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+- Have the requisite **Microsoft Entra roles** to deploy this template:
+  - Permissions to create applications. [Users have this permission by default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#compare-member-and-guest-default-permissions). However, [admins can turn off this default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#restrict-member-users-default-permissions) in which case you need to be assigned at least the [Application Developer](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-developer) role.
+
+### Deploy the template
+
+#### Az CLI
 
 You can deploy the template with the following Azure CLI command (replace `<resource-group>` with the necessary values for your deployment). This deployment uses a parameter file, main.bicepparam, where default values may also be changed.  Since the parameter file references the Bicep template file, there's no need
 to use the `--template-file` switch.
@@ -13,8 +28,10 @@ to use the `--template-file` switch.
 az deployment group create --resource-group <resource-group> --parameter main.bicepparam --verbose
 ```
 
-To deploy the same template using Az Powershell, use:
+#### Az Powershell
 
 ```powershell
 New-AzResourceGroupDeployment -ResourceGroupName bicep-deployments -TemplateFile .\main.bicep -TemplateParameterFile .\main.bicepparam -Verbose
 ```
+
+[no-azure-sub]:https://learn.microsoft.com/graph/templates/how-to-deploy-without-azure-sub?view=graph-bicep-1.0&tabs=CLI
diff --git a/quickstart-templates/resource-application-access-grant-to-client-application/README.md b/quickstart-templates/resource-application-access-grant-to-client-application/README.md
@@ -1,15 +1,31 @@
 # Grant a client app access to a resource app
 
-> **Note1**: Minimum Bicep version required to deploy this quickstart template is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+This template allows you to grant client app access to resource application by assigning the app role (defined in the resource app) to the client app.
 
-> **Note2**: This template depends on a successful deployment of [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/)
+## Details
 
-This template allows you to grant client app access to resource application by assigning the app role in the resource app to the client app.
+The id for the app role must be passed in as a parameter. It needs to be the same as the app role id deployed in the [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/) example.
 
-* The id for the app role can be passed in as a parameter. It needs to be the same as the app role id deployed in the [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/) example.
+### Prerequisites
 
-You can deploy the template with the following Azure CLI command (replace `<resource-group>`, `<app-role-id>` with the necessary values for your deployment):
+- This template depends on a successful deployment of [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/)
+- A valid **Azure subscription**: If you don't own an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
+- An **Azure resource group** that you own under a valid Azure subscription, or [deploy without an Azure subscription][no-azure-sub].
+- [Bicep tools for authoring and deployment](https://learn.microsoft.com/graph/templates/quickstart-install-bicep-tools). The minimum required Bicep version is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+- Permissions to grant app roles. [Users have this permission by default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#compare-member-and-guest-default-permissions) as long as you created the client app. If not, you need to be assigned at least the [Application Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-administrator) role.
+
+### Deploy the Bicep template
+
+You can deploy the template with the following commands (replace `<resource-group>`, `<app-role-id>` with the necessary values for your deployment):
+
+#### Az CLI
 
 ```sh
 az deployment group create --resource-group <resource-group> --template-file main.bicep --parameters appRoleId='<app-role-id>'
 ```
+
+#### Az PowerShell
+
+```powershell
+New-AzResourceGroupDeployment -ResourceGroupName <resource-group> -TemplateFile .\main.bicep -appRoleId "<app-role-id>"
+```
diff --git a/quickstart-templates/security-group-create-with-owners-and-members/README.md b/quickstart-templates/security-group-create-with-owners-and-members/README.md
@@ -1,17 +1,35 @@
 # Create a group with members and owners
 
-> **NOTE**:
->
-> - Minimum Bicep version required to deploy this quickstart template is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
-> - This template depends on a successful deployment of [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/)
+This template allows you to create a security group with members and owners.
 
-This template allows you to create a security group with members and owners. Both `members` and `owners` take a [MicrosoftGraphRelationship](../../generated/microsoftgraph/microsoft.graph/v1.0/0.1.10-preview/types.md#microsoftgraphrelationship) type.
+## Details
+
+Both `members` and `owners` take a [MicrosoftGraphRelationship](../../generated/microsoftgraph/microsoft.graph/v1.0/0.2.0-preview/types.md#microsoftgraphrelationship) type.
 
 - The resource service principal created in [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/) is added to the owners
 - A managed identity is created and added to the members
 
-You can deploy the template with the following Azure CLI command (replace `<resource-group>` with the name of your resource group):
+> NOTE: Due to replication delays, deploying the template may fail when trying to add the newly created managed identity as a member.  Simply wait a few minutes and try running the deployment again.
+
+### Prerequisites
+
+- This template depends on a successful deployment of [application-serviceprincipal-create-client-resource](../application-serviceprincipal-create-client-resource/)
+- A valid **Azure subscription**: If you don't own an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
+- An **Azure resource group** that you own under the valid Azure subscription.
+- [Bicep tools for authoring and deployment](https://learn.microsoft.com/graph/templates/quickstart-install-bicep-tools). The minimum required Bicep version is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+- Have the requisite **Microsoft Entra roles** to deploy this template:
+  - A **Microsoft Entra role** that assigns you permissions to create security groups. [Users have this permission by default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#compare-member-and-guest-default-permissions). However, [admins can turn off this default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#restrict-member-users-default-permissions) in which case you need to be assigned at least the [Groups Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#groups-administrator) role.
+
+### Deploy the template
+
+#### Az CLI
 
 ```sh
 az deployment group create --resource-group <resource-group> --template-file main.bicep
 ```
+
+#### Az PowerShell
+
+```powershell
+New-AzResourceGroupDeployment -ResourceGroupName <resource-group> -TemplateFile .\main.bicep
+```
