Skip to main content
Skip table of contents

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):

POWERSHELL
az login

4. Upload the file Register-Cloudaware.ps1

CODE
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:

CODE
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

Parameters

Function

-name <NAME>

Name of the AD application to be created.

POWERSHELL
-name cloudaware-api-access

-credentialExpiration <YEAR>

Expiration date of the AD application credentials, year.

POWERSHELL
-credentialExpiration 1


-certificateFile <path_to_PEM_FILE_NAME>

Path to the file containing the certificate.

CODE
-certificateFile cert.pem


-createKeyAndSertificate

The switch allows to automatically generate .key и .cert and use them in the AD application that is being created.
The generated files .key и .cert will be available in the directory ~\cloudaware. Files names have the following format: <USER_PRINCIPAL_NAME>_<APP_ID>.

CODE
-createKeyAndSertificate

-redirectUri <URI>

Redirect URI for the AD application to be created. Learn more about redirect URI (reply URL) restrictions and limitations.

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

-withSubscriptionRole <ID1 [,ID2, IDn]>

The Subscription ID(s) that the newly created AD application will have the role Reader assigned to.

The value of the parameter withSubscriptionRole to assign the role 'Reader' to the AD application to all Subscription ID(s) that are available to the user: all

CODE
-withSubscriptionRole all

Specify the particular Subscription ID(s) to which the AD application should have access to with the role 'Reader':

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

If the parameter withSubscriptionRole is not specified - the role is ignored.



-withKeyVaultPolicies <NAME1 [,NAME2, NAMEn]>

The Key Vault name(s) where the policy 'list' will be assigned to keys и secrets, so that Key Vault metadata ('Azure Key Vault Key' and 'Azure Key Vault Secret') is accessible by Cloudaware CMDB.

The value of the parameter withKeyVaultPolicies to grant the AD application with access to Key Vault(s) in the scope of all Subscription ID(s) that are available to the user: all

CODE
-withKeyVaultPolicies all

Specify the particular Key Vault name(s) to which the AD application should have access to with the policy 'list' applied:

CODE
-withKeyVaultPolicies  keyVaultName_1,  keyVaultName_n

If the parameter withKeyVaultPolicies is not specified - the policy is ignored.






-withKubernetesRole <ID1 [,ID2, IDn]>

The Subscription ID(s) that the newly created AD application will have the role Azure Kubernetes Service Cluster Admin Role assigned to.

The value of the parameter withKubernetesRole to assign the role 'Azure Kubernetes Service Cluster Admin Role' to the AD application to all subscriptions that are available to the user: all

CODE
-withKubernetesRole all

Specify the particular Subscription ID(s) to which the AD application should have access to with the role 'Azure Kubernetes Service Cluster Admin Role':

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

If the parameter withKubernetesRole is not specified - the role is ignored.



-withReservationRole <ID1 [,ID2, IDn]>

The Reservation Order ID(s) that the newly created AD application will have the role Reader assigned to.

The 'Reader' role can be assigned to the created AD application, provided that scope for Reservation Order ID(s) is configured as 'Shared': learn more about Reservation scoping options.

The value of the parameter withReservationRole to assign the role 'Reader' to the AD application to all Subscription ID(s) that are available to the user: all

CODE
-withReservationRole all

Specify the particular Reservation Order ID(s) to which the AD application should have access to with the role 'Reader':

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

If the parameter withReservationRole is not specified - the role is ignored.

-dryRun

The switch allows to save the list of parameters and their values that will be used when creating the AD application during the module Register-Cloudaware run.


The saved file will be available in the path ~\cloudaware\dryRunToCreateApp_<USER_PRINCIPAL_NAME>_<APPLICATION_NAME>.json

POWERSHELL
-dryRun

-generateTemplate

The switch allows to automatically generate a .json file that contains a sample structure of required parameters and the guidelines for their population.
The generated file will be available in path ~\cloudaware\template.json.

POWERSHELL
-generateTemplate


-fromTemplate <path_to_JSON_FILE_NAME>

Path to the .json file containing the mentioned parameters.

CODE
-fromTemplate register-cloudaware-parameters.json

Examples of the module execution


To output the information about the module Register-Cloudaware:

CODE
Get-Help Register-Cloudaware -Full 

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

CODE
Get-Help Register-Cloudaware -Examples

To output the list of parameters and their description:

CODE
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:

CODE
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:

CODE
# 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'.

CODE
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:

CODE
# 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'.

CODE
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 fileDownload:

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.