Module Register-Cloudaware

This article instructs you on how to create an AD application in Azure and grant Cloudaware with necessary permissions executing the module Register-Cloudaware in Azure Cloud Shell.

Prepare the environment where the module will be executed

1. Log in to Azure portal.

2. Click the Cloud Shell button in the menu bar. Select Power Shell.

3. Log in Azure using the command below (the user should have the role 'Global Administrator' assigned on the Azure AD level):

az login

4. Upload the file Register-Cloudaware.ps1

mkdir cloudaware
cd cloudaware
curl -LJO https://raw.githubusercontent.com/cloudaware/public-utilities/master/PowerShell%20modules/Register-Cloudaware.ps1

5. Import the module Register-Cloudaware from the file Register-Cloudaware.ps1 for a current session:

Import-Module -Name .\Register-Cloudaware.ps1 -Force

Once these steps are performed, the module Register-Cloudaware is available in the current Azure Cloud Shell session. Using the module, you are able to create an AD application and provide the required information to Cloudaware CMDB.

Description of the module parameters

-name cloudaware-api-access

-credentialExpiration 1

-certificateFile cert.pem

-createKeyAndSertificate

-redirectUri https://cloudaware-api-access.com

-withSubscriptionRole all

-withSubscriptionRole 00000000-0000-0000-0000-000000000000, 11111111-1111-1111-1111-111111111111

-withKeyVaultPolicies all

-withKeyVaultPolicies  keyVaultName_1,  keyVaultName_n

-withKubernetesRole all

-withKubernetesRole 00000000-0000-0000-0000-000000000000, 11111111-1111-1111-1111-111111111111

-withReservationRole all

-withReservationRole 00000000-0000-0000-0000-000000000000, 11111111-1111-1111-1111-11111111111

-dryRun

-generateTemplate

-fromTemplate register-cloudaware-parameters.json

Examples of the module execution

To output the information about the module Register-Cloudaware:

Get-Help Register-Cloudaware -Full 

To output the examples of the module Register-Cloudaware execution:

Get-Help Register-Cloudaware -Examples

To output the list of parameters and their description:

Get-Help Register-Cloudaware -Parameter *

Examples of Register-Cloudaware module execution:

1. Launching the module in the command line using a list of all parameters. Use the switch -dryRun to save the parameters and their values that will be used to create the AD application during the module run:

Register-Cloudaware -name cloudaware-api-access `
                    -credentialExpiration 10 `
                    -certificateFile cert.pem `
                    -redirectUri 'https://cloudaware-api-access.com' `
                    -withSubscriptionRole all `
                    -withKeyVaultPolicies keyVaultName_1, keyVaultName_2 `
                    -withKubernetesRole all `
                    -withReservationRole all `
                    -dryRun `
                    -verbose

2. Launching the module using the switch -fromFile to read the values of parameters ​​from a json file. Use the switch -dryRun to display the list of parameters and their values that will be used during the module run:

# Template generate
Register-Cloudaware -generateTemplate

You will get the file '~\cloudaware\template.json' file containing the sample of structure format that needs to be followed.

Using the file 'template.json' file as a sample, create a file with necessary parameters, i.e., 'register-cloudaware-parameters.json'.

Register-Cloudaware -fromTemplate '~\cloudaware\register-cloudaware-parameters.json' `
                    -dryRun `
                    -verbose

3. Launching the module using a pipeline to read the values of parameters ​​from a json file. Use the switch -dryRun to display the list of parameters and their values that will be used during the module run:

# Template generate
Register-Cloudaware -generateTemplate

You will get the file '~\cloudaware\template.json file' containing the sample of structure format that needs to be followed.

Using the file 'template.json file' as a sample, create a file with necessary parameters, i.e., 'register-cloudaware-parameters.json'.

Get-Content -Raw '~\cloudaware\register-cloudaware-parameters.json' `
                | ConvertFrom-Json ` 
                | Register-Cloudaware -dryRun -verbose

Load the generated data to integrate with Cloudaware CMDB

After the module Register-Cloudaware is executed, the user has the option to download necessary files from из Azure Cloud Shell:

1. In Azure Cloud Shell go to the directory cd ~\cloudaware\ and run the command ls -la.

The directory ~\cloudaware\ may comprise:
1) The file Register-Cloudaware.ps1 containing the module Register-Cloudaware;
2) The file template.json containing the sample structure of required parameters and the guidelines for their population;
3) The .json files containing the parameters and values that will be used by the module Register-Cloudaware when the switch -fromTemplate or a pipeline is used for creating the application in AD;
4) The .log file containing the information about the module execution progress (the file has the following format: log.log);
5) The .json files containing the parameters and their values that will be used when creating or deleting the AD application (the files have the following formats: dryRunToCreateApp_<USER_PRINCIPAL_NAME><APPLICATION_NAME>.json and dryRunToDeleteApp_<USER_PRINCIPAL_NAME>_<APPLICATION_NAME>.json>).
6) The .json files containing the data required for integration with Cloudaware CMDB (the file has the following format: result_<USER_PRINCIPAL_NAME>_<APP_ID>.json);
7) The .key and .cert files generated automatically when the AD application was created (the file has the following format: <USER_PRINCIPAL_NAME>_<APP_ID>.key и <USER_PRINCIPAL_NAME>_<APP_ID>.cert).

Copy the file name (result_<USER_PRINCIPAL_NAME>_<APP_ID>.json):

2. Click Upload/Download file → Download:

3. Paste the file name (result_<USER_PRINCIPAL_NAME>_<APP_ID>.json) and click Download:

NOTE: If the switch -createKeyAndSertificate is specified in parameters, download private and public certificates that will be required for further integration with Cloudaware CMDB [not available yet, Client Secret is currently used instead].

4. Use the file to enable Azure Active Directory integration based on this start guide.

Troubleshooting

1. The error message below means that the user who logged in to Azure using az cli doesn't have the role 'Global Administrator' assigned on the AD level:

   CODE

   [2020-01-01 00:00:00] The user does not have the role 'Global administrator' assigned.

   
   Steps to check and fix:

   • Sign in to your Azure portal.

   • On the left navigation panel, select All services.

   • On the page in the All services search bar enter Users and choose it.

   • In the search users bar enter the name of the current user and select it.

   • On the page, select Assigned roles.
     
     Learn more about Azure AD roles.
     

2. The error message below means that the AD application name you are attempting to use already exists:

   CODE

   [2020-01-01 00:00:00] The AD application 'cloudaware-api-access' already exists.

   
   Steps to check and fix:

   • Sign in to your Azure portal.

   • On the left navigation panel, select All services.

   • On the page in the All services search bar enter App registrations and choose it.

   • Select All Applications, and in the search bar enter the name of the app you used.
     

     Learn more about Application management.
     

3. The error message below means that the user who logged in to Azure using az cli doesn't have access to none of Subscription(s), however, the parameter required for assigning roles or policies (-withSubscriptionRole, -withKeyVaultPolicies, -withKubernetesRole, -withReservationRole) is passed:

   CODE

   [2020-01-01 00:00:00] Impossible to assign role(s) or a policy to the AD application 'cloudaware-api-access': Subscription(s) are not available.

   
   Steps to check and fix:

   • Sign in to your Azure portal.

   • On the left navigation panel, select All services.

   • On the page in the All services search bar enter Users and chose it.

   • In the search users bar enter the name of the current user and select it.

   • On the page, select Azure role assignments.
     

     Learn more about Azure RBAC.
     

4. The error message below means that the user passed a value of incorrect data type in the parameter 'redirectUri':

   CODE

   [2020-01-01 00:00:00] The value of the parameter 'name' does not correspond to the data type [String]: '123'
   OR
   [2020-01-01 00:00:00] The value of the parameter 'redirectUri' does not correspond to the data type [String]: '123'

   
   Steps to fix:

   • Use a string value.
     

5. The error message below means that the user passed a value of incorrect data type in the parameter 'certificateFile':

   CODE

   [2020-01-01 00:00:00] The value of the parameter 'credentialExpiration' does not correspond to the data type [Int]: '3.5'

   
   Steps to fix:

   • Use an integer value.
     

6. The error message below means that the user passed incorrect path for the parameter 'certificateFile':

   CODE

   [2020-01-01 00:00:00] The path in the parameter 'certificateFile' is not correct: './cert.pem'

   
   Steps to fix:

   • Use the correct path to the certificate.
     

7. The error message below means that the user who logged in to Azure using az cli doesn’t have the role 'Owner' to be able to assign the role 'Reader' to all or several of Subscription ID(s):

   CODE

   [2020-01-01 00:00:00] Subscription ID(s) from 'withSubscriptionRole', where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']
   OR
   [2020-01-01 00:00:00] Subscription ID(s) from 'withKubernetesRole', where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']

   
   Steps to fix:

   • Contact your Azure Global administrator to get the role 'Owner' assigned. Once the role is assigned, re-run the module.
     

     Learn more about Azure RBAC.
     

8. The error message below means that the user who logged in to Azure using az cli doesn't have the role 'Owner' to be able to assign the role 'Reader' to all or several of Reservation Order ID(s):

   CODE

   [2020-01-01 00:00:00] Reservation Order ID(s), where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']

   
   Steps to fix:

   • Contact your Azure Global administrator to get the role 'Owner' assigned. Once the role is assigned, re-run the module.
     

     Learn more about Azure RBAC.
     

9. The error message below means that Key Vault name(s) are either unavailable to a user who logged in to Azure or incorrect:

   CODE

   [2020-01-01 00:00:00] Key Vault name(s) that are not associated with any of the available Subscription ID(s): ['keyVaultName_1']

   
   Steps to fix:

   • Check on whether Key Vault name(s) passed by the user are correct.

   • Contact your Azure Global administrator to get the role 'Owner' assigned. Once the role is assigned, re-run the module.
     

10. The error message below means that the organization doesn’t have any Reservation(s):

    CODE

    [2020-01-01 00:00:00] Reservation Order ID(s) were not discovered.

    
    Steps to check and fix:

    • Sign in to your Azure portal.

    • On the left navigation panel, select All services.

    • On the page in the All services search bar enter Reservations and choose it.

    • If no Reservation(s) is available at this point - Reservation(s) haven't been created in your organization.

      Learn more about Azure Reservations.
      

11. The error message below means that the scope value for Reservation Order ID(s) is not 'Shared':

    CODE

    [2020-01-01 00:00:00] Reservation Order ID(s) where the scope is not set up as 'Shared': ['00000000-0000-0000-0000-000000000000']

    
    Steps to check and fix:

    • Sign in to your Azure portal.

    • On the left navigation panel, select All services.

    • On the page in the All services search bar enter Reservations and choose it.

    • Select the Reservation which you need.

    • On the page select Configuration.
      

      Learn more about Reservation scoping options.
      

12. The error message below means that the user who logged in to Azure using az cli doesn't have the role 'Owner' to be able to assign the policy to Key Vaults to all or several of Subscription ID(s):

    CODE

    [2020-01-01 00:00:00] Subscription ID(s) from 'withKeyVaultPolicies', where the user does not have the role 'Owner' (RBAC) assigned: ['00000000-0000-0000-0000-000000000000']

    
    Steps to fix:

    • Contact your Azure Global administrator to get the role 'Owner' assigned. Once the role is assigned, re-run the module
      

      Learn more about Azure RBAC.
      

13. The error message below means that the parameter -redirectUri passed during the AD application creation contains a link of invalid format:
    

    CODE

    [2020-01-01 00:00:00] Invalid value specified for property 'replyUrls' of resource 'Application': 'cloudaware-api-access'. Detailed information: 'https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url'

    
    Steps to fix:

    • Ensure that the value of -redirectUri meets the requirements (see the link below).

    • Re-launch the module Register-Cloudaware.

    
    Learn more about Register an application with the Microsoft identity platform.
    

14. The error message below means that the parameter -certificateFile passed during the AD application creation contains the path to an invalid certificate:

    CODE

    [2020-01-01 00:00:00] ValidationError: Incorrect padding. Detailed information: 'https://docs.microsoft.com/en-us/cli/azure/ad/app/credential?view=azure-cli-latest#az_ad_app_credential_reset'

    
    Steps to fix:

    • Ensure that the certificate has been generated correctly.

    • Re-launch the module Register-Cloudaware.
      
      Learn more about az ad app credential reset.
      

15. The error message below means that the switch -createKeyAndSertificate has been passed during the AD application creation, however, an error occurred when processing the request:

    CODE

    [2020-01-01 00:00:00] Deleting the AD application 'cloudaware-api-access': an error occurred while creating certificates.

    
    Steps to fix:

    • Temporary Internet connection issue may have occurred (if the module is run locally on your work station) - re-launch the module.
      

16. The error message below means that an issue occurred when granting access permissions to the created AD application:

    CODE

    [2020-01-01 00:00:00] Deleting the AD application 'cloudaware-api-access': API permissions were not assigned correctly.

    
    Steps to fix:

    • Temporary Internet connection issue may have occurred (if the module is run locally on your work station) - re-launch the module.

    • There is a problem occurring with standard built-in PS modules and/or with az cli that may be used in Azure Cloud Shell - contact support@clodaware.com or raise a request at Cloudaware Service Desk Portal.