docs: publish v1.1.0 feature docs (#397)

Co-authored-by: Pim Simons <pim.simons@codit.eu>

docs/versioned_docs/version-v1.1.0/01-index.md

@@ -0,0 +1,18 @@
+---
+title: "Arcus - Scripting"
+layout: default
+slug: /
+sidebar_label: Welcome
+---
+
+# Introduction
+Arcus Scripting provides an answer to many frequently-used, repeated tasks in Azure. Categorized in separate PowerShell modules, these functions help with backing up your API Management service, removing resource locks, disabling Logic Apps, injecting content in ARM templates, and many more!
+
+Take a quick look at the sidebar categories to find more information on the resource or topic you're working with.
+
+![Arcus Azure diagram](/img/arcus-azure-diagram.png)
+
+# License
+This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.
+
+*[Full license here](https://github.com/arcus-azure/arcus.scripting/blob/master/LICENSE)*

docs/versioned_docs/version-v1.1.0/02-Guidelines/Installation.md

@@ -0,0 +1,16 @@
+---
+title: "Installation"
+layout: default
+---
+
+# Installation
+
+To have access to the Arcus Scripting features, you have to import the modules.
+The best practice for usage in your build and release pipelines is to use the following commands:
+
+``` powershell
+PS> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+PS> Install-Module -Name Arcus.Scripting.{Module} -AllowClobber
+```
+
+This drastically improves performance over using the `-Force` parameter and as such, usage of the `-Force` parameter is not recommended.

docs/versioned_docs/version-v1.1.0/02-Guidelines/setting-arm-outputs-to-azure-devops-variable-group.md

@@ -0,0 +1,95 @@
+---
+title: "Setting ARM outputs to Azure DevOps variable group"
+layout: default
+---
+
+# Setting ARM outputs to Azure DevOps variable group
+
+In ARM and Bicep templates it is possible to specify [output parameters](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs), this enables you to return values from the deployed resources. 
+
+To enable maximum re-use of these output parameters within your environment we developed [this script](https://scripting.arcus-azure.net/Features/powershell/azure-devops#setting-arm-outputs-to-azure-devops-variable-group) which is available in the `Arcus.Scripting.DevOps` PowerShell module. It allows you to store those output parameters in an Azure DevOps variable group. This helps you in making sure certain parameters are available throughout your Azure DevOps environment.
+
+For example, think of a use-case where your vital infrastructure components are deployed in a seperate Azure DevOps pipeline and need to be referenced from other components. Storing the necessary information such as identifiers, locations or names of these components in an Azure DevOps variable group allows you to easily use these values from other components.
+
+## Example
+### Specify Output Parameters
+So how does this work in practice? Let's take an example where we will deploy a very basic Application Insights instance and specify the `Id` and `ConnectionString` of the Application Insights instance as output parameters. 
+
+Our Bicep template looks like this:
+``` bicep
+param location string = resourceGroup().location
+
+resource applicationInsight 'microsoft.insights/components@2020-02-02' = {
+  name: 'myAppInsights'
+  location: location
+  kind: 'other'
+  properties: {
+    Application_Type: 'other'
+  }
+}
+
+output ApplicationInsights_Id string = applicationInsight.id
+output ApplicationInsights_ConnectionString string = reference(applicationInsight.id, '2020-02-02').ConnectionString
+```
+
+This Bicep template will deploy the Application Insights instance and place the `Id` and `ConnectionString` in the output parameters. 
+
+### Updating The Variable Group
+Now all we need to do is execute our [script](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group) which will update the Azure DevOps variable group.
+
+From an Azure DevOps pipeline this can be done like so:
+``` powershell
+Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+Install-Module -Name Arcus.Scripting.DevOps -AllowClobber
+
+Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup'
+```
+
+### Combining It All In A Pipeline
+Now that we have walked through both steps, let's take a look on how to combine all this into an Azure DevOps pipeline.
+For this we use YAML and define two tasks, the first will deploy our Application Insights instance and the second will update our Azure DevOps variable group.
+
+``` yaml
+- task: AzureResourceGroupDeployment@3
+  displayName: 'Deploy Bicep template'
+  inputs:
+    azureResourceManagerConnection: 'myServiceConnection'
+    subscriptionId: 'mySubscriptionId'
+    resourceGroupName: 'myResourceGroup'
+    location: 'West Europe'
+    csmFile: 'applicationInsights.bicep'
+    csmParametersFile: 'applicationInsights.parameters.json'
+    deploymentOutputs: ArmOutputs
+
+- task: PowerShell@2
+  displayName: 'Update Variable Group'
+  env:
+    system_accesstoken: $(System.AccessToken)
+  inputs:
+    targetType: 'inline'
+    script: |
+      Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+      Install-Module -Name Arcus.Scripting.DevOps -AllowClobber
+
+      Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup' -ArmOutputsEnvironmentVariableName 'ArmOutputs' -UpdateVariablesForCurrentJob
+```
+
+There are a few things worth noting. First of all we define `deploymentOutputs: ArmOutputs` during the `AzureResourceGroupDeployment@3` task. This means that the output parameters we specified in our Bicep template will be placed in a variable called `ArmOutputs`, this is then referenced during the execution of our script with `-ArmOutputsEnvironmentVariableName 'ArmOutputs'`.
+
+Secondly we use `-UpdateVariablesForCurrentJob` as a parameter when calling the script. This means that the output parameters from the Bicep file are also available as pipeline variables in the current running job. While not necessary in our example here, if you need to deploy another Bicep template that needs output parameters from an earlier deployed Bicep template this is the way to do it.
+
+Finally we use `system_accesstoken: $(System.AccessToken)` in the `Powershell@2` task, this is necessary because we need to use the security token used by the running build. 
+
+## Closing Up
+Using this setup we are able to deploy a Bicep template and update an Azure DevOps variable group with the specified output parameters!
+
+> ⚠ Before running your pipeline, make sure the variable group already exists in Azure DevOps and the permissions below are set:
+> - Project Collection Build Service (`<your devops org name>`) - Administrator
+> - `<your devops project name>` Build Service (`<your devops org name>`) - Administrator
+
+## Further Reading
+- [Arcus Scripting Azure DevOps documentation](../03-Features/powershell/azure-devops.md)
+  - [Setting ARM outputs to Azure DevOps variable group](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group)
+  - [Setting ARM outputs to Azure DevOps pipeline variables](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-pipeline-variables)
+- [Bicep Outputs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs/)
+- [Azure DevOps Variable Groups](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml)

docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-active-directory.md

@@ -0,0 +1,122 @@
+---
+title: "Azure Active Directory"
+layout: default
+---
+
+# Azure Active Directory
+
+## Installation
+
+To have access to the following features, you have to import the module:
+
+```powershell
+PS> Install-Module -Name Arcus.Scripting.ActiveDirectory
+```
+
+## Access Rights to Azure Active Directory
+
+To interact with Azure Active Directory these scripts use the [Microsoft.Graph.Applications](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.applications/) module, import this module:
+
+```powershell
+PS> Install-Module -Name Microsoft.Graph.Applications
+```
+
+After importing this module, make sure you are connected to Microsoft Graph with the following scopes:
+
+```powershell
+PS> Connect-MgGraph -Scopes "Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All"
+```
+
+## Listing the Roles and Role Assignments for an Azure Active Directory Application
+
+Lists the roles and role assignments for an Azure Active Directory Application.
+
+| Parameter                 | Mandatory | Description                                                                                                                                                                                |
+| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ClientId`                | yes       | The client ID of the Azure Active Directory Application Registration for which the roles and assignments are retrieved.                                                                    |
+| `RolesAssignedToClientId` | no        | The client ID of the Azure Active Directory Application Registration to which roles have been assigned, used when you only want to retrieve the assignments for this specific application. |
+
+**Example**
+
+Retrieving all information for a Client Id.
+
+```powershell
+PS> List-AzADAppRoleAssignments `
+-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85"
+#Found role 'FirstRole' on Active Directory Application 'main-application'
+#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826'
+#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-two' with ID 'ebafc99d-cbf4-4bd2-9295-f2b785cfc1a1'
+#Found role 'SecondRole' on Active Directory Application 'arcus-scripting-test-main'
+#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826'
+```
+
+Retrieving all information for a Client Id and a specific role.
+
+```powershell
+PS> List-AzADAppRoleAssignments `
+-ClientId 'b885c208-6067-44bd-aba9-4010c62b7d85' `
+-RolesAssignedToClientId '6ea09bbd-c21c-460c-b58a-f4a720f51826'
+#Found role 'FirstRole' on Active Directory Application 'main-application'
+#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826'
+#Found role 'SecondRole' on Active Directory Application 'main-application'
+#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826'
+```
+
+## Add a Role and Assignment for an Azure Active Directory Application
+
+Adds a role assignment for an Azure Active Directory Application. The role will be added to the Azure Active Directory Application Registration defined by the `ClientId` parameter, and a role assignment for this role will be added to the Azure Active Directory Application Registration defined by the `AssignRoleToClientId` parameter.
+
+| Parameter              | Mandatory | Description                                                                                                                                                                                                                                                       |
+| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ClientId`             | yes       | The client ID of the Azure Active Directory Application Registration to which the role will be added if not present.                                                                                                                                              |
+| `Role`                 | yes       | The name of the role.                                                                                                                                                                                                                                             |
+| `AssignRoleToClientId` | yes       | The client ID of the Azure Active Directory Application Registration for which the role assignment will be created. The role assignment will be created based on the role added to the Azure Active Directory Application Registration defined by the `ClientId`. |
+
+**Example**
+
+```powershell
+PS> Add-AzADAppRoleAssignment `
+-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
+-Role "DummyRole" `
+-AssignRoleToClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826"
+#Active Directory Application 'main-application' does not contain the role 'DummyRole', adding the role
+#Added Role 'DummyRole' to Active Directory Application 'main-application'
+#Role Assignment for the role 'DummyRole' added to the Active Directory Application 'client-application-one'
+```
+
+## Remove a Role and Assignment from an Azure Active Directory Application
+
+Removes a role assignment for an Azure Active Directory Application.
+
+| Parameter                          | Mandatory | Description                                                                                                                                                                         |
+| ---------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ClientId`                         | yes       | The client ID of the Azure Active Directory Application Registration containing the role for which the assignment must be removed.                                                  |
+| `Role`                             | yes       | The name of the role.                                                                                                                                                               |
+| `RemoveRoleFromClientId`           | yes       | The client ID of the Azure Active Directory Application Registration for which the role assignment will be removed.                                                                 |
+| `RemoveRoleIfNoAssignmentsAreLeft` | no        | Indicate whether to remove the role from the Azure Active Directory Application Registration defined by the `ClientId` parameter when no more role assignments remain for the role. |
+
+**Example**
+
+Removes a role assignment.
+
+```powershell
+PS> Remove-AzADAppRoleAssignment `
+-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
+-Role "DummyRole" `
+-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" `
+#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one'
+```
+
+Removes a role assignment and removes the fole if no assignments are left on the role.
+
+```powershell
+PS> Remove-AzADAppRoleAssignment `
+-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
+-Role "DummyRole" `
+-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" `
+-RemoveRoleIfNoAssignmentsAreLeft
+#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one'
+#Role 'DummyRole' on Active Directory Application 'main-application' has been disabled as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set
+#Role 'DummyRole' removed from Active Directory Application 'main-application' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set
+```
+