Script for App Registration in Microsoft Entra ID

Required Permissions: IT Admin 

To perform the app registration in Microsoft Entra ID, a package is provided that enables the setup via a script and automates the entire process.

The package contains two PowerShell scripts – one script that is used to create the app registration and an optional script that is only executed if empower® Mails Online is used.

The third file is a configuration file that is used to define important parameters for the registration script in advance to speed up the process.

The package can be downloaded from the following link:

Download App Registration Package

In total, the package contains the following three files:

  • config.json: Configuration file used to define important parameters.

  • EntraIdAppRegistration.ps1: Script used for the app registration.

  • EntraIdAppRegistration_MailsOnline.ps1: Script used for further configuration regarding empower® Mails Online (optional)

Note

The PowerShell scripts are compatible with the Microsoft Graph PowerShell module version 2.19.0.

Configuration File

The file config.json is important for the script's setup. It contains important information regarding the configuration.

Note

If you download the package, you can prepare the file yourself according to your requirements.

The content of the configuration file looks as follows:

 
{
  "tenantID": "Tenant ID from Entra ID"
  "appName": "empower",
  "hostname": "https://",
  "useMailsOnline": false,
  "useSCIM": false,
  "oneTimePasswordServiceUri": "https://oneoffsecret.com/"
}

The values need to be filled in as follows:

  • tenantID: Tenant ID.

    This value needs to be provided by you.

  • appName: The name for the application.

  • hostname: The base URL for the application.

  • useMailsOnline: Indication if empower® Mails Online will be used or not.

    If this setting is set to true, the extensions for empower® Mails Online are added to the app registration.

  • useSCIM: Indication if SCIM will be used as provisioning method.

    If this setting is set to true, the app registration for SCIM is created with delegated permissions only.

  • oneTimePasswordServiceUri: Service used to transmit the client secret.

    The following services are currently approved for this setting:

    https://oneoffsecret.com/ 

    https://snappass.symplasson.de/ 

Note

If you are not hosting in the empower® Cloud, you need to collect all required information (Tenant ID, base URL) yourself before executing the script.

Execute the Script in PowerShell

To be able to execute the script in PowerShell, make sure the following prerequisites are met:

  • Install the MS Graph PowerShell module.

    For further information from Microsoft regarding the installation of PowerShell, see Install the Microsoft Graph PowerShell SDK.

  • Extract the .zip folder.

  • Open PowerShell as an administrator from the unpacked folder.

To execute the script via PowerShell, follow the following steps:

  1. Execute the script EntraIdAppRegistration.ps1 in the path where it is located using the following command:

    .\EntraIdAppRegistration.ps1 

    The script will use the values from the configuration file as default values.

  2. Enter the Tenant ID.

    The Tenant ID can be found under Overview in your Azure Portal.

    To apply the default from the configuration file, press Enter.

  3. In the login window, log in with the user who has access to the VM.

    1. If permissions are requested, accept these permissions.

  4. Enter the name for the app registration.

    To apply the default from the configuration file, press Enter.

  5. Enter the base URL.

    To apply the default from the configuration file, press Enter.

  6. If you want to use empower® Mails Online, enter true.

    If you do not want to use empower® Mails Online, enter false.

    To apply the default from the configuration file, press Enter.

    The app registration will be created automatically.

  7. Copy the values shown on the screen (Tenant ID, Client ID and Client Secret).

    The client secret can only be copied via a one-time password link. Open the link to view the client secret and store it securely.

    These values are required for the installation of the empower® Backend.

    Alternatively, the values can be found in the file AppRegistrationInfo.json which is placed in the execution directory after finishing the execution.

The app registration can then be viewed under the tab App registrations in your Azure Portal.

Important

The one-time password for the client secret is only visible once and expires after one month.

Make sure to save the client secret securely.

Important

The setting useSCIM is only read from the configuration file. In the script itself, you are not asked if you want to use SCIM.

The setting is used to define which permissions need to be granted to the app registration.

In addition, you need to make further manual changes to the app registration after creation.

For further information, see Set up Microsoft Entra ID for SCIM.

Note

If the file config.json has not been customized according to your needs in advance, you need to enter all values manually.

Execute the Script in Cloud Shell

To execute the script via Cloud Shell, follow the following steps:

  1. Make sure you are connected to the tenant in which you want to create the app registration.

  2. Extract the .zip folder before executing the script.

  3. In your browser, enter shell.azure.com.

    1. If you use Cloud Shell for the first time, a dialog opens.

      Select a subscription and click on the button Create storage.

      A storage account for Cloud Shell is created.

  4. In the drop-down menu in the upper right corner of the window, select the option PowerShell.

  5. Click on the document symbol and then choose the option Upload.

  6. Select all three files from your file system and upload it.

  7. Then, execute the main script using the following command:

    .\EntraIdAppRegistration.ps1 

  8. Enter the name for the app registration.

    To apply the default from the configuration file, press Enter.

  9. Enter the base URL.

    To apply the default from the configuration file, press Enter.

  10. If you want to use empower® Mails Online, enter true.

    If you do not want to use empower® Mails Online, enter false.

    To apply the default from the configuration file, press Enter.

    The app registration will be created automatically.

  11. Copy the values shown on the screen (Tenant ID, Client ID and Client Secret).

    The client secret can only be copied via a one-time password link. Open the link to view the client secret and store it securely.

    These values are required for the installation of the empower® Backend.

    1. Alternatively, click on the document symbol again and then choose the option Download.

    2. Enter the file name AppRegistrationInfo.json into the input field and click on the button Download.

      The values can now also be found in the file AppRegistrationInfo.json.

The app registration can then be viewed under the tab App registrations in your Azure Portal.

Important

The one-time password for the client secret is only visible once and expires after one month.

Make sure to save the client secret securely.

Note

If you do not upload the file config.json or if it has not been customized according to your needs in advance, you need to enter all values manually.

Provide empower® with Configuration Details

If you are hosting in the empower® Cloud, you need to provide the empower® Support Team with further information.

To do so, send over the file AppRegistrationInfo.json to empower® Support.

In addition to the information in the file AppRegistrationInfo.json, provide the empower® Support Team with the following information:

  • empower® Group Object ID

    This ID is a globally unique identifier (GUID), or more precisely: an  Entra ID User Group, which is used to synchronize users to empower®.

    This way, empower® does not synchronize your complete Entra ID Tenant, but only the users that will work with empower®.

  • Entra ID Group Display Name

    In order to grant permissions within empower®, not only users but also groups are synchronized.

    Therefore, it is useful to work with empower® Groups or with groups that can be clustered together via name. These names should always start with empower.

    For example: empower® User Group = empower_users – empower® Admin Group = empower_adminusers.

    This way, permissions in empower® can be applied directly to the Entra ID groups.

  • Client Secret Expiry Date

Note

You will receive a reminder from empower® before your current client secret expires.

Note

For further information regarding the creation of user groups in Microsoft Entra ID, see Manage Microsoft Entra groups and group membership.

Was this article helpful?

/

Comments

0 comments

Article is closed for comments.