Register WorkZone in Azure

WorkZone Azure AD registration

WorkZone uses the Microsoft identity platform for identity and access management tasks. To set up a trust relationship between WorkZone and the Microsoft identity platform, the WorkZone application must be registered.

The WorkZone SharePoint and WorkZone Process modules require additional application registrations.

Prerequisite:

When creating an application registration for WorkZone, the full hostname of the WorkZone instance must be used as the identifier URI. For example, if WorkZone should be accessible at https://wzExample.test.workzone.cloud, then the identifier URI must be "https://wzExample.test.workzone.cloud".

Because of the requirements for the identifier URIs, only verified custom domains can be used in the URIs. For more information about adding a custom domain, see the Microsoft article Add your custom domain name using the Azure Active Directory portal.

If you have issues with the verification of the domain, WorkZone DevOps can assist you.

Register the application

Note: The download location for the scripts mentioned in this topic will be supplied when you request a WorkZone environment.

To register WorkZone in your Azure AD, run the New-KmdWorkZoneIdentityAp.ps1 script.

Use the following parameters:

  • DisplayName: Display name of the Azure AD app.
  • IdentifierUri: Identifier URI of the Azure AD app that is also used for updates (script reruns). See the prerequisite for the domain above.
  • ReplyUrlPrefix: Prefix for the reply URLs. This should match the IdentifierUri. For example, https://wzExample.test.workzone.cloud.
  • TenantId: Azure AD Tenant ID.
  • SharepointDomain: The SharePoint domain name, for example spExample if your SharePoint domain is spExample.sharepoint.com. Only provide this parameter if your WorkZone installation also includes the WorkZone SharePoint connector.
Example: 
.\New-KmdWorkZoneIdentityApp.ps1 `
	-DisplayName 'KMD WorkZone - Production' `
	-IdentifierUri 'https://wzExample.test.workzone.cloud' `
	-ReplyUrlPrefix 'https://wzExample.test.workzone.cloud' `
	-TenantId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX `
	-SharepointDomain 'spExample'

The script will output a client (application) identifier, a tenant ID, and a client secret that must be delivered to KMD.

Register the application for WorkZone Process

An additional registration is needed to send emails from WorkZone Process. This registration will allow interaction with Exchange Online. Because the privileges that are granted are broad, the application access must be scoped down to one mailbox.

To create an application registration for WorkZone Process, run the New-KmdWorkZoneExchangeApp.ps1 script.

The script uses the following parameters:

  • DisplayName: Display name of the Azure AD app.
  • TenantId: Azure AD Tenant ID.
  • IdentifierUriPrefix: Unique name prefix used for application registration Uri.
  • ExchangeOnlineAuthFlow: ClientCredential (recommended) or PublicClient.

Example: 


.\New-KmdWorkZoneExchangeApp.ps1 `
	-DisplayName 'KMD WorkZone - Production - Exchange' `
	-TenantId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX `
	-IdentifierUriPrefix 'Production' ` 
	-ExchangeOnlineAuthFlow ClientCredential

See Command line configuration of WorkZone Process for more details.

The script will output a client (application) identifier, tenant ID, and a client secret that must be delivered to KMD.

After running the script:

  1. Inform KMD about the client (application) identifier, tenant ID, and a client secret that the script returns.

  2. The script also returns the following message:

    "Permissions for this App requires Admin Consent. Please go to Azure Portal and 'Grant Permission' for this App or go directly to this consent url and log in as an AAD Admin (ignore that the redirect in the end might not work)".

    Follow the instructions in the message to grant Admin Consent to the WorkZone Process application.

Secure WorkZone Process application registration

Important:

Application access must be limited to a single mailbox used by WorkZone Process using an application access policy. For more information, see the Microsoft documentation Limiting application permissions to specific Exchange Online mailboxes. Use the PowerShell script Set-WZPAppRegistrationScope.ps1 to set the access limitation.

Prerequisite:

The script requires that the PowerShell ExchangeOnlineManagement module is installed. Before you execute the script, you need to connect to Exchange Online by running:

Connect-ExchangeOnline -UserPrincipalName <Exchange administrator account>

The following parameters are required by the script:

  • wzpMailbox: The mailbox that the application should have access to.
  • wzpAppId: The application (client) ID of the WorkZone Process application registration.
  • groupName: Name of the Azure AD group that manages security for the application registration.

Example: 


.\Set-WZPAppRegistrationScope.ps1 `
	-wzpMailbox example@yourdomain.com `
	-wzpAppId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
	-groupName "KMD WorkZone Process Production"