AzureAD Application Registration Script Explanation for CyberArk Secrets Hub

app_registration.md

This script is written in PowerShell and is used for managing Azure resources. It's designed to automate the process of creating an application registration in Azure Active Directory, granting it permissions to a Key Vault in Azure, and handling various checks and error scenarios along the way. Here's a breakdown:

1. Setting up Parameters and Preferences:

   • It starts by defining mandatory parameters that need to be passed when the script is called: $AppClientDisplayName, $KeyVaultName, and $ResourceGroupName.
   • $ErrorActionPreference = "Stop": This line sets the preference for how to handle errors in the script. "Stop" means that the script will stop executing as soon as there's an error.

2. Checking Resource Group Existence:

   • The script checks if the specified Azure Resource Group exists. If it doesn't, the script throws an error and stops execution.

3. Checking for Existing Application and Key Vault:

   • It checks whether an Azure AD application with the specified display name already exists.
   • It verifies if the specified Key Vault exists within the given resource group.
   • If the application already exists, or if the Key Vault doesn't exist, an error is thrown, stopping the script.

4. Creating Application and Service Principal:

   • If the application doesn't exist, it creates a new application in Azure AD with the provided display name.
   • It creates a new service principal for the application. This is an identity for the application to be used in Azure.
   • It creates a new secret (password) for the application and sets it to expire in one year.

5. Handling Key Vault Permissions:

   • The script checks if the Key Vault uses RBAC (Role-Based Access Control) or access policies for permissions.

   • If RBAC is used:

     • A custom role is created for the Key Vault with the following permissions:
       • Actions:
         • write and read access to secrets in the Key Vault.
       • Data Actions:
         • Permissions to delete, purge, update, get, set secrets, and read their metadata.
       • This role is then assigned to the application at the scope of the specified Key Vault.

   • If access policies are used:

     • The script retrieves the service principal of the newly created application.
     • It sets a new access policy for the Key Vault granting the application permissions to get, set, list, delete, and purge secrets.

6. Outputting Results:

   • If the secret (password) for the app was created successfully, the script prints a success message along with the application's client ID and the new secret.

The role that's being created in Azure (when RBAC is used) is a custom role specifically for managing secrets within a specific Key Vault. The permissions associated with this role allow the application to read, write, delete, and perform other operations related to secrets stored in the Azure Key Vault.

role_assignment.md

In Azure, to assign roles, a user must have specific permissions. These permissions are typically held by users in certain roles. The two primary roles that allow for assigning other roles are:

• Owner: A user with the "Owner" role at a certain scope (like a subscription, resource group, or resource) can assign roles to others for that scope. This role allows users to manage everything, including access to resources.
• User Access Administrator: This role allows a user to manage user access to Azure resources. This includes the ability to assign roles to users, groups, or service principals within the scope they have this role.

For more granular permissions, custom roles can be created with specific permissions required to assign roles. The specific permissions needed to assign roles are:

• Microsoft.Authorization/roleAssignments/write: This permission allows for creating or assigning roles.
• Microsoft.Authorization/roleAssignments/delete: This permission allows for removing role assignments.
• Microsoft.Authorization/roleDefinitions/read: This permission is necessary to view roles and understand what permissions they grant.

A user needs the roleAssignments/write permission to assign a role to another user, group, or service principal. This permission is included in the built-in "Owner" and "User Access Administrator" roles but can also be part of custom roles.

It's important to note that role assignments in Azure are also scope-bound. This means that a user with permissions to assign roles at one level (for example, a subscription) does not necessarily have permissions to assign roles at another level (like a resource group or individual resource) unless explicitly given those permissions at the other scope. The hierarchy is considered - if a user has role assignment permissions at a higher level (e.g., subscription), they can assign roles at lower levels (e.g., resource groups within that subscription) unless there are explicit deny assignments in place.