+ Title: Configure Azure Active Directory B2C with Akamai Web Application Protector

+description: Configure Akamai Web Application Protector with Azure AD B2C

+# Configure Azure Active Directory B2C with Akamai Web Application Protector

+Learn to enable Akamai Web Application Protector (WAP) for Azure Active Directory B2C (Azure AD B2C) tenant using custom domains. Akamai WAP helps organization protect their web applications from malicious attacks that aim to exploit vulnerabilities such as SQL injection and Cross site scripting.

+Learn more on akamai.com: [What Is a Web Application Firewall (WAF)?](https://www.akamai.com/glossary/what-is-a-waf)

+Benefits of using WAF:

+* Control traffic management to your services

+* Configure in front of an Azure AD B2C tenant

+* Manipulate traffic to protect and secure your identity infrastructure

+This article applies to:

+WAP: [Web Application Protector](https://www.akamai.com/products/web-application-protector)

+KSD: [Kona Site Defender](https://www.akamai.com/us/en/products/security/kona-site-defender.jsp)

+* An Azure subscription

+ * If you don't have one, get an [Azure free account](https://azure.microsoft.com/free/)

+* An Azure AD B2C tenant linked to your Azure subscription

+ * See, [Tutorial: Create an Azure Active Directory B2C tenant](tutorial-create-tenant.md)

+* An Akamai WAP account

+ * Go to akamai.com for [Explore all Akamai products and trials](https://www.akamai.com/us/en/akamai-free-trials.jsp)

+Akamai WAP integration includes the following components:

+* **Azure AD B2C** ΓÇô the authorization server that verifies user credentials with custom policies in the tenant. Also known as the identity provider (IdP).

+* **Azure Front Door** ΓÇô enables custom domains for the Azure B2C tenant

+ * Traffic from Akamai WAP routs to Azure Front Door then goes to the Azure AD B2C tenant

+ * [What is Azure Front Door?](../frontdoor/front-door-overview.md)

+* **Akamai WAP** ΓÇô The web application firewall that manages traffic sent to the authorization server

+ * See, [Web Application Protector](https://www.akamai.com/us/en/resources/waf.jsp)

+For custom domains in Azure AD B2C, use the custom domain feature in Azure Front Door.

+See, [Enable custom domains for Azure AD B2C](./custom-domain.md?pivots=b2c-user-flow).

+When the custom domain for Azure AD B2C is configured using Azure Front Door, use the following instructions to test the custom domain.

+See, [Test your custom domain](./custom-domain.md?pivots=b2c-custom-policy#test-your-custom-domain), then proceed to the next section.

+## Create an Akamai account

+1. Go to [akamai.com](https://www.akamai.com).

+2. Select **Learn more**.

+3. On the **Cloud Computing Services** page, select **Create account**.

+### Create and configure a property

+A property is a configuration file that tells our edge servers how to handle and respond to incoming requests from your end users. Properties are created and maintained in Property Manager.

+To learn more, go to techdocs.akamai.com for [What is a Property?](https://techdocs.akamai.com/start/docs/prop)

+1. Go to control.akamai.com to sign in: [Akamai Control Center sign in page](https://control.akamai.com/wh/CUSTOMER/AKAMAI/en-US/WEBHELP/property-manager/property-manager-help/GUID-14BB87F2-282F-4C4A-8043-B422344884E6.html).

+2. Go to Property Manager.

+3. For **Property version**, select **Standard** or **Enhanced TLS** (recommended).

+4. For **Property hostnames**, add a property hostname, your custom domain. For example, `login.domain.com`.

+ > [!IMPORTANT]

+ > Create or modify certificates with correct custom domain name settings. </br> Go to techdocs.akamai.com for [Configure HTTPS hostnames](https://learn.akamai.com/en-us/webhelp/property-manager/https-delivery-with-property-manager/GUID-9EE0EB6A-E62B-4F5F-9340-60CBD093A429.html).

+#### Origin server property configuration settings

+Use the following settings for origin server.

+1. For **Origin type**, enter your type.

+2. For **Origin server hostname** enter your hostname. For example, `yourafddomain.azurefd.net`

+3. For **Forward host header**, use **Incoming Host Header**.

+4. For **Cache key hostname** use **Incoming Host Header**.

+### Configure DNS

+Create a Canonical Name (CNAME) record in your DNS, such as `login.domain.com`, which points to the Edge hostname in the **Property hostname** field.

+### Configure Akamai WAP

+1. To get started with WAP configuration, go to techdocs.akamai.com for [App & API Protector](https://techdocs.akamai.com/cloud-security/docs/app-api-protector).

+2. During configuration, for items in **Attack Group**, under **Rule Actions**, select **Deny**.

+ 

+To ensure traffic to Azure AD B2C goes through the custom domain:

+* Confirm WAP routes incoming requests to the Azure AD B2C custom domain

+ * Ensure a valid TLS connection

+* Ensure Azure AD B2C sets cookies correctly for the custom domain

+* The WAP dashboard in Defender for Cloud console has WAP traffic charts

+ * Attack traffic also appears

+* [Enable custom domains for Azure Active Directory B2C](./custom-domain.md?pivots=b2c-user-flow)

+* [Tutorial: Create user flows and custom policies in Azure AD B2C](./tutorial-create-user-flows.md?pivots=b2c-custom-policy&tabs=applications)

+ Title: Configure Asignio with Azure Active Directory B2C for multifactor authentication

+description: Configure Azure Active Directory B2C with Asignio for multifactor authentication

+# Configure Asignio with Azure Active Directory B2C for multifactor authentication

+Learn to integrate Azure Active Directory (Azure AD B2C) authentication with [Asignio](https://www.asignio.com/). With this integration, provide passwordless, soft biometric, and multifactor authentication experience to customers. Asignio uses patented Asignio Signature and live facial verification for user authentication. The changeable biometric signature helps to reduce passwords, fraud, phishing, and credential reuse through omni-channel authentication.

+## Before you begin

+Choose a policy type selector to indicate the policy type setup. Azure AD B2C has two methods to define how users interact with your applications:

+* Predefined user flows

+* Configurable custom policies

+The steps in this article differ for each method.

+Learn more:

+* [User flows and custom policies overview](user-flow-overview.md)

+* [Azure AD B2C custom policy overview](custom-policy-overview.md)

+## Prerequisites

+* An Azure AD subscription.

+* If you don't have on, get an [Azure free account](https://azure.microsoft.com/free/)

+- An Azure AD B2C tenant linked to the Azure subscription

+- See, [Tutorial: Create an Azure Active Directory B2C tenant](./tutorial-create-tenant.md)

+- An Asignio Client ID and Client Secret issued by Asignio.

+- These tokens are obtained by registering your mobile or web applications with Asignio.

+### For custom policies

+Complete [Tutorial: Create user flows and custom policies in Azure AD B2C](./tutorial-create-user-flows.md?pivots=b2c-custom-policy)

+## Scenario description

+This integration includes the following components:

+* **Azure AD B2C** - authorization server that verifies user credentials

+* **Web or mobile applications** - to secure with Asignio MFA

+* **Asignio web application** - signature biometric collection on the user touch device

+The following diagram illustrates the implementation.

+ 

+1. User opens Azure AD B2C sign in page on their mobile or web application, and then signs in or signs up.

+2. Azure AD B2C redirects the user to Asignio using an OpenID Connect (OIDC) request.

+3. The user is redirected to the Asignio web application for biometric sign in. If the user hasn't registered their Asignio Signature, they can use an SMS One-Time-Password (OTP) to authenticate. After authentication, user receives a registration link to create their Asignio Signature.

+4. The user authenticates with Asignio Signature and facial verification, or voice and facial verification.

+5. The challenge response goes to Asignio.

+6. Asignio returns the OIDC response to Azure AD B2C sign in.

+7. Azure AD B2C sends an authentication verification request to Asignio to confirm receipt of the authentication data.

+8. The user is granted or denied access to the application.

+## Configure an application with Asignio

+Configurating an application with Asignio is with the Asignio Partner Administration site.

+1. Go to asignio.com [Asignio Partner Administration](https://partner.asignio.com) page to request access for your organization.

+2. With credentials, sign into Asignio Partner Administration.

+3. Create a record for the Azure AD B2C application using your Azure AD B2C tenant. When you use Azure AD B2C with Asignio, Azure AD B2C manages connected applications. Asignio apps represent apps in the Azure portal.

+4. In the Asignio Partner Administration site, generate a Client ID and Client Secret.

+5. Note and store Client ID and Client Secret. You'll use them later. Asignio doesn't store Client Secrets.

+6. Enter the redirect URI in your site the user is returned to after authentication. Use the following URI pattern.

+`[https://<your-b2c-domain>.b2clogin.com/<your-b2c-domain>.onmicrosoft.com/oauth2/authresp]`.

+7. Upload a company logo. It appears on Asignio authentication when users sign in.

+## Register a web application in Azure AD B2C

+Register applications in a tenant you manage, then they can interact with Azure AD B2C.

+Learn more: [Application types that can be used in Active Directory B2C](application-types.md)

+For this tutorial, you're registering `https://jwt.ms`, a Microsoft web application with decoded token contents that don't leave your browser.

+### Register a web application and enable ID token implicit grant

+Complete [Tutorial: Register a web application in Azure Active Directory B2C](tutorial-register-applications.md?tabs=app-reg-ga)

+## Configure Asignio as an identity provider in Azure AD B2C

+For the following instructions, use the Azure AD tenant with the Azure subscription.

+1. Sign in to the [Azure portal](https://portal.azure.com/#home) as the Global Administrator of the Azure AD B2C tenant.

+2. In the Azure portal toolbar, select **Directories + subscriptions**.

+3. On **Portal settings | Directories + subscriptions**, in the **Directory name** list, locate your Azure AD directory.

+4. Select **Switch**.

+5. In the top-left corner of the Azure portal, select **All services**.

+6. Search for and select **Azure AD B2C**.

+7. In the Azure portal, search for and select **Azure AD B2C**.

+8. In the left menu, select **Identity providers**.

+9. Select **New OpenID Connect Provider**.

+10. Select **Identity provider type** > **OpenID Connect**.

+11. For **Name**, enter the Asignio sign in, or a name you choose.

+12. For **Metadata URL**, enter `https://authorization.asignio.com/.well-known/openid-configuration`.

+13. For **Client ID**, enter the Client ID you generated.

+14. For **Client Secret**, enter the Client Secret you generated.

+15. For **Scope**, use **openid email profile**.

+16. For **Response type**, use **code**.

+17. For **Response mode**, use **query**.

+18. For Domain hint, use `https://asignio.com`.

+19. Select **OK**.

+20. Select **Map this identity provider's claims**.

+21. For **User ID**, use **sub**.

+22. For **Display Name**, use **name**.

+23. For **Given Name**, use **given_name**.

+24. For **Surname**, use **family_name**.

+25. For **Emai**l, use **email**.

+26. Select **Save**.

+## SCreate a user flow policy

+2. Select **New user flow**.

+3. Select **Sign up and sign in** user flow type.

+4. Select **Version Recommended**.

+5. Select **Create**.

+6. Enter a user flow **Name**, such as `AsignioSignupSignin`.

+7. Under **Identity providers**, for **Local Accounts**, select **None**. This action disables email and password authentication.

+8. For **Custom identity providers**, select the created Asignio Identity provider.

+9. Select **Create**.

+## Test your user flow

+2. Select the created user flow.

+3. For **Application**, select the web application you registered. The **Reply URL** is `https://jwt.ms`.

+4. Select **Run user flow**.

+5. The browser is redirected to the Asignio sign in page.

+6. A sign in screen appears.

+7. At the bottom, select **Asignio** authentication.

+If you have an Asignio Signature, complete the prompt to authenticate. If not, supply the device phone number to authenticate via SMS OTP. Use the link to register your Asignio Signature.

+8. The browser is redirected to `https://jwt.ms`. The token contents returned by Azure AD B2C appear.

+## Create Asignio policy key

+1. Store the generated Client Secret in the Azure AD B2C tenant.

+2. Sign in to the [Azure portal](https://portal.azure.com/).

+3. In the portal toolbar, select the **Directories + subscriptions**.

+4. On **Portal settings | Directories + subscriptions**, in the **Directory name** list, locate your Azure AD B2C directory.

+5. Select **Switch**.

+6. In the top-left corner of the Azure portal, select **All services**.

+7. Search for and select **Azure AD B2C**.

+8. On the Overview page, select **Identity Experience Framework**.

+9. Select **Policy Keys**.

+10. Select **Add**.

+11. For **Options**, select **Manual**.

+12. Enter a policy key **Name** for the policy key. The prefix `B2C_1A_` is appended to the key name.

+13. In **Secret**, enter the Client Secret that you noted.

+14. For **Key usage**, select **Signature**.

+15. Select **Create**.

+## Configure Asignio as an Identity provider

+>Before you begin, ensure the Azure AD B2C policy is configured. If not, follow the instructions in [Custom policy starter pack](tutorial-create-user-flows.md?pivots=b2c-custom-policy#custom-policy-starter-pack).

+For users to sign in with Asignio, define Asignio as a claims provider that Azure AD B2C communicates with through an endpoint. The endpoint provides claims Azure AD B2C uses to verify user authentication with using digital ID on the device.

+### Add Asignio as a claims provider

+Get the custom policy starter packs from GitHub, then update the XML files in the LocalAccounts starter pack with your Azure AD B2C tenant name:

+1. Download the zip [active-directory-b2c-custom-policy-starterpack](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/archive/master.zip) or clone the repository:

+ ```

+ git clone https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack

+ ```

+

+2. In the files in the **LocalAccounts** directory, replace the string `yourtenant` with the Azure AD B2C tenant name.

+3. Open the **LocalAccounts/ TrustFrameworkExtensions.xml**.

+4. Find the **ClaimsProviders** element. If there isn't one, add it under the root element, `TrustFrameworkPolicy`.

+5. Add a new **ClaimsProvider** similar to the following example:

+6. Set **client_id** with the Asignio Application ID you noted.

+7. Update **client_secret** section with the policy key you created. For example, `B2C_1A_AsignioSecret`:

+8. Save the changes.

+## Add a user journey

+The identity provider isn't in the sign in pages.

+1. If you have a custom user journey continue to **Configure the relying party policy**, otherwise, copy a template user journey:

+2. From the starter pack, open the **LocalAccounts/ TrustFrameworkBase.xml**.

+3. Locate and copy the contents of the **UserJourney** element that include `Id=SignUpOrSignIn`.

+4. Open the **LocalAccounts/ TrustFrameworkExtensions.xml**.

+5. Locate the **UserJourneys** element. If there isn't one, add one.

+6. Paste the UserJourney element contents as a child of the UserJourneys element.]

+7. Rename the user journey **ID**. For example, `Id=AsignioSUSI`.

+Learn more: [User journeys](custom-policy-overview.md#user-journeys)

+## Add the identity provider to a user journey

+Add the new identity provider to the user journey.

+1. Find the orchestration step element that includes `Type=CombinedSignInAndSignUp`, or `Type=ClaimsProviderSelection` in the user journey. It's usually the first orchestration step. The **ClaimsProviderSelections** element has an identity provider list that users sign in with. The order of the elements controls the order of the sign in buttons.

+2. Add a **ClaimsProviderSelection** XML element.

+3. Set the value of **TargetClaimsExchangeId** to a friendly name.

+4. Add a **ClaimsExchange** element.

+5. Set the **Id** to the value of the target claims exchange ID.

+6. Update the value of **TechnicalProfileReferenceId** to the ID of the technical profile you created.

+The following XML demonstrates user journey orchestration with the identity provider.

+## Configure the relying party policy

+The relying party policy, for example [SignUpSignIn.xml](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/blob/main/LocalAccounts/SignUpOrSignin.xml), specifies the user journey Azure AD B2C executes.

+1. In the relying party, locate the **DefaultUserJourney** element.

+2. Update the **ReferenceId** to match the user journey ID, in which you added the identity provider.

+## Upload the custom policy

+2. In the portal toolbar, select the **Directories + subscriptions**.

+3. On **Portal settings | Directories + subscriptions**, in the **Directory name** list, locate your Azure AD B2C directory.

+4. Select **Switch**.

+5. In the Azure portal, search for and select **Azure AD B2C**.

+6. Under Policies, select **Identity Experience Framework**.

+7. Select **Upload Custom Policy**.

+8. Upload the two policy files you changed in the following order:

+ * Extension policy, for example `TrustFrameworkExtensions.xml`

+ * Relying party policy, such as `SignUpOrSignin.xml`

+## Test your custom policy

+1. In your Azure AD B2C tenant, and under **Policies**, select **Identity Experience Framework**.

+2. Under **Custom policies**, select **AsignioSUSI**.

+3. For **Application**, select the web application that you registered. The **Reply URL** is `https://jwt.ms`.

+4. Select **Run now**.

+5. The browser is redirected to the Asignio sign in page.

+6. A sign in screen appears.

+7. At the bottom, select **Asignio** authentication.

+If you have an Asignio Signature, you're prompted to authenticate with your Asignio Signature. If not, supply the device phone number to authenticate via SMS OTP. Use the link to register your Asignio Signature.

+8. The browser is redirected to `https://jwt.ms`. The token contents returned by Azure AD B2C appear.

+* [Solutions and Training for Azure Active Directory B2C](solution-articles.md)

+* Ask questions on [Stackoverflow](https://stackoverflow.com/questions/tagged/azure-ad-b2c)

+* [Azure AD B2C Samples](https://stackoverflow.com/questions/tagged/azure-ad-b2c)

+* YouTube: [Identity Azure AD B2C Series](https://www.youtube.com/playlist?list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0)

+* [Azure AD B2C custom policy overview](custom-policy-overview.md)

+* [Tutorial: Create user flows and custom policies in Azure Active Directory B2C](tutorial-create-user-flows.md?pivots=b2c-custom-policy)

+ Title: Configure xID with Azure Active Directory B2C for passwordless authentication

+In this tutorial, learn to integrate Azure Active Directory B2C (Azure AD B2C) authentication with the xID digital ID solution. The xID app provides users with passwordless, secure, multifactor authentication. The My Number Card, the digital ID card issued by the Japanese government, verifies xID-authenticated user identities. For their users, organizations can get verified Personal Identification Information (customer content) through the xID API. Furthermore, the xID app generates a private key in a secure area in user mobile devices, making them digital signing devices.

+* An Azure AD subscription

+ * If you don't have one, you can get an [Azure free account](https://azure.microsoft.com/free/)

+* An Azure AD B2C tenant linked to the Azure subscription

+ * See, [Tutorial: Create an Azure Active Directory B2C tenant](./tutorial-create-tenant.md)

+* Your xID client information provided by xID inc.

+* Go to the xid.inc [Contact Us](https://xid.inc/contact-us) page for xID client information:

+ * Client ID

+ * Client Secret

+ * Redirect URL

+ * Scopes

+* Go to x-id.me to install the [xID app](https://x-id.me/) on a mobile device:

+ * My Number Card

+ * If you use API UAT version, get the xID app UAT version. See, [Contact Us](https://xid.inc/contact-us)

+The following diagram shows the architecture.

+

+1. At the Azure AD B2C sign-in page user signs in or signs up.

+2. Azure AD B2C redirects the user to xID authorize API endpoint using an OpenID Connect (OIDC) request. An OIDC endpoint has endpoint information. xID identity provider (IdP) redirects the user to the xID authorization sign in page. User enters email address.

+3. xID IdP sends push notification to user mobile device.

+4. User opens the xID app, checks the request, enters a PIN, or uses biometrics. xID app activates the private key and creates an electronic signature.

+5. xID app sends the signature to xID IdP for verification.

+6. A consent screen appears to give personal information to the service.

+7. xID IdP returns the OAuth authorization code to Azure AD B2C.

+8. Azure AD B2C sends a token request using the authorization code.

+9. xID IdP checks the token request. If valid, OAuth access token is returned and the ID token with user identifier and email address.

+10. If user customer content is needed, Azure AD B2C calls the xID user data API.

+11. The xID user data API returns encrypted customer content. Users decrypt with a private key, created when requesting xID client information.

+12. User is granted or denied access to the customer application.

+## Install xID

+1. To request API documents, fill out the request form. Go to [Contact Us](https://xid.inc/contact-us).

+2. In the message, indicate you're using Azure AD B2C.

+3. An xID sales representative contacts you.

+4. Follow the instructions in the xID API document.

+5. Request an xID API client.

+6. xID tech team sends client information to you in 3-4 business days.

+7. Supply a redirect URI in your site using the following pattern. Users return to it after authentication.

+`https://<your-b2c-domain>.b2clogin.com/<your-b2c-domain>.onmicrosoft.com/oauth2/authresp`

+## Register a web application in Azure AD B2C

+Register applications in a tenant you manage, then they can interact with Azure AD B2C.

+Learn more: [Application types that can be used in Active Directory B2C](application-types.md)

+For testing, you register `https://jwt.ms`, a Microsoft web application with decoded token contents, which don't leave your browser.

+### Register a web application and enable ID token implicit grant

+Complete [Tutorial: Register a web application in Azure AD B2C](tutorial-register-applications.md?tabs=app-reg-ga)

+## Create a xID policy key

+Store the Client Secret from xID in your Azure AD B2C tenant. For the following instructions, use the directory with the Azure AD B2C tenant.

+1. Sign in to the [Azure portal](https://portal.azure.com/).

+2. In the portal toolbar, select **Directories + subscriptions**.

+3. On the **Portal settings | Directories + subscriptions** page, in the Directory name list, locate your Azure AD B2C directory.

+4. Select **Switch**.

+5. In the top-left corner of the Azure portal, select **All services**.

+6. Search for and select **Azure AD B2C**.

+7. On **Overview**, select **Identity Experience Framework**.

+8. Select **Policy Keys**.

+9. Select **Add**.

+10. For **Options**, select **Manual**.

+11. Enter a policy key **Name** for the policy key. The prefix `B2C_1A_` is appended to the key name.

+12. In **Secret**, enter the Client Secret from xID.

+13. For **Key usage**, select **Signature**.

+14. Select **Create**.

+ >[!NOTE]

+ >In Azure AD B2C, custom policies are for complex scenarios.

+ >

+ >See, [User flows and custom policies overview](./user-flow-overview.md).

+## Configure xID as identity provider

+For users to sign in using xID, make xID a claims provider that Azure AD B2C communicates with through an endpoint. The endpoint provides claims Azure AD B2C uses to verify users authenticated with digital identity on their device.

+### Add xID as a claims provider

+Get the custom policy starter packs from GitHub, then update the XML files in the SocialAccounts starter pack with your Azure AD B2C tenant name.

+1. Download the zip file [active-directory-b2c-policy-starterpack-main](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/archive/master.zip) or clone the repository. See, [Azure-Samples/active-directory-b2c-custom-policy-starterpack](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack).

+2. In the files in the **SocialAccounts** directory, replace the string `yourtenant` with the name of your Azure AD B2C tenant. For example, `yourtenant.onmicrosoft.com` becomes `contoso.onmicrosoft.com`.

+3. Open the **SocialAccounts/TrustFrameworkExtensions.xml**.

+4. Find the **ClaimsProviders** element. If there isn't one, add it under the root element.

+5. Add a new **ClaimsProvider** similar to the following example:

+6. Set **client_id** with your xID Application ID.

+7. Select **Save**.

+## Add a user journey

+Add an identity provider to sign-in pages.

+1. If you have a custom user journey, go to **Add the identity provider to a user journey**. Otherwise, create a duplicate of a template user journey:

+2. From the starter pack, open the **TrustFrameworkBase.xml**.

+3. Locate and copy the contents of the **UserJourneys** element that includes `ID=SignUpOrSignIn`.

+4. Open the **TrustFrameworkExtensions.xml** and locate the UserJourneys element. If there isn't one, add one.

+5. Paste the contents of the UserJourney element as a child of the UserJourneys element.

+6. Rename the user journey ID. For example, `ID=CustomSignUpSignIn`

+## Add the identity provider to a user journey

+Add the new identity provider to the user journey.

+1. Locate the orchestration step element with Type=`CombinedSignInAndSignUp`, or Type=`ClaimsProviderSelection` in the user journey. It's usually the first orchestration step. The **ClaimsProviderSelections** element has an identity provider list for signing in. The order of the elements controls the order of the sign-in buttons.

+2. Add a **ClaimsProviderSelection** XML element.

+3. Set the value of **TargetClaimsExchangeId** to a friendly name.

+4. Add a **ClaimsExchange** element.

+5. Set the **ID** to the value of the target claims exchange ID. This change links the xID button to `X-IDExchange` action.

+6. Update the **TechnicalProfileReferenceId** value to the technical profile ID you created (`X-ID-Oauth2`).

+7. Add an Orchestration step to call xID UserInfo endpoint to return claims about the authenticated user `X-ID-Userdata`.

+The following XML demonstrates the user journey orchestration with xID identity provider.

+There are identity claims xID supports referenced as part of the policy. Claims schema is where you declare the claims. The ClaimsSchema element has a ClaimType element list. The ClaimType element contains the ID attribute, which is the claim name.

+1. Open the **TrustFrameworksExtension.xml**.

+2. Locate the **BuildingBlocks** element.

+3. Add the following ClaimType element in the **ClaimsSchema** element of the **TrustFrameworksExtension.xml** policy

+## Configure the relying party policy

+The relying party policy, for example [SignUpSignIn.xml](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/blob/main/LocalAccounts/SignUpOrSignin.xml), specifies the user journey the Azure AD B2C executes.

+1. In the relying party,locate the **DefaultUserJourney** element.

+2. Update the **ReferenceId** to match the user journey ID you added to the identity provider.

+In the following example, for the xID user journey, the **ReferenceId** is set to `CombinedSignInAndSignUp`.

+## Upload the custom policy

+For the following instructions, use the directory with the Azure AD B2C tenant.

+1. Sign in to the [Azure portal](https://portal.azure.com/#home).

+2. In the portal toolbar, select the **Directories + subscriptions**.

+3. On the **Portal settings | Directories + subscriptions** page, in the **Directory name** list. locate your Azure AD B2C directory.

+4. Select **Switch**.

+5. In the [Azure portal](https://portal.azure.com/#home), search for and select **Azure AD B2C**.

+6. Under Policies, select **Identity Experience Framework**.

+7. Select **Upload Custom Policy**.

+8. Upload the files in the following order:

+ * Base policy file: `TrustFrameworkBase.xml`

+ * Extension policy: `TrustFrameworkExtensions.xml`

+ * Relying party policy: `SignUpSignIn.xml`

+## Test the custom policy

+2. Under **Custom policies**, select **CustomSignUpSignIn**.

+3. For **Application**, select the web application that you registered. The **Reply URL** is `https://jwt.ms`.

+4. Select **Run now**.

+5. The browser redirects to the xID sign in page.

+6. The browser redirects to `https://jwt.ms`. The token contents returned by Azure AD B2C appear.

+* [Azure AD B2C custom policy overview](custom-policy-overview.md)

+* [Tutorial: Create user flows and custom policies in Azure AD B2C](tutorial-create-user-flows.md?pivots=b2c-custom-policy)

+ Title: Find out when a specific user is able to access an app in Azure Active Directory Application Provisioning

+description: How to find out when a critically important user is able to access an application you have configured for user provisioning with Azure Active Directory.

+The Azure AD provisioning service runs an initial provisioning cycle against the source system and target system, followed by periodic incremental cycles. When you configure provisioning for an app, you can check the current status of the provisioning service and see when a user is able to access an app.

+When you first configure automatic provisioning, the **Current Status** section at the bottom of the page shows the status of the initial provisioning cycle. This section updates each time an incremental cycle is run. The following details are shown:

+- A **progress bar** showing the percentage of the provisioning cycle that has completed. The percentage reflects the count of pages provisioned. Each page could contain multiple users or groups, so the percentage doesn't directly correlate to the number of users, groups, or roles provisioned.

+- The number of **Users** and **Groups** in the connector data store. The count increases anytime an object is added to the scope of provisioning. The count doesn't go down if a user is soft-deleted or hard-deleted because the operation doesn't remove the object from the connector data store. The count is recalculated the first sync after the CDS is [reset](/graph/api/synchronization-synchronizationjob-restart?tabs=http&view=graph-rest-beta&preserve-view=true)

+- A **View Audit Logs** link, which opens the Azure AD provisioning logs. To learn more about operations run by the user provisioning service, including provisioning status for individual users, see [Use provisioning logs](#use-provisioning-logs-to-check-a-users-provisioning-status) later in the article.

+The provisioning progress is viewed in the Azure portal at **Azure Active Directory &gt; Enterprise Apps &gt; \[application name\] &gt; Provisioning**.

+To see the provisioning status for a selected user, consult the [Provisioning logs (preview)](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context) in Azure AD. All operations run by the user provisioning service are recorded in the Azure AD provisioning logs. The logs include read and write operations made to the source and target systems. Associated user data related to read and write operations is also logged.

+For more information on how to read the provisioning logs in the Azure portal, see [provisioning reporting guide](check-status-user-account-provisioning.md).

+When you're using automatic user provisioning with an application, there are some things to keep in mind. First, Azure AD automatically provisions and updates user accounts in an app based on things like [user and group assignment](../manage-apps/assign-user-or-group-access-portal.md). The sync happens at a regularly scheduled time interval, typically every 40 minutes.

+- For **initial cycle**, the job time depends on many factors, including the number of users and groups in scope for provisioning, and the total number of users and group in the source system. The first sync between Azure AD and an app happen as fast as 20 minutes or take as long as several hours. The time depends on the size of the Azure AD directory and the number of users in scope for provisioning. A comprehensive list of factors that affect initial cycle performance are summarized later in this section.

+- For **incremental cycles**, after the initial cycle, job times tend to be faster (within 10 minutes), as the provisioning service stores watermarks that represent the state of both systems after the initial cycle, improving performance of subsequent syncs. The job time depends on the number of changes detected in that provisioning cycle. If there are fewer than 5,000 user or group membership changes, the job can finish within a single incremental provisioning cycle.

+- The number and sizes of assigned groups. Syncing assigned groups takes longer than syncing users. Both the number and the sizes of the assigned groups impact performance. If an application has [mappings enabled for group object sync](customize-application-attributes.md#editing-group-attribute-mappings), group properties such as group names and memberships are synced in addition to users. These syncs take longer than only syncing user objects.

+- If performance becomes an issue, and you're attempting to provision most users and groups in your tenant, then use scoping filters. Scoping filters allow you to fine tune the data that the provisioning service extracts from Azure AD by filtering out users based on specific attribute values. For more information on scoping filters, see [Attribute-based application provisioning with scoping filters](define-conditional-rules-for-provisioning-user-accounts.md).

+[Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](user-provisioning.md)

+Azure Active Directory (Azure AD) includes a [user account provisioning service](user-provisioning.md). The service helps automate the provisioning deprovisioning of user accounts in SaaS apps and other systems. The automation helps with end-to-end identity lifecycle management. Azure AD supports preintegrated user provisioning connectors for many applications and systems. To learn more about user provisioning tutorials, see [Provisioning Tutorials](../saas-apps/tutorial-list.md).

+Provisioning connectors are set up and configured using the [Azure portal](https://portal.azure.com), by following the [provided documentation](../saas-apps/tutorial-list.md) for the supported application. When the connector is configured and running, provisioning jobs can be reported using the following methods:

+This article uses the following terms:

+* **Source System** - The repository of users that the Azure AD provisioning service synchronizes from. Azure Active Directory is the source system for most preintegrated provisioning connectors, however there are some exceptions (example: Workday Inbound Synchronization).

+* **Target System** - The repository of users where the Azure AD provisioning service synchronizes. The repository is typically a SaaS application, such as Salesforce, ServiceNow, G Suite, and Dropbox for Business. In some cases the repository can be an on-premises system such as Active Directory, such as Workday Inbound Synchronization to Active Directory.

+To get provisioning report information for a given application, start by launching the [Azure portal](https://portal.azure.com) and **Azure Active Directory** &gt; **Enterprise Apps** &gt; **Provisioning logs** in the **Activity** section. You can also browse to the Enterprise Application for which provisioning is configured. For example, if you're provisioning users to LinkedIn Elevate, the navigation path to the application details is:

+From the all applications area, you access both the provisioning progress bar and provisioning logs.

+The [provisioning progress bar](application-provisioning-when-will-provisioning-finish-specific-user.md#view-the-provisioning-progress-bar) is visible in the **Provisioning** tab for a given application. It's located in the **Current Status** section and shows the status of the current initial or incremental cycle. This section also shows:

+* The total number of users and groups that are synchronized and currently in scope for provisioning between the source system and the target system.

+* The status of an [initial cycle](../app-provisioning/how-provisioning-works.md#provisioning-cycles-initial-and-incremental) and if the cycle has been completed.

+* The status of the provisioning process and if it's being placed in quarantine. The status also shows the reason for the quarantine. For example, a status might indicate a failure to communicate with the target system due to invalid admin credentials.

+## Next steps

+- [Managing user account provisioning for Enterprise Apps](configure-automatic-user-provisioning-portal.md)

+- [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+ Title: Azure AD Provisioning to applications via PowerShell

+description: This document describes how to configure Azure AD to provision users with external systems that offer Windows PowerShell based APIs.

+# Provisioning users into applications using PowerShell

+The following documentation provides configuration and tutorial information demonstrating how the generic PowerShell connector and the ECMA Connector Host can be used to integrate Azure AD with external systems that offer Windows PowerShell based APIs.

+For additional information see [Windows PowerShell Connector technical reference](/microsoft-identity-manager/reference/microsoft-identity-manager-2016-connector-powershell)

+## Prerequisites for provisioning via PowerShell

+The following sections detail the prerequisites for this tutorial.

+### Download the PowerShell setup files

+Download the PowerShell setup files from GitHub. The setup files consist of the configuration file, the input file, schema file and the scripts used. The files are located [here for download](https://github.com/microsoft/MIMPowerShellConnectors/tree/master/src/ECMA2HostCSV).

+### On-premises prerequisites

+The connector provides a bridge between the capabilities of the ECMA Connector Host and Windows PowerShell. Before you use the Connector, make sure you have the following on the server hosting the connector

+- A Windows Server 2016 or a later version.

+- At least 3 GB of RAM, to host a provisioning agent.

+- .NET Framework 4.7.2

+- Windows PowerShell 2.0, 3.0, or 4.0

+- Connectivity between hosting server, the connector, and the target system that the PowerShell scripts interact with.

+- The execution policy on the server must be configured to allow the connector to run Windows PowerShell scripts. Unless the scripts the connector runs are digitally signed, configure the execution policy by running this command:

+`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned`

+- Deploying this connector requires one or more PowerShell scripts. Some Microsoft products may provide scripts for use with this connector, and the support statement for those scripts would be provided by that product. If you are developing your own scripts for use with this connector, you'll need to have familiarity with the [Extensible Connectivity Management Agent API](https://msdn.microsoft.com/library/windows/desktop/hh859557.aspx) to develop and maintain those scripts. If you are integrating with third party systems using your own scripts in a production environment, we recommend you work with the third party vendor or a deployment partner for help, guidance and support for this integration.

+### Cloud requirements

+ - An Azure AD tenant with Azure AD Premium P1 or Premium P2 (or EMS E3 or E5). [!INCLUDE [active-directory-p1-license.md](../../../includes/active-directory-p1-license.md)]

+ - The Hybrid Identity Administrator role for configuring the provisioning agent and the Application Administrator or Cloud Application Administrator roles for configuring provisioning in the Azure portal.

+ - The Azure AD users, to be provisioned, must already be populated with any attributes required by the schema.

+## Download, install, and configure the Azure AD Connect Provisioning Agent Package

+If you have already downloaded the provisioning agent and configured it for another on-premises application, then continue reading in the next section.

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+

+ :::image type="content" source="../../../includes/media/active-directory-cloud-sync-how-to-install/new-ux-1.png" alt-text="Screenshot of new UX screen." lightbox="../../../includes/media/active-directory-cloud-sync-how-to-install/new-ux-1.png":::

+ 4. On the left, select **Agent**.

+ 5. Select **Download on-premises agent**, and select **Accept terms & download**.

+ >[!NOTE]

+ >Please use different provisioning agents for on-premises application provisioning and Azure AD Connect Cloud Sync / HR-driven provisioning. All three scenarios should not be managed on the same agent.

+ 6. Open the provisioning agent installer, agree to the terms of service, and select **next**.

+ 7. When the provisioning agent wizard opens, continue to the **Select Extension** tab and select **On-premises application provisioning** when prompted for the extension you want to enable.

+ 8. The provisioning agent uses the operating system's web browser to display a popup window for you to authenticate to Azure AD, and potentially also your organization's identity provider. If you are using Internet Explorer as the browser on Windows Server, then you may need to add Microsoft web sites to your browser's trusted site list to allow JavaScript to run correctly.

+ 9. Provide credentials for an Azure AD administrator when you're prompted to authorize. The user is required to have the Hybrid Identity Administrator or Global Administrator role.

+ 10. Select **Confirm** to confirm the setting. Once installation is successful, you can select **Exit**, and also close the Provisioning Agent Package installer.

+## Configure the On-premises ECMA app

+ 1. Sign in to the Azure portal as an administrator.

+ 2. Go to **Enterprise applications** and select **New application**.

+ 3. Search for the **On-premises ECMA app** application, give the app a name, and select **Create** to add it to your tenant.

+ 4. Navigate to the **Provisioning** page of your application.

+ 5. Select **Get started**.

+ 6. On the **Provisioning** page, change the mode to **Automatic**.

+ 7. On the **On-Premises Connectivity** section, select the agent that you just deployed and select **Assign Agent(s)**.

+ 8. Keep this browser window open, as you complete the next step of configuration using the configuration wizard.

+ ## Place the InputFile.txt and Schema.xml file in locations

+ Before you can create the PowerShell connector for this tutorial, you need to copy the InputFile.txt and Schema.xml file into the correct locations. These files are the ones you needed to download in section [Download the PowerShell setup files](#download-the-powershell-setup-files).

+ |File|location|

+ |--|--|

+ |InputFile.txt|`C:\Program Files\Microsoft ECMA2Host\Service\ECMA\MAData`|

+ |Schema.xml|`C:\Program Files\Microsoft ECMA2Host\Service\ECMA`|

+ ## Configure the Azure AD ECMA Connector Host certificate

+ 1. On the Windows Server where the provisioning agent is installed, right click the **Microsoft ECMA2Host Configuration Wizard** from the start menu, and run as administrator. Running as a Windows administrator is necessary for the wizard to create the necessary Windows event logs.

+ 2. After the ECMA Connector Host Configuration starts, if it's the first time you have run the wizard, it will ask you to create a certificate. Leave the default port **8585** and select **Generate certificate** to generate a certificate. The autogenerated certificate will be self-signed as part of the trusted root. The certificate SAN matches the host name.

+ 3. Select **Save**.

+## Create the PowerShell Connector

+

+### General Screen

+ 1. Launch the Microsoft ECMA2Host Configuration Wizard from the start menu.

+ 2. At the top, select **Import** and select the configuration.xml file from step 1.

+ 3. The new connector should be created and appear in red. Click **Edit**.

+ 4. Generate a secret token used for authenticating Azure AD to the connector. It should be 12 characters minimum and unique for each application. If you do not already have a secret generator, you can use a PowerShell command such as the following to generate an example random string.

+ ```powershell

+ -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})

+ ```

+ 5. On the **Properties** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+

+ |Property|Value|

+ |--|--|

+ |Name|The name you chose for the connector, which should be unique across all connectors in your environment. For example, `PowerShell`.|

+ |Autosync timer (minutes)|120|

+ |Secret Token|Enter your secret token here. It should be 12 characters minimum.|

+ |Extension DLL|For the PowerShell connector, select **Microsoft.IAM.Connector.PowerShell.dll**.|

+### Connectivity

+The connectivity tab allows you to supply configuration parameters for connecting to a remote system. Configure the connectivity tab with the information provided in the table.

+ - On the **Connectivity** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+ :::image type="content" source="media/on-premises-powershell-connector/powershell-2.png" alt-text="Screenshot of the connectivity screen." lightbox="media/on-premises-powershell-connector/powershell-2.png":::

+|Parameter|Value|Purpose|

+|-|--|--|

+| Server | \<Blank\> | Server name that the connector should connect to. |

+| Domain | \<Blank\> |Domain of the credential to store for use when the connector is run.|

+|User| \<Blank\> | Username of the credential to store for use when the connector is run. |

+| Password | \<Blank\> | Password of the credential to store for use when the connector is run. |

+| Impersonate Connector Account |Unchecked| When true, the synchronization service runs the Windows PowerShell scripts in the context of the credentials supplied. When possible, it is recommended that the **$Credentials** parameter is passed to each script is used instead of impersonation.|

+| Load User Profile When Impersonating |Unchecked|Instructs Windows to load the user profile of the connectorΓÇÖs credentials during impersonation. If the impersonated user has a roaming profile, the connector does not load the roaming profile.|

+| Logon Type When Impersonating |None|Logon type during impersonation. For more information, see the [dwLogonType][dw] documentation. |

+|Signed Scripts Only |Unchecked| If true, the Windows PowerShell connector validates that each script has a valid digital signature. If false, ensure that the Synchronization Service serverΓÇÖs Windows PowerShell execution policy is RemoteSigned or Unrestricted.|

+|Common Module Script Name (with extension)|xADSyncPSConnectorModule.psm1|The connector allows you to store a shared Windows PowerShell module in the configuration. When the connector runs a script, the Windows PowerShell module is extracted to the file system so that it can be imported by each script.|

+|Common Module Script|[AD Sync PowerShell Connector Module code](https://github.com/microsoft/MIMPowerShellConnectors/blob/master/src/ECMA2HostCSV/Scripts/CommonModule.psm1) as value. This module will be automatically created by the ECMA2Host when the connector is running.||

+|Validation Script|\<Blank\>|The Validation Script is an optional Windows PowerShell script that can be used to ensure that connector configuration parameters supplied by the administrator are valid.|

+|Schema Script|[GetSchema code](https://github.com/microsoft/MIMPowerShellConnectors/blob/master/src/ECMA2HostCSV/Scripts/Schema%20Script.ps1) as value.||

+|Additional Config Parameter Names|FileName,Delimiter,Encoding|In addition to the standard configuration settings, you can define additional custom configuration settings that are specific to the instance of the Connector. These parameters can be specified at the connector, partition, or run step levels and accessed from the relevant Windows PowerShell script. |

+|Additional Encrypted Config Parameter Names|\<Blank\> ||

+### Capabilities

+The capabilities tab defines the behavior and functionality of the connector. The selections made on this tab cannot be modified when the connector has been created. Configure the capabilities tab with the information provided in the table.

+- On the **Capabilities** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+ :::image type="content" source="media/on-premises-powershell-connector/powershell-4.png" alt-text="Screenshot of the capabilities screen." lightbox="media/on-premises-powershell-connector/powershell-4.png":::

+|Parameter|Value|Purpose|

+|-|--|--|

+|Distinguished Name Style|None|Indicates if the connector supports distinguished names and if so, what style. |

+|Export Type|ObjectReplace|Determines the type of objects that are presented to the Export script.|

+|Data Normalization|None|Instructs the Synchronization Service to normalize anchor attributes before they are provided to scripts. |

+|Object Confirmation|Normal|This is ignored.|

+|Use DN as Anchor|Unchecked|If the Distinguished Name Style is set to LDAP, the anchor attribute for the connector space is also the distinguished name. |

+|Concurrent Operations of Several Connectors|Checked|When checked, multiple Windows PowerShell connectors can run simultaneously. |

+|Partitions|Unchecked|When checked, the connector supports multiple partitions and partition discovery. |

+|Hierarchy|Unchecked|When checked, the connector supports an LDAP style hierarchical structure. |

+|Enable Import|Checked|When checked, the connector imports data via import scripts. |

+|Enable Delta Import|Unchecked|When checked, the connector can request deltas from the import scripts. |

+|Enable Export|Checked|When checked, the connector exports data via export scripts. |

+|Enable Full Export|Checked|Not supported. This will be ignored.|

+|No Reference Values In First Export Pass|Unchecked|When checked, reference attributes are exported in a second export pass. |

+|Enable Object Rename|Unchecked|When checked, distinguished names can be modified. |

+|Delete-Add As Replace|Checked|Not supported. This will be ignored.|

+|Enable Export Password in First Pass|Checked|Not supported. This will be ignored.|

+### Global Parameters

+The Global Parameters tab enables you to configure the Windows PowerShell scripts that are run by the connector. You can also configure global values for custom configuration settings defined on the Connectivity tab. Configure the global parameters tab with the information provided in the table.

+ - On the **Global Parameters** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+|Parameter|Value|

+|--|--|

+|Partition Script|\<Blank>|

+|Hierarchy Script|\<Blank>|

+|Begin Import Script|\<Blank>|

+|Import Script|Paste ImportData code as value|

+|End Import Script|\<Blank>|

+|Begin Export Script|Paste Begin export code as value|

+|Export Script|Paste ExportData code as value|

+|End Export Script|\<Blank>|

+|Begin Password Script|\<Blank>|

+|Password Extension Script|\<Blank>|

+|End Password Script|\<Blank>|

+|FileName_Global|InputFile.txt|

+|Delimiter_Global|;|

+|Encoding_Global|\<Blank> (defaults to UTF8)|

+### Partitions, Run Profiles, Export, FullImport

+Keep the defaults and click **next**.

+### Object types

+Configure the object types tab with the information provided in the table.

+- On the **Object types** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+|Parameter|Value|

+|--|--|

+|Target Object|Person|

+|Anchor|AzureObjectID|

+|Query Attribute|AzureObjectID|

+|DN|AzureObjectID|

+### Select Attributes

+Ensure that the following attributes are selected:

+- On the **Select Attributes** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+- AzureObjectID

+- IsActive

+- DisplayName

+- EmployeeId

+- Title

+- UserName

+- Email

+### Deprovisioning

+On the Deprovisioning page, you can specify if you wish to have Azure AD remove users from the directory when they go out of scope of the application. If so, under Disable flow, select Delete, and under Delete flow, select Delete. If Set attribute value is chosen, the attributes selected on the previous page won't be available to select on the Deprovisioning page.

+- On the **Deprovisioning** page, all of the information should be populated. The table is provided as reference. Click **Next**.

+## Ensure ECMA2Host service is running and can read from file via PowerShell

+Follow these steps to confirm that the connector host has started and has identified any existing users from the target system.

+ 1. On the server running the Azure AD ECMA Connector Host, select **Start**.

+ 2. Select **run** if needed, then enter **services.msc** in the box.

+ 3. In the **Services** list, ensure that **Microsoft ECMA2Host** is present and running. If it is not running, select **Start**.

+ 4. On the server running the Azure AD ECMA Connector Host, launch PowerShell.

+ 5. Change to the folder where the ECMA host was installed, such as `C:\Program Files\Microsoft ECMA2Host`.

+ 6. Change to the subdirectory `Troubleshooting`.

+ 7. Run the script `TestECMA2HostConnection.ps1` in the directory as shown, and provide as arguments the connector name and the `ObjectTypePath` value `cache`. If your connector host is not listening on TCP port 8585, then you may also need to provide the `-Port` argument as well. When prompted, type the secret token configured for that connector.

+ ```

+ PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> $cout = .\TestECMA2HostConnection.ps1 -ConnectorName PowerShell -ObjectTypePath cache; $cout.length -gt 9

+ Supply values for the following parameters:

+ SecretToken: ************

+ ```

+ 8. If the script displays an error or warning message, then check that the service is running, and the connector name and secret token match those values you configured in the configuration wizard.

+ 9. If the script displays the output `False`, then the connector has not seen any entries in the source target system for existing users. If this is a new target system installation, then this behavior is to be expected, and you can continue at the next section.

+ 10. However, if the target system already contains one or more users but the script displayed `False`, then this status indicates the connector could not read from the target system. If you attempt to provision, then Azure AD may not correctly match users in that source directory with users in Azure AD. Wait several minutes for the connector host to finish reading objects from the existing target system, and then rerun the script. If the output continues to be `False`, then check the configuration of your connector and the permissions in the target system are allowing the connector to read existing users.

+## Test the connection from Azure AD to the connector host

+ 1. Return to the web browser window where you were configuring the application provisioning in the portal.

+ >[!NOTE]

+ >If the window had timed out, then you need to re-select the agent.

+ 1. Sign in to the Azure portal.

+ 2. Go to **Enterprise applications** and the **On-premises ECMA app** application.

+ 3. Click on **Provisioning**.

+ 4. If **Get started** appears, then change the mode to **Automatic**, on the **On-Premises Connectivity** section, select the agent that you just deployed and select **Assign Agent(s)**, and wait 10 minutes. Otherwise go to **Edit Provisioning**.

+ 2. Under the **Admin credentials** section, enter the following URL. Replace the `connectorName` portion with the name of the connector on the ECMA host, such as `PowerShell`. If you provided a certificate from your certificate authority for the ECMA host, then replace `localhost` with the host name of the server where the ECMA host is installed.

+ |Property|Value|

+ |--|--|

+ |Tenant URL|https://localhost:8585/ecma2host_connectorName/scim|

+ 3. Enter the **Secret Token** value that you defined when you created the connector.

+ >[!NOTE]

+ >If you just assigned the agent to the application, please wait 10 minutes for the registration to complete. The connectivity test won't work until the registration completes. Forcing the agent registration to complete by restarting the provisioning agent on your server can speed up the registration process. Go to your server, search for **services** in the Windows search bar, identify the **Azure AD Connect Provisioning Agent** service, right-click the service, and restart.

+ 4. Select **Test Connection**, and wait one minute.

+ 5. After the connection test is successful and indicates that the supplied credentials are authorized to enable provisioning, select **Save**.

+## Configure the application connection in the Azure portal

+Return to the web browser window where you were configuring the application provisioning.

+>[!NOTE]

+>If the window had timed out, then you need to re-select the agent.

+ 1. Sign in to the Azure portal.

+ 2. Go to **Enterprise applications** and the **On-premises ECMA app** application.

+ 3. Select on **Provisioning**.

+ 4. If **Get started** appears, then change the mode to **Automatic**, on the **On-Premises Connectivity** section, select the agent that you deployed and select **Assign Agent(s)**. Otherwise go to **Edit Provisioning**.

+ 5. Under the **Admin credentials** section, enter the following URL. Replace the `{connectorName}` portion with the name of the connector on the ECMA connector host, such as **CSV**. The connector name is case sensitive and should be the same case as was configured in the wizard. You can also replace `localhost` with your machine hostname.

+

+ |Property|Value|

+ |--|--|

+ |Tenant URL| `https://localhost:8585/ecma2host_CSV/scim`|

+ 6. Enter the **Secret Token** value that you defined when you created the connector.

+ >[!NOTE]

+ >If you just assigned the agent to the application, please wait 10 minutes for the registration to complete. The connectivity test won't work until the registration completes. Forcing the agent registration to complete by restarting the provisioning agent on your server can speed up the registration process. Go to your server, search for **services** in the Windows search bar, identify the **Azure AD Connect Provisioning Agent Service**, right-click the service, and restart.

+ 7. Select **Test Connection**, and wait one minute.

+ 8. After the connection test is successful and indicates that the supplied credentials are authorized to enable provisioning, select **Save**.

+## Configure attribute mappings

+Now you need to map attributes between the representation of the user in Azure AD and the representation of a user in the on-premises InputFile.txt.

+You'll use the Azure portal to configure the mapping between the Azure AD user's attributes and the attributes that you previously selected in the ECMA Host configuration wizard.

+ 1. In the Azure AD portal, under **Enterprise applications**, select the **On-premises ECMA app** application, and then the **Provisioning** page.

+ 2. Select **Edit provisioning**, and wait 10 seconds.

+ 3. Expand **Mappings** and select **Provision Azure Active Directory Users**. If this is the first time you've configured the attribute mappings for this application, there will be only one mapping present, for a placeholder.

+ 4. To confirm that the schema is available in Azure AD, select the **Show advanced options** checkbox and select **Edit attribute list for ScimOnPremises**. Ensure that all the attributes selected in the configuration wizard are listed. If not, then wait several minutes for the schema to refresh, and then reload the page. Once you see the attributes listed, then cancel from this page to return to the mappings list.

+ 5. Now, on the click on the **userPrincipalName** PLACEHOLDER mapping. This mapping is added by default when you first configure on-premises provisioning.

+ Change the value to match the following:

+

+ |Mapping type|Source attribute|Target attribute|

+ |--|--|--|

+ |Direct|userPrincipalName|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName|

+ 4. Now select **Add New Mapping**, and repeat the next step for each mapping.

+ 5. Specify the source and target attributes for each of the mappings in the following table.

+

+ |Mapping type|Source attribute|Target attribute|

+ |--|--|--|

+ |Direct|objectId|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:AzureObjectID|

+ |Direct|userPrincipalName|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName|

+ |Direct|displayName|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:DisplayName|

+ |Direct|employeeId|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:EmployeeId|

+ |Direct|jobTitle|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Title|

+ |Direct|mail|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Email|

+ |Expression|Switch([IsSoftDeleted],, "False", "True", "True", "False")|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:IsActive|

+

+ 6. Once all of the mappings have been added, select **Save**.

+## Assign users to an application

+Now that you have the Azure AD ECMA Connector Host talking with Azure AD, and the attribute mapping configured, you can move on to configuring who's in scope for provisioning.

+>[!IMPORTANT]

+>If you were signed in using a Hybrid Identity Administrator role, you need to sign-out and sign-in with an account that has the Application Administrator, Cloud Application Administrator or Global Administrator role, for this section. The Hybrid Identity Administrator role does not have permissions to assign users to applications.

+If there are existing users in the InputFile.txt, then you should create application role assignments for those existing users. To learn more about how to create application role assignments in bulk, see [governing an application's existing users in Azure AD](../governance/identity-governance-applications-existing-users.md).

+Otherwise, if there are no current users of the application, then select a test user from Azure AD who will be provisioned to the application.

+ 1. Ensure that the user selected has all the properties, mapped to the required attributes of the schema.

+ 2. In the Azure portal, select **Enterprise applications**.

+ 3. Select the **On-premises ECMA app** application.

+ 4. On the left, under **Manage**, select **Users and groups**.

+ 5. Select **Add user/group**.

+ 6. Under **Users**, select **None Selected**.

+ 7. Select users from the right and select the **Select** button.

+ 8. Now select **Assign**.

+## Test provisioning

+Now that your attributes are mapped and users are assigned, you can test on-demand provisioning with one of your users.

+

+ 1. In the Azure portal, select **Enterprise applications**.

+ 2. Select the **On-premises ECMA app** application.

+ 3. On the left, select **Provisioning**.

+ 4. Select **Provision on demand**.

+ 5. Search for one of your test users, and select **Provision**.

+ 6. After several seconds, then the message **Successfully created user in target system** appears, with a list of the user attributes.

+## Start provisioning users

+1. After on-demand provisioning is successful, change back to the provisioning configuration page. Ensure that the scope is set to only assigned users and groups, turn provisioning **On**, and select **Save**.

+2. Wait several minutes for provisioning to start. It might take up to 40 minutes. After the provisioning job has been completed, as described in the next section, if you're done testing, you can change the provisioning status to **Off**, and select **Save**. This action stops the provisioning service from running in the future.

+## Next steps

+- [App provisioning](user-provisioning.md)

+- [ECMA Connector Host generic SQL connector](tutorial-ecma-sql-connector.md)

+- [ECMA Connector Host LDAP connector](on-premises-ldap-connector-configure.md)

+## Support for certificates on hardware security key

+This feature supports using YubiKey with USB and NFC.

+## Support for certificates on hardware security key

+>Azure AD will check the CRL of the issuing CA and other CAs in the PKI trust chain up to the root CA. We have a limit of up to 10 CAs from the leaf client certificate for CRL validation in the PKI chain. The limitation is to make sure a bad actor will not bring down the service by uploading a PKI chain with a huge number of CAs with a bigger CRL size.

+ For more information, see [Assign user and device profiles in Microsoft Intune](/mem/intune/configuration/device-profile-assign).

+[AAD-App-Branding]:howto-add-branding-in-apps.md

+>This information last updated on May 4th, 2023.<br/>You can also download a CSV version of this table [here](https://download.microsoft.com/download/e/3/e/e3e9faf2-f28b-490a-9ada-c6089a1fc5b0/Product%20names%20and%20service%20plan%20identifiers%20for%20licensing.csv).

+| Compliance Manager Premium Assessment Add-On | CMPA_addon | 8a5fbbed-8b8c-41e5-907e-c50c471340fd | COMPLIANCE_MANAGER_PREMIUM_ASSESSMENT_ADDON (3a117d30-cfac-4f00-84ac-54f8b6a18d78) | Compliance Manager Premium Assessment Add-On (3a117d30-cfac-4f00-84ac-54f8b6a18d78) |

+| Defender Threat Intelligence | Defender_Threat_Intelligence | a9c51c15-ffad-4c66-88c0-8771455c832d | THREAT_INTELLIGENCE_APP (fbdb91e6-7bfd-4a1f-8f7a-d27f4ef39702) | Defender Threat Intelligence (fbdb91e6-7bfd-4a1f-8f7a-d27f4ef39702) |

+| Dynamics 365 Customer Service Enterprise Admin | Dynamics_365_Customer_Service_Enterprise_admin_trial | 94a6fbd4-6a2f-4990-b356-dc7dd8bed08a | CUSTOMER_VOICE_DYN365_VIRAL_TRIAL (dbe07046-af68-4861-a20d-1c8cbda9194f)<br/>DYN365_CS_MESSAGING_TPS (47c2b191-a5fb-4129-b690-00c474d2f623)<br/>D365_CSI_EMBED_CSEnterprise (5b1e5982-0e88-47bb-a95e-ae6085eda612)<br/>DYN365_ENTERPRISE_CUSTOMER_SERVICE (99340b49-fb81-4b1e-976b-8f2ae8e9394f)<br/>DYN365_CS_VOICE (f6ec6dfa-2402-468d-a455-89be11116d43)<br/>POWER_VIRTUAL_AGENTS_D365_CS_VOICE (a3dce1be-e9ca-453a-9483-e69a5b46ce98)<br/>POWER_VIRTUAL_AGENTS_D365_CS_MESSAGING (2d2f174c-c3cc-4abe-9ce8-4dd86f469ab1)<br/>EXCHANGE_S_FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>POWERAPPS_DYN_APPS (874fc546-6efe-4d22-90b8-5c4e7aa59f4b)<br/>FLOW_DYN_APPS (7e6d7d78-73de-46ba-83b1-6d25117334ba) | Customer Voice for Dynamics 365 vTrial (dbe07046-af68-4861-a20d-1c8cbda9194f)<br/>Dynamics 365 Customer Service Digital Messaging add-on (47c2b191-a5fb-4129-b690-00c474d2f623)<br/>Dynamics 365 Customer Service Insights for CS Enterprise (5b1e5982-0e88-47bb-a95e-ae6085eda612)<br/>Dynamics 365 for Customer Service (99340b49-fb81-4b1e-976b-8f2ae8e9394f)<br/>Dynamics 365 for Customer Service Voice Add-in (f6ec6dfa-2402-468d-a455-89be11116d43)<br/>Power Virtual Agents for Customer Service Voice (a3dce1be-e9ca-453a-9483-e69a5b46ce98)<br/>Power Virtual Agents for Digital Messaging (2d2f174c-c3cc-4abe-9ce8-4dd86f469ab1)<br/>Exchange Foundation (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>Power Apps for Dynamics 365 (874fc546-6efe-4d22-90b8-5c4e7aa59f4b)<br/>Power Automate for Dynamics 365 (7e6d7d78-73de-46ba-83b1-6d25117334ba) |

+| Dynamics 365 Field Service, Enterprise Edition - Resource Scheduling Optimization | CRM_AUTO_ROUTING_ADDON | 977464c4-bfaf-4b67-b761-a9bb735a2196 | CRM_AUTO_ROUTING_ENGINE_ADDON (24435e4b-87d0-4d7d-8beb-63a9b1573022)<br/>CRM_AUTO_ROUTING_ADDON (2ba394e0-6f18-4b77-b45f-a5663bbab540)<br/>EXCHANGE_S_FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318) | Field Service ΓÇô Automated Routing Engine Add-On (24435e4b-87d0-4d7d-8beb-63a9b1573022)<br/>Field Service ΓÇô Automated Routing Engine Add-On (2ba394e0-6f18-4b77-b45f-a5663bbab540)<br/>Exchange Foundation (113feb6c-3fe4-4440-bddc-54d774bf0318) |

+| Microsoft Teams Rooms Standard | MEETING_ROOM | 6070a4c8-34c6-4937-8dfb-39bbc6397a60 | AAD_PREMIUM (41781fb2-bc02-4b7c-bd55-b576c07bb09d)<br/>MCOMEETADV (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>MCOEV (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Teams_Room_Standard (92c6b761-01de-457a-9dd9-793a975238f7)<br/>WHITEBOARD_PLAN3 (4a51bca5-1eff-43f5-878c-177680f191af)<br/>INTUNE_A (c1ec4a95-1f05-45b3-a911-aa3fa01094f5) | Azure Active Directory Premium Plan 1 (41781fb2-bc02-4b7c-bd55-b576c07bb09d)<br/>Microsoft 365 Audio Conferencing (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>Microsoft 365 Phone System (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Teams Room Standard (92c6b761-01de-457a-9dd9-793a975238f7)<br/>Whiteboard (Plan 3) (4a51bca5-1eff-43f5-878c-177680f191af)<br/>Microsoft Intune Plan 1 (c1ec4a95-1f05-45b3-a911-aa3fa01094f5) |

+ Title: 'Configure accidental deletion prevention with Active Directory'

+description: This article describes how you can configure accidental deletion prevention for the synchronization tools with Active Directory.

+documentationcenter: ''

+editor: ''

+ na

+# How to prevent accidental deletions

+When installing either cloud sync or Azure AD Connect, this feature is enabled by default and configured to not allow an export with more than 500 deletes. This feature is designed to protect you from accidental configuration changes and changes to your on-premises directory that would affect many users and other objects.

+You can change the default behavior and tailor it to your organizations needs.

+## Configure accidental delete prevention with cloud sync

+To use the new feature, follow the steps below.

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+ 4. Under **Configuration**, select your configuration.

+ 5. Select **View default properties**.

+ 6. Click the pencil next to **Basics**

+ 5. On the right, fill in the following information.

+ - **Notification email** - email used for notifications

+ - **Prevent accidental deletions** - check this box to enable the feature

+ - **Accidental deletion threshold** - enter the number of objects to stop synchronization and send a notification

+For more information, see [Accidental delete prevention with cloud sync](cloud-sync/how-to-accidental-deletes.md)

+## Configure accidental delete prevention with Azure AD Connect

+The default value of 500 objects can be changed with PowerShell using `Enable-ADSyncExportDeletionThreshold`, which is part of the [AD Sync module](connect/reference-connect-adsync.md) installed with Azure Active Directory Connect. You should configure this value to fit the size of your organization. Since the sync scheduler runs every 30 minutes, the value is the number of deletes seen within 30 minutes.

+For more information, see [Accidental delete prevention with Azure AD Connect](connect/how-to-connect-sync-feature-prevent-accidental-deletes.md).

+ Title: 'Accounts for integrating with Active Directory'

+description: This article describes the required accounts for each of the synchronization tools.

+documentationcenter: ''

+editor: ''

+ na

+# Accounts for integrating with Active Directory

+The following article describes the accounts that are required for each of the two synchronization tools. Use these sections as a reference when configuring and setting up your environment.

+## Accounts for installing and running cloud sync

+|Requirement|Description and more requirements|

+|--|--|

+|Domain/Enterprise administrator|Required to install the agent on the server and create the gMSA service account.|

+|Hybrid Identity administrator|Required to configure cloud sync. This account cannot be a guest account.|

+|gMSA service account|Required to run the agent.|

+For more information, on cloud sync accounts, and how to set up a custom gMSA account, see [Cloud sync prerequisites](cloud-sync/how-to-prerequisites.md).

+## Accounts for installing and running Azure AD Connect

+Azure AD Connect uses three accounts to *synchronize information* from on-premises Windows Server Active Directory (Windows Server AD) to Azure Active Directory (Azure AD):

+|Requirement|Description and additional requirements|

+|--|--|

+|AD DS Connector account|Used to read and write information to Windows Server AD by using Active Directory Domain Services (AD DS).|

+|ADSync service account|Used to run the sync service and access the SQL Server database.|

+|Azure AD Connector account|Used to write information to Azure AD.|

+|Local Administrator account|The administrator who is installing Azure AD Connect and who has local Administrator permissions on the computer.|

+|AD DS Enterprise Administrator account|Optionally used to create the required AD DS Connector account.|

+|Azure AD Global Administrator account|Used to create the Azure AD Connector account and to configure Azure AD. You can view Global Administrator and Hybrid Identity Administrator accounts in the Azure portal. See [List Azure AD role assignments](../roles/view-assignments.md).|

+|SQL SA account (optional)|Used to create the ADSync database when you use the full version of SQL Server. The instance of SQL Server can be local or remote to the Azure AD Connect installation. This account can be the same account as the Enterprise Administrator account.|

+For more information, on Azure AD Connet accounts, and how to configure them, see [Accounts and permissions](connect/reference-connect-accounts-permissions.md).

+ Title: 'Understand the Azure AD schema and custom expressions'

+description: This article describes the Azure AD schema, the attributes that the provisioning agent flows, and custom expressions.

+documentationcenter: ''

+editor: ''

+ na

+# Understand the Azure AD schema

+An object in Azure Active Directory (Azure AD), like any directory, is a programmatic high-level data construct that represents such things as users, groups, and contacts. When you create a new user or contact in Azure AD, you're creating a new instance of that object. These instances can be differentiated based on their properties.

+Properties in Azure AD are the elements responsible for storing information about an instance of an object in Azure AD.

+The Azure AD schema defines the rules for which properties might be used in an entry, the kinds of values that those properties might have, and how users might interact with those values.

+Azure AD has two types of properties:

+- **Built-in properties**: Properties that are predefined by the Azure AD schema. These properties provide different uses and might or might not be accessible.

+- **Directory extensions**: Properties that are provided so that you can customize Azure AD for your own use. For example, if you've extended your on-premises Active Directory with a certain attribute and want to flow that attribute, you can use one of the custom properties that's provided.

+## Attributes and expressions

+When an object such as a user is provisioned to Azure AD, a new instance of the user object is created. This creation includes the properties of that object, which are also known as attributes. Initially, the newly created object has its attributes set to values that are determined by the synchronization rules. These attributes are then kept up to date via the cloud provisioning agent.

+

+For example, a user might be part of a Marketing department. Their Azure AD department attribute is initially created when they're provisioned, and the value is set to Marketing. Six months later if they change to Sales, their on-premises Active Directory department attribute is changed to Sales. This change synchronizes to Azure AD and is reflected in their Azure AD user object.

+Attribute synchronization might be direct, where the value in Azure AD is directly set to the value of the on-premises attribute. Or, a programmatic expression might handle the synchronization. A programmatic expression is needed in cases where some logic or a determination must be made to populate the value.

+For example, if you had the mail attribute "john.smith@contoso.com" and needed to strip out the "@contoso.com" portion and flow only the value "john.smith," you'd use something like this:

+`Replace([mail], "@contoso.com", , ,"", ,)`

+**Sample input/output:** <br>

+* **INPUT** (mail): "john.smith@contoso.com"

+* **OUTPUT**: "john.smith"

+For more information on how to write custom expressions and the syntax, see [Writing expressions for attribute mappings in Azure Active Directory](../../app-provisioning/functions-for-customizing-application-data.md).

+The following table lists common attributes and how they're synchronized to Azure AD.

+|On-premises Active Directory|Mapping type|Azure AD|

+|--|--|--|

+|cn|Direct|commonName

+|countryCode|Direct|countryCode|

+|displayName|Direct|displayName|

+|givenName|Expression|givenName|

+|objectGUID|Direct|sourceAnchorBinary|

+|userprincipalName|Direct|userPrincipalName|

+|ProxyAdress|Direct|ProxyAddress|

+## View the schema

+> [!WARNING]

+> The cloud sync configuration creates a service principal. The service principal is visible in the Azure portal. You should not modify the attribute mappings using the service principal experience in the Azure portal. This is not supported.

+To view the schema and verify it, follow these steps.

+1. Go to [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer).

+1. Sign in with your global administrator account.

+1. On the left, select **modify permissions** and ensure that **Directory.ReadWrite.All** is *Consented*.

+1. Run the query `https://graph.microsoft.com/beta/serviceprincipals/?$filter=startswith(DisplayName, ΓÇÿ{sync config name}ΓÇÖ)`. This query returns a filtered list of service principals. This can also be acquired via the App Registration node under Azure Active Directory.

+1. Locate `"appDisplayName": "Active Directory to Azure Active Directory Provisioning"` and note the value for `"id"`.

+ ```

+ "value": [

+ {

+ "id": "00d41b14-7958-45ad-9d75-d52fa29e02a1",

+ "deletedDateTime": null,

+ "accountEnabled": true,

+ "appDisplayName": "Active Directory to Azure Active Directory Provisioning",

+ "appId": "1a4721b3-e57f-4451-ae87-ef078703ec94",

+ "applicationTemplateId": null,

+ "appOwnerOrganizationId": "47df5bb7-e6bc-4256-afb0-dd8c8e3c1ce8",

+ "appRoleAssignmentRequired": false,

+ "displayName": "Active Directory to Azure Active Directory Provisioning",

+ "errorUrl": null,

+ "homepage": "https://account.activedirectory.windowsazure.com:444/applications/default.aspx?metadata=AD2AADProvisioning|ISV9.1|primary|z",

+ "loginUrl": null,

+ "logoutUrl": null,

+ "notificationEmailAddresses": [],

+ "preferredSingleSignOnMode": null,

+ "preferredTokenSigningKeyEndDateTime": null,

+ "preferredTokenSigningKeyThumbprint": null,

+ "publisherName": "Active Directory Application Registry",

+ "replyUrls": [],

+ "samlMetadataUrl": null,

+ "samlSingleSignOnSettings": null,

+ "servicePrincipalNames": [

+ "http://adapplicationregistry.onmicrosoft.com/adprovisioningtoaad/primary",

+ "1a4721b3-e57f-4451-ae87-ef078703ec94"

+ ],

+ "signInAudience": "AzureADMultipleOrgs",

+ "tags": [

+ "WindowsAzureActiveDirectoryIntegratedApp"

+ ],

+ "addIns": [],

+ "api": {

+ "resourceSpecificApplicationPermissions": []

+ },

+ "appRoles": [

+ {

+ "allowedMemberTypes": [

+ "User"

+ ],

+ "description": "msiam_access",

+ "displayName": "msiam_access",

+ "id": "a0326856-1f51-4311-8ae7-a034d168eedf",

+ "isEnabled": true,

+ "origin": "Application",

+ "value": null

+ }

+ ],

+ "info": {

+ "termsOfServiceUrl": null,

+ "supportUrl": null,

+ "privacyStatementUrl": null,

+ "marketingUrl": null,

+ "logoUrl": null

+ },

+ "keyCredentials": [],

+ "publishedPermissionScopes": [

+ {

+ "adminConsentDescription": "Allow the application to access Active Directory to Azure Active Directory Provisioning on behalf of the signed-in user.",

+ "adminConsentDisplayName": "Access Active Directory to Azure Active Directory Provisioning",

+ "id": "d40ed463-646c-4efe-bb3e-3fa7d0006688",

+ "isEnabled": true,

+ "type": "User",

+ "userConsentDescription": "Allow the application to access Active Directory to Azure Active Directory Provisioning on your behalf.",

+ "userConsentDisplayName": "Access Active Directory to Azure Active Directory Provisioning",

+ "value": "user_impersonation"

+ }

+ ],

+ "passwordCredentials": []

+ },

+ ```

+1. Replace `{Service Principal id}` with your value, and run the query `https://graph.microsoft.com/beta/serviceprincipals/{Service Principal id}/synchronization/jobs/`.

+1. Locate `"id": "AD2AADProvisioning.fd1c9b9e8077402c8bc03a7186c8f976"` and note the value for `"id"`.

+ ```

+ {

+ "id": "AD2AADProvisioning.fd1c9b9e8077402c8bc03a7186c8f976",

+ "templateId": "AD2AADProvisioning",

+ "schedule": {

+ "expiration": null,

+ "interval": "PT2M",

+ "state": "Active"

+ },

+ "status": {

+ "countSuccessiveCompleteFailures": 0,

+ "escrowsPruned": false,

+ "code": "Active",

+ "lastSuccessfulExecutionWithExports": null,

+ "quarantine": null,

+ "steadyStateFirstAchievedTime": "2019-11-08T15:48:05.7360238Z",

+ "steadyStateLastAchievedTime": "2019-11-20T16:17:24.7957721Z",

+ "troubleshootingUrl": "",

+ "lastExecution": {

+ "activityIdentifier": "2dea06a7-2960-420d-931e-f6c807ebda24",

+ "countEntitled": 0,

+ "countEntitledForProvisioning": 0,

+ "countEscrowed": 15,

+ "countEscrowedRaw": 15,

+ "countExported": 0,

+ "countExports": 0,

+ "countImported": 0,

+ "countImportedDeltas": 0,

+ "countImportedReferenceDeltas": 0,

+ "state": "Succeeded",

+ "error": null,

+ "timeBegan": "2019-11-20T16:15:21.116098Z",

+ "timeEnded": "2019-11-20T16:17:24.7488681Z"

+ },

+ "lastSuccessfulExecution": {

+ "activityIdentifier": null,

+ "countEntitled": 0,

+ "countEntitledForProvisioning": 0,

+ "countEscrowed": 0,

+ "countEscrowedRaw": 0,

+ "countExported": 5,

+ "countExports": 0,

+ "countImported": 0,

+ "countImportedDeltas": 0,

+ "countImportedReferenceDeltas": 0,

+ "state": "Succeeded",

+ "error": null,

+ "timeBegan": "0001-01-01T00:00:00Z",

+ "timeEnded": "2019-11-20T14:09:46.8855027Z"

+ },

+ "progress": [],

+ "synchronizedEntryCountByType": [

+ {

+ "key": "group to Group",

+ "value": 33

+ },

+ {

+ "key": "user to User",

+ "value": 3

+ }

+ ]

+ },

+ "synchronizationJobSettings": [

+ {

+ "name": "Domain",

+ "value": "{\"DomainFQDN\":\"contoso.com\",\"DomainNetBios\":\"CONTOSO\",\"ForestFQDN\":\"contoso.com\",\"ForestNetBios\":\"CONTOSO\"}"

+ },

+ {

+ "name": "DomainFQDN",

+ "value": "contoso.com"

+ },

+ {

+ "name": "DomainNetBios",

+ "value": "CONTOSO"

+ },

+ {

+ "name": "ForestFQDN",

+ "value": "contoso.com"

+ },

+ {

+ "name": "ForestNetBios",

+ "value": "CONTOSO"

+ },

+ {

+ "name": "QuarantineTooManyDeletesThreshold",

+ "value": "500"

+ }

+ ]

+ }

+ ```

+1. Now run the query `https://graph.microsoft.com/beta/serviceprincipals/{Service Principal Id}/synchronization/jobs/{AD2AAD Provisioning id}/schema`.

+

+ Replace `{Service Principal Id}` and `{AD2ADD Provisioning Id}` with your values.

+1. This query returns the schema.

+ 

+

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Azure AD Connect cloud sync deep dive - how it works'

+description: This topic provides deep dive information on how cloud sync works.

+# Cloud sync deep dive - how it works

+## Overview of components

+

+Cloud sync is built on top of the Azure AD services and has 2 key components:

+- **Provisioning agent**: The Azure AD Connect cloud provisioning agent is the same agent as Workday inbound and built on the same server-side technology as app proxy and Pass Through Authentication. It requires an outbound connection only and agents are auto-updated.

+- **Provisioning service**: Same provisioning service as outbound provisioning and Workday inbound provisioning, which uses a scheduler-based model. Cloud sync provisions change every 2 mins.

+## Initial setup

+During initial setup, a few things are done that makes cloud sync happen.

+- **During agent installation**: You configure the agent for the AD domains you want to provision from. This configuration registers the domains in the hybrid identity service and establishes an outbound connection to the service bus listening for requests.

+- **When you enable provisioning**: You select the AD domain and enable provisioning, which runs every 2 mins. Optionally you may deselect password hash sync and define notification email. You can also manage attribute transformation using Microsoft Graph APIs.

+## Agent installation

+The following items occur when the cloud provisioning agent is installed.

+- First, the Installer installs the Agent binaries and the Agent Service running under the Virtual Service Account (NETWORK SERVICE\AADProvisioningAgent). A virtual service account is a special type of account that doesn't have a password and is managed by Windows.

+- The Installer then starts the Wizard.

+- The Wizard will prompt for Azure AD credentials, will then authenticate, and retrieve a token.

+- The wizard then asks for the current machine Domain Administrators credentials.

+- Using these credentials, the agent general managed service account (GMSA) for this domain is either created or located and reused if it already exists.

+- The agent service is now reconfigured to run under the GMSA.

+- The wizard now asks for domain configuration along with the Enterprise Admin (EA)/Domain Admin(DA) Account for each domain you want the agent to service.

+- The GMSA account is then updated with permissions that enable it access to each domain entered during setup.

+- Next, the wizard triggers agent registration

+- The agent creates a certificate and using the Azure AD token, registers itself and the certificate with the Hybrid Identity Service(HIS) Registration Service

+- The Wizard triggers an AgentResourceGrouping call. This call to HIS Admin Service is to assign the agent to one or more AD Domains in the HIS configuration.

+- The wizard now restarts the agent service.

+- The agent calls a Bootstrap Service on restart (and every 10 mins afterwards) to check for configuration updates. The bootstrap service validates the agent identity. It also updates the last bootstrap time. This is important because if agents don't bootstrap, they aren't getting updated Service Bus endpoints and may not be able to receive requests.

+## What is System for Cross-domain Identity Management (SCIM)?

+The [SCIM specification](https://tools.ietf.org/html/draft-scim-core-schema-01) is a standard that is used to automate the exchanging of user or group identity information between identity domains such as Azure AD. SCIM is becoming the de facto standard for provisioning and, when used with federation standards like SAML or OpenID Connect, provides administrators an end-to-end standards-based solution for access management.

+The Azure AD Connect cloud provisioning agent uses SCIM with Azure AD to provision and deprovision users and groups.

+## Synchronization flow

+

+Once you've installed the agent and enabled provisioning, the following flow occurs.

+1. Once configured, the Azure AD Provisioning service calls the Azure AD hybrid service to add a request to the Service bus. The agent constantly maintains an outbound connection to the Service Bus listening for requests and picks up the System for Cross-domain Identity Management (SCIM) request immediately.

+2. The agent breaks up the request into separate queries based on object type.

+3. AD returns the result to the agent and the agent filters this data before sending it to Azure AD.

+4. Agent returns the SCIM response to Azure AD. These responses are based on the filtering that happened within the agent. The agent uses scoping to filter the results.

+5. The provisioning service writes the changes to Azure AD.

+6. If a delta Sync occurs, as opposed to a full sync, then the cookie/watermark is used. New queries will get changes from that cookie/watermark onwards.

+## Supported scenarios:

+The following scenarios are supported for cloud sync.

+- **Existing hybrid customer with a new forest**: Azure AD Connect sync is used for primary forests. Cloud sync is used for provisioning from an AD forest (including disconnected). For more information, see the tutorial [here](tutorial-existing-forest.md).

+ 

+- **New hybrid customer**: Azure AD Connect sync isn't used. Cloud sync is used for provisioning from an AD forest. For more information, see the tutorial [here](tutorial-single-forest.md).

+

+ 

+- **Existing hybrid customer**: Azure AD Connect sync is used for primary forests. Cloud sync is piloted for a small set of users in the primary forests [here](tutorial-existing-forest.md).

+ 

+For more information, see [Supported topologies](plan-cloud-sync-topologies.md).

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Azure AD Connect cloud sync directory extensions and custom attribute mapping'

+description: This topic provides information on custom attribute mapping in cloud sync.

+# Cloud Sync directory extensions and custom attribute mapping

+## Directory extensions

+You can use directory extensions to extend the schema in Azure Active Directory (Azure AD) with your own attributes from on-premises Active Directory. This feature enables you to build LOB apps by consuming attributes that you continue to manage on-premises.

+For additional information on directory extensions see [Using directory extension attributes in claims](../../develop/active-directory-schema-extensions.md)

+ You can see the available attributes by using [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). You can also use this feature to create dynamic groups in Azure AD.

+>[!NOTE]

+> In order to discover new Active Directory extension attributes, the provisioning agent needs to be restarted. You should restart the agent after the directory extensions have been created. For Azure AD extension attributes, the agent doesn't need to be restarted.

+

+## Syncing directory extensions for Azure Active Directory Connect cloud sync

+You can use [directory extensions](/graph/api/resources/extensionproperty?view=graph-rest-1.0&preserve-view=true) to extend the synchronization schema directory definition in Azure Active Directory (Azure AD) with your own attributes.

+>[!Important]

+> Directory extension for Azure Active Directory Connect cloud sync is only supported for applications with the identifier URI ΓÇ£api://&LT;tenantId&GT;/CloudSyncCustomExtensionsAppΓÇ¥ and the [Tenant Schema Extension App](../connect/how-to-connect-sync-feature-directory-extensions.md#configuration-changes-in-azure-ad-made-by-the-wizard) created by Azure AD Connect

+### Create application and service principal for directory extension

+You need to create an [application](/graph/api/resources/application?view=graph-rest-1.0&preserve-view=true) with the identifier URI "api://&LT;tenantId&GT;/CloudSyncCustomExtensionsApp" if it doesn't exist and create a service principal for the application if it doesn't exist.

+ 1. Check if application with the identifier URI "api://&LT;tenantId&GT;/CloudSyncCustomExtensionsApp" exists.

+ - Using Microsoft Graph

+ ```

+ GET /applications?$filter=identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')

+ ```

+ For more information, see [Get application](/graph/api/application-get?view=graph-rest-1.0&tabs=http&preserve-view=true)

+ - Using PowerShell

+

+ ```

+ Get-AzureADApplication -Filter "identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')"

+ ```

+ For more information, see [Get-AzureADApplication](/powershell/module/azuread/get-azureadapplication?view=azureadps-2.0&preserve-view=true)

+ 2. If the application doesn't exist, create the application with identifier URI ΓÇ£api://&LT;tenantId&GT;/CloudSyncCustomExtensionsApp.ΓÇ¥

+ - Using Microsoft Graph

+ ```

+ POST https://graph.microsoft.com/v1.0/applications

+ Content-type: application/json

+ {

+ "displayName": "CloudSyncCustomExtensionsApp",

+ "identifierUris": ["api://<tenant id>/CloudSyncCustomExtensionsApp"]

+ }

+ ```

+ For more information, see [create application](/graph/api/application-post-applications?view=graph-rest-1.0&tabs=http&preserve-view=true)

+ - Using PowerShell

+ ```

+ New-AzureADApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "api://<tenant id>/CloudSyncCustomExtensionsApp"

+ ```

+ For more information, see [New-AzureADApplication](/powershell/module/azuread/new-azureadapplication?view=azureadps-2.0&preserve-view=true)

+

+ 3. Check if the service principal exists for the application with identifier URI ΓÇ£api://&LT;tenantId&GT;/CloudSyncCustomExtensionsAppΓÇ¥.

+ - Using Microsoft Graph

+ ```

+ GET /servicePrincipals?$filter=(appId eq '{appId}')

+ ```

+ For more information, see [get service principal](/graph/api/serviceprincipal-get?view=graph-rest-1.0&tabs=http&preserve-view=true)

+ - Using PowerShell

+ ```

+ Get-AzureADServicePrincipal -ObjectId '<application objectid>'

+ ```

+ For more information, see [Get-AzureADServicePrincipal](/powershell/module/azuread/get-azureadserviceprincipal?view=azureadps-2.0&preserve-view=true&preserve-view=true)

+

+ 4. If a service principal doesn't exist, create a new service principal for the application with identifier URI ΓÇ£api://&LT;tenantId&GT;/CloudSyncCustomExtensionsAppΓÇ¥

+ - Using Microsoft Graph

+ ```

+ POST https://graph.microsoft.com/v1.0/servicePrincipals

+ Content-type: application/json

+ {

+ "appId":

+ "<application appId>"

+ }

+ ```

+ For more information, see [create servicePrincipal](/graph/api/serviceprincipal-post-serviceprincipals?view=graph-rest-1.0&tabs=http&preserve-view=true)

+ - Using PowerShell

+

+ ```

+ New-AzureADServicePrincipal -AppId '<appId>'

+ ```

+ For more information, see [New-AzureADServicePrincipal](/powershell/module/azuread/new-azureadserviceprincipal?view=azureadps-2.0&preserve-view=true)

+

+ 5. You can create directory extensions in Azure AD in several different ways.

+|Method|Description|URL|

+|--|--|--|

+|MS Graph|Create extensions using GRAPH|[Create extensionProperty](/graph/api/application-post-extensionproperty?view=graph-rest-1.0&tabs=http&preserve-view=true)|

+|PowerShell|Create extensions using PowerShell|[New-AzureADApplicationExtensionProperty](/powershell/module/azuread/new-azureadapplicationextensionproperty?view=azureadps-2.0&preserve-view=true)|

+Using Cloud Sync and Azure AD Connect|Create extensions using Azure AD Connect|[Create an extension attribute using Azure AD Connect](../../app-provisioning/user-provisioning-sync-attributes-for-mapping.md#create-an-extension-attribute-using-azure-ad-connect)|

+|Customizing attributes to sync|Information on customizing which attributes to synch|[Customize which attributes to synchronize with Azure AD](../connect/how-to-connect-sync-feature-directory-extensions.md#customize-which-attributes-to-synchronize-with-azure-ad)

+## Use attribute mapping to map Directory Extensions

+If you have extended Active Directory to include custom attributes, you can add these attributes and map them to users.

+To discover and map attributes, click **Add attribute mapping**. The attributes will automatically be discovered and will be available in the drop-down under **source attribute**. Fill in the type of mapping you want and click **Apply**.

+ [](media/custom-attribute-mapping/schema-1.png#lightbox)

+For information on new attributes that are added and updated in Azure AD see the [user resource type](/graph/api/resources/user?view=graph-rest-1.0#properties&preserve-view=true) and consider subscribing to [change notifications](/graph/webhooks).

+For more information on extension attributes, see [Syncing extension attributes for Azure Active Directory Application Provisioning](../../app-provisioning/user-provisioning-sync-attributes-for-mapping.md)

+## Additional resources

+- [Understand the Azure AD schema and custom expressions](concept-attributes.md)

+- [Azure AD Connect sync: Directory extensions](../connect/how-to-connect-sync-feature-directory-extensions.md)

+- [Attribute mapping in Azure AD Connect cloud sync](how-to-attribute-mapping.md)

+ Title: 'Azure AD Connect cloud sync accidental deletes'

+description: This topic describes how to use the accidental delete feature to prevent deletions.

+# Accidental delete prevention

+The following document describes the accidental deletion feature for Azure AD Connect cloud sync. The accidental delete feature is designed to protect you from accidental configuration changes and changes to your on-premises directory that would affect many users and groups. This feature allows you to:

+- configure the ability to prevent accidental deletes automatically.

+- Set the # of objects (threshold) beyond which the configuration takes effect

+- set up a notification email address so they can get an email notification once the sync job in question is put in quarantine for this scenario

+To use this feature, you set the threshold for the number of objects that, if deleted, synchronization should stop. So if this number is reached, the synchronization stops and a notification is sent to the email that is specified. This notification allows you to investigate what is going on.

+For more information and an example, see the following video.

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWK5mV]

+## Configure accidental delete prevention

+To use the new feature, follow the steps below.

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+4. Under **Configuration**, select your configuration.

+5. Select **View default properties**.

+6. Click the pencil next to **Basics**

+5. On the right, fill in the following information.

+ - **Notification email** - email used for notifications

+ - **Prevent accidental deletions** - check this box to enable the feature

+ - **Accidental deletion threshold** - enter the number of objects to stop synchronization and send a notification

+## Recovering from an accidental delete instance

+If you encounter an accidental delete you see this message on the status of your provisioning agent configuration. It says **Delete threshold exceeded**.

+

+

+By clicking on **Delete threshold exceeded**, you'll see the sync status info. This action will provide more details.

+

+ 

+By right-clicking on the ellipses, you get the following options:

+ - View provisioning log

+ - View agent

+ - Allow deletes

+ 

+Using **View provisioning log**, you can see the **StagedDelete** entries and review the information provided on the users that have been deleted.

+

+ 

+### Allowing deletes

+The **Allow deletes** action, deletes the objects that triggered the accidental delete threshold. Use the following procedure to accept these deletes.

+1. Right-click on the ellipses and select **Allow deletes**.

+2. Click **Yes** on the confirmation to allow the deletions.

+

+ 

+3. You'll see confirmation that the deletions were accepted and the status will return to healthy with the next cycle.

+

+ 

+### Rejecting deletions

+If you don't want to allow the deletions, you need to do the following actions:

+- investigate the source of the deletions

+- fix the issue (example, OU was moved out of scope accidentally and you've now readded it back to the scope)

+- Run **Restart sync** on the agent configuration

+## Next steps

+- [Azure AD Connect cloud sync troubleshooting?](how-to-troubleshoot.md)

+- [Azure AD Connect cloud sync error codes](reference-error-codes.md)

+

+ Title: 'Attribute mapping in Azure AD Connect cloud sync'

+description: This article describes how to use the cloud sync feature of Azure AD Connect to map attributes.

+# Attribute mapping in Azure AD Connect cloud sync

+You can use the cloud sync attribute mapping feature to map attributes between your on-premises user or group objects and the objects in Azure AD.

+ :::image type="content" source="media/how-to-attribute-mapping/new-ux-mapping-1.png" alt-text="Screenshot of new UX screen attribute mapping." lightbox="media/how-to-attribute-mapping/new-ux-mapping-1.png":::

+You can customize (change, delete, or create) the default attribute mappings according to your business needs. For a list of attributes that are synchronized, see [Attributes synchronized to Azure Active Directory](../connect/reference-connect-sync-attributes-synchronized.md).

+> [!NOTE]

+> This article describes how to use the Azure portal to map attributes. For information on using Microsoft Graph, see [Transformations](how-to-transformation.md).

+## Understand types of attribute mapping

+With attribute mapping, you control how attributes are populated in Azure AD. Azure AD supports four mapping types:

+|Mapping Type|Description|

+|--|--|

+|**Direct**|The target attribute is populated with the value of an attribute of the linked object in Active Directory.|

+|**Constant**|The target attribute is populated with a specific string that you specify.|

+|**Expression**|The target attribute is populated based on the result of a script-like expression. For more information, see [Expression Builder](how-to-expression-builder.md) and [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md).|

+|**None**|The target attribute is left unmodified. However, if the target attribute is ever empty, it's populated with the default value that you specify.|

+Along with these basic types, custom attribute mappings support the concept of an optional *default* value assignment. The default value assignment ensures that a target attribute is populated with a value if Azure AD or the target object doesn't have a value. The most common configuration is to leave this blank.

+## Schema updates and mappings

+Cloud sync will occasionally update the schema and the list of default attributes that are [synchronized](../connect/reference-connect-sync-attributes-synchronized.md). These default attribute mappings will be available for new installations but will not automatically be added to existing installations. To add these mappings you can follow the steps below.

+ 1. Click on ΓÇ£add attribute mappingΓÇ¥

+ 2. Select the Target attribute dropdown

+ 3. You should see the new attributes that are available here.

+The following is a list of new mappings that were added.

+Attribute Added | Mapping Type | Added with Agent Version

+| -- | --| --|

+|preferredDatalocation|Direct|1.1.359.0|

+|EmployeeNumber|Direct|1.1.359.0|

+|UserType|Direct|1.1.359.0|

+For more information on how to map UserType, see [Map UserType with cloud sync](how-to-map-usertype.md).

+## Understand properties of attribute mappings

+Along with the type property, attribute mappings support certain attributes. These attributes will depend on the type of mapping you have selected. The following sections describe the supported attribute mappings for each of the individual types. The following type of attribute mapping is available.

+- Direct

+- Constant

+- Expression

+### Direct mapping attributes

+The following are the attributes supported by a direct mapping:

+- **Source attribute**: The user attribute from the source system (example: Active Directory).

+- **Target attribute**: The user attribute in the target system (example: Azure Active Directory).

+- **Default value if null (optional)**: The value that will be passed to the target system if the source attribute is null. This value will be provisioned only when a user is created. It won't be provisioned when you're updating an existing user.

+- **Apply this mapping**:

+ - **Always**: Apply this mapping on both user-creation and update actions.

+ - **Only during creation**: Apply this mapping only on user-creation actions.

+### Constant mapping attributes

+The following are the attributes supported by a constant mapping:

+- **Constant value**: The value that you want to apply to the target attribute.

+- **Target attribute**: The user attribute in the target system (example: Azure Active Directory).

+- **Apply this mapping**:

+ - **Always**: Apply this mapping on both user-creation and update actions.

+ - **Only during creation**: Apply this mapping only on user-creation actions.

+### Expression mapping attributes

+The following are the attributes supported by an expression mapping:

+- **Expression**: This is the expression that is going to be applied to the target attribute. For more information, see [Expression Builder](how-to-expression-builder.md) and [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md).

+- **Default value if null (optional)**: The value that will be passed to the target system if the source attribute is null. This value will be provisioned only when a user is created. It won't be provisioned when you're updating an existing user.

+- **Target attribute**: The user attribute in the target system (example: Azure Active Directory).

+

+- **Apply this mapping**:

+ - **Always**: Apply this mapping on both user-creation and update actions.

+ - **Only during creation**: Apply this mapping only on user-creation actions.

+## Add an attribute mapping

+To use attribute mapping, follow these steps:

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-1.png" alt-text="Screenshot of new UX screen." lightbox="media/how-to-on-demand-provision/new-ux-1.png":::

+ 4. Under **Configuration**, select your configuration.

+ 5. On the left, select **Attribute mapping**.

+ 6. At the top, ensure that you have the correct object type selected. That is, user, group, or contact.

+ 7. Click **Add attribute mapping**.

+ :::image type="content" source="media/how-to-attribute-mapping/new-ux-mapping-3.png" alt-text="Screenshot of adding an attribute mapping." lightbox="media/how-to-attribute-mapping/new-ux-mapping-3.png":::

+ 8. Select the mapping type. This can be one of the following:

+ - **Direct**: The target attribute is populated with the value of an attribute of the linked object in Active Directory.

+ - **Constant**: The target attribute is populated with a specific string that you specify.

+ - **Expression**: The target attribute is populated based on the result of a script-like expression.

+ - **None**: The target attribute is left unmodified.

+

+ 9. Depending on what you have selected in the previous step, different options will be available for filling in.

+ 10. Select when to apply this mapping, and then select **Apply**.

+ :::image type="content" source="media/how-to-attribute-mapping/new-ux-mapping-4.png" alt-text="Screenshot of saving an attribute mapping." lightbox="media/how-to-attribute-mapping/new-ux-mapping-4.png":::

+ 11. Back on the **Attribute mappings** screen, you should see your new attribute mapping.

+ 12. Select **Save schema**. You will be notified that once you save the schema, a synchronization will occur. Click **OK**.

+ :::image type="content" source="media/how-to-attribute-mapping/new-ux-mapping-5.png" alt-text="Screenshot of saving schema." lightbox="media/how-to-attribute-mapping/new-ux-mapping-5.png":::

+ 13. Once the save is successful you will see a notification on the right.

+ :::image type="content" source="media/how-to-attribute-mapping/new-ux-mapping-6.png" alt-text="Screenshot of successful schema save." lightbox="media/how-to-attribute-mapping/new-ux-mapping-6.png":::

+## Test your attribute mapping

+To test your attribute mapping, you can use [on-demand provisioning](how-to-on-demand-provision.md):

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+ 4. Under **Configuration**, select your configuration.

+ 5. On the left, select **Provision on demand**.

+ 6. Enter the distinguished name of a user and select the **Provision** button.

+

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-2.png" alt-text="Screenshot of user distinguished name." lightbox="media/how-to-on-demand-provision/new-ux-2.png":::

+ 7. After provisioning finishes, a success screen appears with four green check marks. Any errors appear to the left.

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-3.png" alt-text="Screenshot of on-demand success." lightbox="media/how-to-on-demand-provision/new-ux-3.png":::

+## Next steps

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+- [Writing expressions for attribute mappings](reference-expressions.md)

+- [How to use expression builder with cloud sync](how-to-expression-builder.md)

+- [Attributes synchronized to Azure Active Directory](../connect/reference-connect-sync-attributes-synchronized.md)

+ Title: 'Azure AD Connect cloud provisioning agent: Automatic upgrade'

+description: This article describes the built-in automatic upgrade feature in the Azure AD Connect cloud provisioning agent.

+documentationcenter: ''

+editor: ''

+ na

+# Azure AD Connect cloud provisioning agent: Automatic upgrade

+Making sure your Azure Active Directory (Azure AD) Connect cloud provisioning agent installation is always up to date is easy with the automatic upgrade feature.

+The agent is installed here: "Program files\Azure AD Connect Provisioning Agent\AADConnectProvisioningAgent.exe"

+To verify your version, right-click the executable and select properties and then details.

+

+The agent updater is installed here: "Program files\Azure AD Connect Provisioning Agent Updater\AzureADConnectAgentUpdater.exe"

+To verify your version, right-click the executable and select properties and then details.

+

+## Uninstall the agent

+To remove the agent, go to **Uninstall or change a program** and uninstall the following:

+- **Microsoft Azure AD Connect Agent Updater**

+- **Microsoft Azure AD Connect Provisioning Agent**

+- **Microsoft Azure AD Connect Provisioning Agent Package**

+

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Azure AD cloud sync insights workbook'

+description: This article describes the Azure Monitor workbook for cloud sync.

+# Azure AD cloud sync insights workbook

+The Cloud sync workbook provides a flexible canvas for data analysis. The workbook allows you to create rich visual reports within the Azure portal. To learn more, see Azure Monitor Workbooks overview.

+This workbook is intended for Hybrid Identity Admins who use cloud sync to sync users from AD to Azure AD. It allows admins to gain insights into sync status and details.

+The workbook can be accessed by select **Insights** on the left hand side of the cloud sync page.

+ :::image type="content" source="media/how-to-cloud-sync-workbook/workbook-1.png" alt-text="Screenshot of the cloud sync workbook." lightbox="media/how-to-cloud-sync-workbook/workbook-1.png":::

+>[!NOTE]

+>The Insights node is available at both the all configurations level and the individual configuration level. To view information on individual configurations select the Job Id for the configuration.

+This workbook:

+- Provides a synchronization summary of users and groups synchronized from AD to Azure AD

+- Provides a detailed view of information captured by the cloud sync provisioning logs.

+- Allows you to customize the data to tailor it to your specific needs

+|Field|Description|

+|--|--|

+|Date|The range that you want to view data on.|

+|Status|View the provisioning status such as Success or Skipped.|

+|Action|View the provisioning actions taken such as Create or Delete.|

+|Job Id|Allows you to target specific Job Ids. This can be used to see individual configuration data if you have multiple configurations.|

+|SyncType|Filter by type of synchronization such as object or password.|

+## Enabling provisioning logs

+You should already be familiar with Azure monitoring and Log Analytics. If not, jump over to learn about them and then come back to learn about application provisioning logs. To learn more about Azure monitoring, see [Azure Monitor overview](../../../azure-monitor/overview.md). To learn more about Azure Monitor logs and Log Analytics, see [Overview of log queries in Azure Monitor](../../../azure-monitor/logs/log-query-overview.md) and [Provisioning Logs for troubleshooting cloud sync](how-to-troubleshoot.md).

+## Sync summary

+The sync summary section provides a summary of your organizations synchronization activities. These activities include:

+ - Sync actions per day by action

+ - Sync actions per day by status

+ - Unique sync count by status

+ - Recent sync errors

+ :::image type="content" source="media/how-to-cloud-sync-workbook/workbook-2.png" alt-text="Screenshot of the cloud sync summary." lightbox="media/how-to-cloud-sync-workbook/workbook-2.png":::

+## Sync details

+The sync details tab allows you to drill into the synchronization data and get more information. This information includes:

+ - Objects sync by status

+ - Sync log details

+

+ :::image type="content" source="media/how-to-cloud-sync-workbook/workbook-3.png" alt-text="Screenshot of the cloud sync details." lightbox="media/how-to-cloud-sync-workbook/workbook-3.png":::

+You can further drill in to the sync log details for additional information.

+ :::image type="content" source="media/how-to-cloud-sync-workbook/workbook-4.png" alt-text="Screenshot of the log details." lightbox="media/how-to-cloud-sync-workbook/workbook-4.png":::

+## Job Id

+A Job Id will be created for each configuration when it runs and is populated with data. You can look at individual configuration based on Job Id.

+## Custom queries

+You can create custom queries and show the data on Azure dashboards. To learn how, see [Create and share dashboards of Log Analytics data](../../../azure-monitor/logs/get-started-queries.md). Also, be sure to check out [Overview of log queries in Azure Monitor](../../../azure-monitor/logs/log-query-overview.md).

+## Custom alerts

+Azure Monitor lets you configure custom alerts so that you can get notified about key events related to Provisioning. For example, you might want to receive an alert on spikes in failures. Or perhaps spikes in disables or deletes. Another example of where you might want to be alerted is a lack of any provisioning, which indicates something is wrong.

+To learn more about alerts, see [Azure Monitor Log Alerts](../../../azure-monitor/alerts/alerts-log.md).

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+- [Known limitations](how-to-prerequisites.md#known-limitations)

+- [Error codes](reference-error-codes.md)

+ Title: 'Azure AD Connect cloud sync new agent configuration'

+description: This article describes how to install cloud sync.

+# Create a new configuration for Azure AD Connect cloud sync

+The following document will guide you through configuring Azure AD Connect cloud sync.

+The following documentation demonstrates the new guided user experience for Azure AD Connect cloud sync. If you are not seeing the images below, you need to select the **Preview features** at the top. You can select this again to revert back to the old experience.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-19.png" alt-text="Screenshot of enable preview features." lightbox="media/how-to-configure/new-ux-configure-19.png":::

+For additional information and an example of how to configure cloud sync, see the video below.

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWKact]

+## Configure provisioning

+To configure provisioning, follow these steps.

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-1.png" alt-text="Screenshot of new UX screen." lightbox="media/how-to-on-demand-provision/new-ux-1.png":::

+

+ 4. Select **New configuration**.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-1.png" alt-text="Screenshot of adding a configuration." lightbox="media/how-to-configure/new-ux-configure-1.png":::

+ 5. On the configuration screen, select your domain and whether to enable password hash sync. Click **Create**.

+

+ :::image type="content" source="media/how-to-configure/new-ux-configure-2.png" alt-text="Screenshot of a new configuration." lightbox="media/how-to-configure/new-ux-configure-2.png":::

+ 6. The **Get started** screen will open. From here, you can continue configuring cloud sync.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-3.png" alt-text="Screenshot of the getting started screen." lightbox="media/how-to-configure/new-ux-configure-3.png":::

+ 7. The configuration is split in to the following 5 sections.

+|Section|Description|

+|--|--|

+|1. Add [scoping filters](#scope-provisioning-to-specific-users-and-groups)|Use this section to define what objects appear in Azure AD|

+|2. Map [attributes](#attribute-mapping)|Use this section to map attributes between your on-premises users/groups with Azure AD objects|

+|3. [Test](#on-demand-provisioning)|Test your configuration before deploying it|

+|4. View [default properties](#accidental-deletions-and-email-notifications)|View the default setting prior to enabling them and make changes where appropriate|

+|5. Enable [your configuration](#enable-your-configuration)|Once ready, enable the configuration and users/groups will begin synchronizing|

+ >[!NOTE]

+ > During the configuration process the synchronization service account will be created with the format **ADToAADSyncServiceAccount@[TenantID].onmicrosoft.com** and you may get an error if multi-factor authentication is enabled for the synchronization service account, or other interactive authentication policies are accidentally enabled for the synchronization account. Removing multi-factor authentication or any interactive authentication policies for the synchronization service account should resolve the error and you can complete the configuration smoothly.

+## Scope provisioning to specific users and groups

+You can scope the agent to synchronize specific users and groups by using on-premises Active Directory groups or organizational units.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-4.png" alt-text="Screenshot of scoping filters icon." lightbox="media/how-to-configure/new-ux-configure-4.png":::

+You can't configure groups and organizational units within a configuration.

+ >[!NOTE]

+ > You cannot use nested groups with group scoping. Nested objects beyond the first level will not be included when scoping using security groups. Only use group scope filtering for pilot scenarios as there are limitations to syncing large groups.

+

+ 1. On the **Getting started** configuration screen. Click either **Add scoping filters** next to the **Add scoping filters** icon or on the click **Scoping filters** on the left under **Manage**.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-5.png" alt-text="Screenshot of scoping filters." lightbox="media/how-to-configure/new-ux-configure-5.png":::

+

+ 2. Select the scoping filter. The filter can be one of the following:

+ - **All users**: Scopes the configuration to apply to all users that are being synchronized.

+ - **Selected security groups**: Scopes the configuration to apply to specific security groups.

+ - **Selected organizational units**: Scopes the configuration to apply to specific OUs.

+ 3. For security groups and organizational units, supply the appropriate distinguished name and click **Add**.

+ 4. Once your scoping filters are configured, click **Save**.

+ 5. After saving, you should see a message telling you what you still need to do to configure cloud sync. You can click the link to continue.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-16.png" alt-text="Screenshot of the nudge for scoping filters." lightbox="media/how-to-configure/new-ux-configure-16.png":::

+ 7. Once you've changed the scope, you should [restart provisioning](#restart-provisioning) to initiate an immediate synchronization of the changes.

+## Attribute mapping

+Azure AD Connect cloud sync allows you to easily map attributes between your on-premises user/group objects and the objects in Azure AD.

+You can customize the default attribute-mappings according to your business needs. So, you can change or delete existing attribute-mappings, or create new attribute-mappings.

+After saving, you should see a message telling you what you still need to do to configure cloud sync. You can click the link to continue.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-17.png" alt-text="Screenshot of the nudge for attribute filters." lightbox="media/how-to-configure/new-ux-configure-17.png":::

+For more information, see [attribute mapping](how-to-attribute-mapping.md).

+## Directory extensions and custom attribute mapping.

+Azure AD Connect cloud sync allows you to extend the directory with extensions and provides for custom attribute mapping. For more information see [Directory extensions and custom attribute mapping](custom-attribute-mapping.md).

+## On-demand provisioning

+Azure AD Connect cloud sync allows you to test configuration changes, by applying these changes to a single user or group.

+You can use this to validate and verify that the changes made to the configuration were applied properly and are being correctly synchronized to Azure AD.

+After testing, you should see a message telling you what you still need to do to configure cloud sync. You can click the link to continue.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-18.png" alt-text="Screenshot of the nudge for testing." lightbox="media/how-to-configure/new-ux-configure-18.png":::

+For more information, see [on-demand provisioning](how-to-on-demand-provision.md).

+## Accidental deletions and email notifications

+The default properties section provides information on accidental deletions and email notifications.

+The accidental delete feature is designed to protect you from accidental configuration changes and changes to your on-premises directory that would affect many users and groups.

+This feature allows you to:

+- configure the ability to prevent accidental deletes automatically.

+- Set the # of objects (threshold) beyond which the configuration will take effect

+- set up a notification email address so they can get an email notification once the sync job in question is put in quarantine for this scenario

+For more information, see [Accidental deletes](how-to-accidental-deletes.md)

+Click the **pencil** next to **Basics** to change the defaults in a configuration.

+## Enable your configuration

+Once you've finalized and tested your configuration, you can enable it.

+Click **Enable configuration** to enable it.

+## Quarantines

+Cloud sync monitors the health of your configuration and places unhealthy objects in a quarantine state. If most or all of the calls made against the target system consistently fail because of an error, for example, invalid admin credentials, the sync job is marked as in quarantine. For more information, see the troubleshooting section on [quarantines](how-to-troubleshoot.md#provisioning-quarantined-problems).

+## Restart provisioning

+If you don't want to wait for the next scheduled run, trigger the provisioning run by using the **Restart sync** button.

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+ 4. Under **Configuration**, select your configuration.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-14.png" alt-text="Screenshot of restarting sync." lightbox="media/how-to-configure/new-ux-configure-14.png":::

+ 5. At the top, select **Restart sync**.

+## Remove a configuration

+To delete a configuration, follow these steps.

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+ 4. Under **Configuration**, select your configuration.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-15.png" alt-text="Screenshot of deletion." lightbox="media/how-to-configure/new-ux-configure-15.png":::

+ 5. At the top of the configuration screen, select **Delete configuration**.

+>[!IMPORTANT]

+>There's no confirmation prior to deleting a configuration. Make sure this is the action you want to take before you select **Delete**.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Use the expression builder with Azure AD Connect cloud sync'

+description: This article describes how to use the expression builder with cloud sync.

+# Expression builder with cloud sync

+The expression builder is a new function in Azure located under cloud sync. It helps you build complex expressions. You can use it to test these expressions before you apply them to your cloud sync environment.

+## Use the expression builder

+To access the expression builder:

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 1. Select **Azure AD Connect**.

+ 1. Select **Manage cloud sync**.

+ 1. Under **Configuration**, select your configuration.

+ 1. Under **Manage attributes**, select **Click to edit mappings**.

+ 1. On the **Edit attribute mappings** pane, select **Add attribute mapping**.

+ 1. Under **Mapping type**, select **Expression**.

+ 1. Select **Try the expression builder (Preview)**.

+

+ 

+## Build an expression

+In this section, you use the dropdown list to select from supported functions. Then you fill in more boxes, depending on the function selected. After you select **Apply expression**, the syntax appears in the **Expression input** box.

+For example, by selecting **Replace** from the dropdown list, more boxes are provided. The syntax for the function is displayed in the light blue box. The boxes that are displayed correspond to the syntax of the function you selected. Replace works differently depending on the parameters provided.

+For this example, when **oldValue** and **replacementValue** are provided, all occurrences of **oldValue** are replaced in the source with **replacementValue**.

+For more information, see [Replace](reference-expressions.md#replace).

+The first thing you need to do is select the attribute that's the source for the replace function. In this example, the **mail** attribute is selected.

+Next, find the box for **oldValue** and enter **@fabrikam.com**. Finally, in the box for **replacementValue**, fill in the value **@contoso.com**.

+The expression basically says, replace the mail attribute on user objects that have a value of @fabrikam.com with the @contoso.com value. When you select **Add expression**, you can see the syntax in the **Expression input** box.

+>[!NOTE]

+>Be sure to place the values in the boxes that would correspond with **oldValue** and **replacementValue** based on the syntax that occurs when you've selected **Replace**.

+For more information on supported expressions, see [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md).

+### Information on expression builder input boxes

+Depending on which function you selected, the boxes provided by the expression builder will accept multiple values. For example, the JOIN function will accept strings or the value that's associated with a given attribute. For example, we can use the value contained in the attribute value of **[givenName]** and join it with a string value of **@contoso.com** to create an email address.

+ 

+For more information on acceptable values and how to write expressions, see [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md).

+## Test an expression

+In this section, you can test your expressions. From the dropdown list, select the **mail** attribute. Fill in the value with **@fabrikam.com**, and select **Test expression**.

+The value **@contoso.com** appears in the **View expression output** box.

+ 

+## Deploy the expression

+After you're satisfied with the expression, select **Apply expression**.

+

+This action adds the expression to the agent configuration.

+

+## Set a NULL value on an expression

+To set an attribute's value to NULL, use an expression with the value of `""`. This expression will flow the NULL value to the target attribute.

+

+## Next steps

+- [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md)

+- [Cloud sync configuration](how-to-configure.md)

+ Title: 'Azure AD Connect cloud provisioning agent gMSA PowerShell cmdlets'

+description: Learn how to use the Azure AD Connect cloud provisioning agent gMSA powershell cmdlets.

+# Azure AD Connect cloud provisioning agent gMSA PowerShell cmdlets

+The purpose of this document is to describe the Azure AD Connect cloud provisioning agent gMSA PowerShell cmdlets. These cmdlets allow you to have more granularity on the permissions that are applied on the service account (gMSA). By default, Azure AD Connect cloud sync applies all permissions similar to Azure AD Connect on the default gMSA or a custom gMSA, during cloud provisioning agent install.

+This document will cover the following cmdlets:

+`Set-AADCloudSyncPermissions`

+`Set-AADCloudSyncRestrictedPermissions`

+## How to use the cmdlets:

+The following prerequisites are required to use these cmdlets.

+1. Install provisioning agent.

+2. Import Provisioning Agent PS module into a PowerShell session.

+ ```powershell

+ Import-Module "C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\Microsoft.CloudSync.Powershell.dll"

+ ```

+3. These cmdlets require a parameter called `Credential` which can be passed, or will prompt the user if not provided in the command line. Depending on the cmdlet syntax used, these credentials must be an enterprise admin account or, at a minimum, a domain administrator of the target domain where you're setting the permissions.

+4. To create a variable for credentials, use:

+ `$credential = Get-Credential`

+

+5. To set Active Directory permissions for cloud provisioning agent, you can use the following cmdlet. This will grant permissions in the root of the domain allowing the service account to manage on-premises Active Directory objects. See [Using Set-AADCloudSyncPermissions](#using-set-aadcloudsyncpermissions) below for examples on setting the permissions.

+ `Set-AADCloudSyncPermissions -EACredential $credential`

+6. To restrict Active Directory permissions set by default on the cloud provisioning agent account, you can use the following cmdlet. This will increase the security of the service account by disabling permission inheritance and removing all existing permissions, except SELF and Full Control for administrators. See [Using Set-AADCloudSyncRestrictedPermission](#using-set-aadcloudsyncrestrictedpermissions) below for examples on restricting the permissions.

+ `Set-AADCloudSyncRestrictedPermission -Credential $credential`

+## Using Set-AADCloudSyncPermissions

+`Set-AADCloudSyncPermissions` supports the following permission types which are identical to the permissions used by Azure AD Connect Classic Sync (ADSync). The following permission types are supported:

+|Permission type|Description|

+|--|--|

+|BasicRead| See [BasicRead](../connect/how-to-connect-configure-ad-ds-connector-account.md#configure-basic-read-only-permissions) permissions for Azure AD Connect|

+|PasswordHashSync|See [PasswordHashSync](../connect/how-to-connect-configure-ad-ds-connector-account.md#permissions-for-password-hash-synchronization) permissions for Azure AD Connect|

+|PasswordWriteBack|See [PasswordWriteBack](../connect/how-to-connect-configure-ad-ds-connector-account.md#permissions-for-password-writeback) permissions for Azure AD Connect|

+|HybridExchangePermissions|See [HybridExchangePermissions](../connect/how-to-connect-configure-ad-ds-connector-account.md#permissions-for-exchange-hybrid-deployment) permissions for Azure AD Connect|

+|ExchangeMailPublicFolderPermissions| See [ExchangeMailPublicFolderPermissions](../connect/how-to-connect-configure-ad-ds-connector-account.md#permissions-for-exchange-mail-public-folders) permissions for Azure AD Connect|

+|CloudHR| Applies 'Create/delete User objects' on 'This object and all descendant objects'|

+|All| Applies all the above permissions|

+You can use AADCloudSyncPermissions in one of two ways:

+- [Grant permissions to all configured domains](#grant-permissions-to-all-configured-domains)

+- [Grant permissions to a specific domain](#grant-permissions-to-a-specific-domain)

+## Grant permissions to all configured domains

+Granting certain permissions to all configured domains will require the use of an enterprise admin account.

+```powershell

+$credential = Get-Credential

+Set-AADCloudSyncPermissions -PermissionType "Any mentioned above" -EACredential $credential

+```

+## Grant permissions to a specific domain

+Granting certain permissions to a specific domain will require the use of a TargetDomainCredential that is enterprise admin or, domain admin of the target domain. The TargetDomain has to be already configured through wizard.

+```powershell

+$credential = Get-Credential

+Set-AADCloudSyncPermissions -PermissionType "Any mentioned above" -TargetDomain "FQDN of domain" -TargetDomainCredential $credential

+```

+## Using Set-AADCloudSyncRestrictedPermissions

+For increased security, `Set-AADCloudSyncRestrictedPermissions` will tighten the permissions set on the cloud provisioning agent account itself. Hardening permissions on the cloud provisioning agent account involves the following changes:

+- Disable inheritance

+- Remove all default permissions, except ACEs specific to SELF.

+- Set Full Control permissions for SYSTEM, Administrators, Domain Admins, and Enterprise Admins.

+- Set Read permissions for Authenticated Users and Enterprise Domain Controllers.

+

+ The -Credential parameter is necessary to specify the Administrator account that has the necessary privileges to restrict Active Directory permissions on the cloud provisioning agent account. This is typically the domain or enterprise administrator.

+

+For Example:

+``` powershell

+$credential = Get-Credential

+Set-AADCloudSyncRestrictedPermissions -Credential $credential

+```

+ Title: 'How to programmatically configure cloud sync using MS Graph API'

+description: This topic describes how to enable inbound synchronization using just the Graph API

+# How to programmatically configure cloud sync using MS Graph API

+The following document describes how to replicate a synchronization profile from scratch using only MSGraph APIs.

+The structure of how to do this consists of the following steps. They are:

+- [How to programmatically configure cloud sync using MS Graph API](#how-to-programmatically-configure-cloud-sync-using-ms-graph-api)

+ - [Basic setup](#basic-setup)

+ - [Enable tenant flags](#enable-tenant-flags)

+ - [Create service principals](#create-service-principals)

+ - [Create sync job](#create-sync-job)

+ - [Update targeted domain](#update-targeted-domain)

+ - [Enable Sync password hashes on configuration blade](#enable-sync-password-hashes-on-configuration-blade)

+ - [Accidental deletes](#accidental-deletes)

+ - [Enabling and setting the threshold](#enabling-and-setting-the-threshold)

+ - [Allowing deletes](#allowing-deletes)

+ - [Start sync job](#start-sync-job)

+ - [Review status](#review-status)

+ - [Next steps](#next-steps)

+Use these [Microsoft Azure Active Directory Module for Windows PowerShell](/powershell/module/msonline/) commands to enable synchronization for a production tenant, a prerequisite for being able to call the Administration Web Service for that tenant.

+## Basic setup

+### Enable tenant flags

+```powershell

+Connect-MsolService ('-AzureEnvironment <AzureEnvironmnet>')

+ Set-MsolDirSyncEnabled -EnableDirSync $true

+```

+The first of those two commands, require Azure Active Directory credentials. These cmdlets implicitly identify the tenant and enable it for synchronization.

+## Create service principals

+Next, we need to create the [AD2AAD application/ service principal](/graph/api/applicationtemplate-instantiate)

+You need to use this application ID 1a4721b3-e57f-4451-ae87-ef078703ec94. The displayName is the AD domain URL, if used in the portal (for example, contoso.com), but it may be named something else.

+```

+POST https://graph.microsoft.com/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate

+Content-type: application/json

+{

+ displayName: [your app name here]

+}

+```

+## Create sync job

+The output of the above command returns the objectId of the service principal that was created. For this example, the objectId is 614ac0e9-a59b-481f-bd8f-79a73d167e1c. Use Microsoft Graph to add a synchronizationJob to that service principal.

+Documentation for creating a sync job can be found [here](/graph/api/synchronization-synchronizationjob-post?tabs=http&view=graph-rest-beta&preserve-view=true).

+If you did not record the ID above, you can find the service principal by running the following MS Graph call. You'll need Directory.Read.All permissions to make that call:

+`GET https://graph.microsoft.com/beta/servicePrincipals`

+Then look for your app name in the output.

+Run the following two commands to create two jobs: one for user/group provisioning, and one for password hash syncing. It's the same request twice but with different template IDs.

+Call the following two requests:

+```

+POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs

+Content-type: application/json

+{

+"templateId":"AD2AADProvisioning"

+}

+```

+```

+POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs

+Content-type: application/json

+{

+"templateId":"AD2AADPasswordHash"

+}

+```

+You need two calls if you want to create both.

+Example return value (for provisioning):

+```

+HTTP 201/Created

+{

+ "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('614ac0e9-a59b-481f-bd8f-79a73d167e1c')/synchronization/jobs/$entity",

+ "id": "AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da",

+ "templateId": "ADDCInPassthrough",

+ "schedule": {

+ "expiration": null,

+ "interval": "PT40M",

+ "state": "Disabled"

+ },

+ "status": {

+ "countSuccessiveCompleteFailures": 0,

+ "escrowsPruned": false,

+ "code": "Paused",

+ "lastExecution": null,

+ "lastSuccessfulExecution": null,

+ "lastSuccessfulExecutionWithExports": null,

+ "quarantine": null,

+ "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",

+ "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",

+ "troubleshootingUrl": null,

+ "progress": [],

+ "synchronizedEntryCountByType": []

+ }

+}

+```

+## Update targeted domain

+For this tenant, the object identifier and application identifier of the service principal are as follows:

+ObjectId: 8895955e-2e6c-4d79-8943-4d72ca36878f

+AppId: 00000014-0000-0000-c000-000000000000

+DisplayName: testApp

+We're going to need to update the domain this configuration is targeting, so update the secrets for this domain.

+Make sure the domain name you use is the same URL you set for your on-premises domain controller.

+```

+PUT ΓÇô https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

+```

+Add the following key/value pair in the below value array based on what you're trying to do:

+- Enable both PHS and sync tenant flags

+ { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

+- Enable only sync tenant flag (do not turn on PHS)

+ { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

+```

+Request body ΓÇô

+{

+ "value": [

+ {

+ "key": "Domain",

+ "value": "{\"domain\":\"ad2aadTest.com\"}"

+ }

+ ]

+}

+```

+The expected response is …

+HTTP 204/No content

+Here, the highlighted "Domain" value is the name of the on-premises Active Directory domain from which entries are to be provisioned to Azure Active Directory.

+## Enable Sync password hashes on configuration blade

+ This section covers enabling syncing password hashes for a particular configuration. This is different than the AppKey secret that enables the tenant-level feature flag - this is only for a single domain/config. You need to set the application key to the PHS one for this to work end to end.

+1. Grab the schema (warning, it's pretty large):

+ ```

+ GET ΓÇôhttps://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema

+ ```

+2. Take this CredentialData attribute mapping:

+ ```

+ {

+ "defaultValue": null,

+ "exportMissingReferences": false,

+ "flowBehavior": "FlowWhenChanged",

+ "flowType": "Always",

+ "matchingPriority": 0,

+ "targetAttributeName": "CredentialData",

+ "source": {

+ "expression": "[PasswordHash]",

+ "name": "PasswordHash",

+ "type": "Attribute",

+ "parameters": []

+ }

+ ```

+3. Find the following object mappings with the following names in the schema

+ - Provision Active Directory Users

+ - Provision Active Directory inetOrgPersons

+ Object mappings are within the schema.synchronizationRules[0].objectMappings (For now you can assume there's only one Synchronization Rule)

+4. Take the CredentialData Mapping from Step (2) and insert it into the object mappings in Step (3)

+ Your object mapping looks something like this:

+ ```

+ {

+ "enabled": true,

+ "flowTypes": "Add,Update,Delete",

+ "name": "Provision Active Directory users",

+ "sourceObjectName": "user",

+ "targetObjectName": "User",

+ "attributeMappings": [

+ ...

+ }

+ ```

+ Copy/paste the mapping from the **Create AD2AADProvisioning and AD2AADPasswordHash jobs** step above into the attributeMappings array.

+ Order of elements in this array doesn't matter (the backend sorts for you). Be careful about adding this attribute mapping if the name exists already in the array (e.g. if there's already an item in attributeMappings that has the targetAttributeName CredentialData) - you may get conflict errors, or the pre-existing and new mappings may be combined together (usually not desired outcome). Backend does not dedupe for you.

+ Remember to do this for both Users and inetOrgpersons.

+5. Save the schema you've created:

+ ```

+ PUT ΓÇô

+ https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema

+ ```

+Add the Schema in the request body.

+## Accidental deletes

+This section covers how to programmatically enable/disable and use [accidental deletes](how-to-accidental-deletes.md) programmatically.

+### Enabling and setting the threshold

+There are two per job settings that you can use, they are:

+- DeleteThresholdEnabled - Enables accidental delete prevention for the job when set to 'true'. Set to 'true' by default.

+- DeleteThresholdValue - Defines the maximum number of deletes that is allowed in each execution of the job when accidental deletes prevention is enabled. The value is set to 500 by default. So, if the value is set to 500, the maximum number of deletes allowed is 499 in each execution.

+The delete threshold settings are a part of the `SyncNotificationSettings` and can be modified via graph.

+We're going to need to update the SyncNotificationSettings this configuration is targeting, so update the secrets.

+```

+PUT ΓÇô https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

+```

+Add the following Key/value pair in the below value array based on what you're trying to do:

+```

+Request body -

+{

+ "value":[

+ {

+ "key":"SyncNotificationSettings",

+ "value": "{\"Enabled\":true,\"Recipients\":\"foobar@xyz.com\",\"DeleteThresholdEnabled\":true,\"DeleteThresholdValue\":50}"

+ }

+ ]

+}

+```

+The "Enabled" setting in the example is for enabling/disabling notification emails when the job is quarantined.

+Currently, we do not support PATCH requests for secrets, so you need to add all the values in the body of the PUT request(like in the example) in order to preserve the other values.

+The existing values for all the secrets can be retrieved by using:

+```

+GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets

+```

+### Allowing deletes

+To allow these deletes to flow through after the job goes into quarantine, you need to issue a restart with just "ForceDeletes" as the scope.

+```

+Request:

+POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

+```

+```

+Request Body:

+{

+ "criteria": {"resetScope": "ForceDeletes"}

+}

+```

+## Start sync job

+The job can be retrieved again via the following command:

+ `GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/`

+Documentation for retrieving jobs can be found [here](/graph/api/synchronization-synchronizationjob-list?tabs=http&view=graph-rest-beta&preserve-view=true).

+To start the job, issue this request, using the objectId of the service principal created in the first step, and the job identifier returned from the request that created the job.

+Documentation for how to start a job can be found [here](/graph/api/synchronization-synchronizationjob-start?tabs=http&view=graph-rest-beta&preserve-view=true).

+```

+POST https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

+```

+The expected response is …

+HTTP 204/No content.

+Other commands for controlling the job are documented [here](/graph/api/resources/synchronization-synchronizationjob?view=graph-rest-beta&preserve-view=true).

+To restart a job, use:

+```

+POST https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/restart

+{

+ "criteria": {

+ "resetScope": "Full"

+ }

+}

+```

+## Review status

+Retrieve your job statuses via:

+```

+GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

+```

+Look under the 'status' section of the return object for relevant details

+## Next steps

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+- [Transformations](how-to-transformation.md)

+- [Azure AD Synchronization API](/graph/api/resources/synchronization-overview?view=graph-rest-beta&preserve-view=true)

+ Title: 'Install the Azure AD Connect cloud provisioning agent using a command-line interface (CLI) and PowerShell'

+description: Learn how to install the Azure AD Connect cloud provisioning agent by using PowerShell cmdlets.

+# Install the Azure AD Connect provisioning agent by using a CLI and PowerShell

+This article shows you how to install the Azure Active Directory (Azure AD) Connect provisioning agent by using PowerShell cmdlets.

+

+>[!NOTE]

+>This article deals with installing the provisioning agent by using the command-line interface (CLI). For information on how to install the Azure AD Connect provisioning agent by using the wizard, see [Install the Azure AD Connect provisioning agent](how-to-install.md).

+## Prerequisite

+The Windows server must have TLS 1.2 enabled before you install the Azure AD Connect provisioning agent by using PowerShell cmdlets. To enable TLS 1.2, follow the steps in [Prerequisites for Azure AD Connect cloud sync](how-to-prerequisites.md#tls-requirements).

+>[!IMPORTANT]

+>The following installation instructions assume that all the [prerequisites](how-to-prerequisites.md) were met.

+## Install the Azure AD Connect provisioning agent by using PowerShell cmdlets

+ 1. Sign in to the server you use with enterprise admin permissions.

+ 2. Sign in to the Azure portal, and then go to **Azure Active Directory**.

+ 3. On the menu on the left, select **Azure AD Connect**.

+ 4. Select **Manage cloud sync**.

+ [](media/how-to-install/new-install-1.png#lightbox)</br>

+ 5. At the top, click **Download agent**.

+ [](media/how-to-install/new-install-2.png#lightbox)</br>

+ 6. On the right, click **Accept terms and download**.

+ 7. For the purposes of these instructions, the agent was downloaded to the C:\temp folder.

+ 8. Install ProvisioningAgent in quiet mode.

+ ```

+ $installerProcess = Start-Process 'c:\temp\AADConnectProvisioningAgentSetup.exe' /quiet -NoNewWindow -PassThru

+ $installerProcess.WaitForExit()

+ ```

+ 9. Import the Provisioning Agent PS module.

+ ```

+ Import-Module "C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\Microsoft.CloudSync.PowerShell.dll"

+ ```

+ 10. Connect to Azure AD by using an account with the hybrid identity role. You can customize this section to fetch a password from a secure store.

+ ```

+ $hybridAdminPassword = ConvertTo-SecureString -String "Hybrid identity admin password" -AsPlainText -Force

+

+ $hybridAdminCreds = New-Object System.Management.Automation.PSCredential -ArgumentList ("HybridIDAdmin@contoso.onmicrosoft.com", $hybridAdminPassword)

+

+ Connect-AADCloudSyncAzureAD -Credential $hybridAdminCreds

+ ```

+ 11. Add the gMSA account, and provide credentials of the domain admin to create the default gMSA account.

+ ```

+ $domainAdminPassword = ConvertTo-SecureString -String "Domain admin password" -AsPlainText -Force

+

+ $domainAdminCreds = New-Object System.Management.Automation.PSCredential -ArgumentList ("DomainName\DomainAdminAccountName", $domainAdminPassword)

+

+ Add-AADCloudSyncGMSA -Credential $domainAdminCreds

+ ```

+ 12. Or use the preceding cmdlet to provide a precreated gMSA account.

+ ```

+ Add-AADCloudSyncGMSA -CustomGMSAName preCreatedGMSAName$

+ ```

+ 13. Add the domain.

+ ```

+ $contosoDomainAdminPassword = ConvertTo-SecureString -String "Domain admin password" -AsPlainText -Force

+

+ $contosoDomainAdminCreds = New-Object System.Management.Automation.PSCredential -ArgumentList ("DomainName\DomainAdminAccountName", $contosoDomainAdminPassword)

+

+ Add-AADCloudSyncADDomain -DomainName contoso.com -Credential $contosoDomainAdminCreds

+ ```

+ 14. Or use the preceding cmdlet to configure preferred domain controllers.

+ ```

+ $preferredDCs = @("PreferredDC1", "PreferredDC2", "PreferredDC3")

+

+ Add-AADCloudSyncADDomain -DomainName contoso.com -Credential $contosoDomainAdminCreds -PreferredDomainControllers $preferredDCs

+ ```

+ 15. Repeat the previous step to add more domains. Provide the account names and domain names of the respective domains.

+ 16. Restart the service.

+ ```

+ Restart-Service -Name AADConnectProvisioningAgent

+ ```

+ 17. Go to the Azure portal to create the cloud sync configuration.

+## Provisioning agent gMSA PowerShell cmdlets

+Now that you've installed the agent, you can apply more granular permissions to the gMSA. For information and step-by-step instructions on how to configure the permissions, see [Azure AD Connect cloud provisioning agent gMSA PowerShell cmdlets](how-to-gmsa-cmdlets.md).

+## Installing against US government cloud

+By default, the Azure Active Directory (Azure AD) Connect provisioning agent installs against the default Azure cloud environment. If you are installing the agent for use in the US government cloud do the following:

+- In step #8, add **ENVIRONMENTNAME=AzureUSGovernment** to the command line like the example.

+ ```

+ $installerProcess = Start-Process -FilePath "c:\temp\AADConnectProvisioningAgent.Installer.exe" -ArgumentList "/quiet ENVIRONMENTNAME=AzureUSGovernment" -NoNewWindow -PassThru

+ $installerProcess.WaitForExit()

+ ```

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [Azure AD Connect cloud provisioning agent gMSA PowerShell cmdlets](how-to-gmsa-cmdlets.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Install the Azure AD Connect provisioning agent'

+description: Learn how to install the Azure AD Connect provisioning agent and how to configure it in the Azure portal.

+# Install the Azure AD Connect provisioning agent

+This article walks you through the installation process for the Azure Active Directory (Azure AD) Connect provisioning agent and how to initially configure it in the Azure portal.

+> [!IMPORTANT]

+> The following installation instructions assume that you've met all the [prerequisites](how-to-prerequisites.md).

+>[!NOTE]

+>This article deals with installing the provisioning agent by using the wizard. For information about installing the Azure AD Connect provisioning agent by using a CLI, see [Install the Azure AD Connect provisioning agent by using a CLI and PowerShell](how-to-install-pshell.md).

+For more information and an example, view the following video:

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWK5mR]

+## Group Managed Service Accounts

+A group Managed Service Account (gMSA) is a managed domain account that provides automatic password management, simplified service principal name (SPN) management, and the ability to delegate the management to other administrators. A gMSA also extends this functionality over multiple servers. Azure AD Connect cloud sync supports and recommends the use of a gMSA for running the agent. For more information, see [Group Managed Service Accounts](how-to-prerequisites.md#group-managed-service-accounts).

+### Update an existing agent to use the gMSA

+To update an existing agent to use the Group Managed Service Account created during installation, upgrade the agent service to the latest version by running *AADConnectProvisioningAgent.msi*. Now run through the installation wizard again and provide the credentials to create the account when you're prompted to do so.

+## Install the agent

+## Verify the agent installation

+>[!IMPORTANT]

+> After you've installed the agent, you must configure and enable it before it will start synchronizing users. To configure a new agent, see [Create a new configuration for Azure AD Connect cloud sync](how-to-configure.md).

+## Enable password writeback in Azure AD Connect cloud sync

+To use *password writeback* and enable the self-service password reset (SSPR) service to detect the cloud sync agent, use the `Set-AADCloudSyncPasswordWritebackConfiguration` cmdlet and the tenantΓÇÖs global administrator credentials:

+ ```

+ Import-Module "C:\\Program Files\\Microsoft Azure AD Connect Provisioning Agent\\Microsoft.CloudSync.Powershell.dll"

+ Set-AADCloudSyncPasswordWritebackConfiguration -Enable $true -Credential $(Get-Credential)

+ ```

+For more information about using password writeback with Azure AD Connect cloud sync, see [Tutorial: Enable cloud sync self-service password reset writeback to an on-premises environment (preview)](../../../active-directory/authentication/tutorial-enable-cloud-sync-sspr-writeback.md).

+## Install an agent in the US government cloud

+By default, the Azure AD Connect provisioning agent is installed in the default Azure environment. If you're installing the agent for US government use, make this change in step 7 of the preceding installation procedure:

+- Instead of selecting **Open file**, select **Start** > **Run**, and then go to the *AADConnectProvisioningAgentSetup.exe* file. In the **Run** box, after the executable, enter **ENVIRONMENTNAME=AzureUSGovernment**, and then select **OK**.

+ [](media/how-to-install/new-install-12.png#lightbox)

+## Password hash synchronization and FIPS with cloud sync

+If your server has been locked down according to the Federal Information Processing Standard (FIPS), MD5 (message-digest algorithm 5) is disabled.

+To enable MD5 for password hash synchronization, do the following:

+1. Go to %programfiles%\Microsoft Azure AD Connect Provisioning Agent.

+1. Open *AADConnectProvisioningAgent.exe.config*.

+1. Go to the configuration/runtime node at the top of the file.

+1. Add the `<enforceFIPSPolicy enabled="false"/>` node.

+1. Save your changes.

+For reference, your code should look like the following snippet:

+```xml

+<configuration>

+ <runtime>

+ <enforceFIPSPolicy enabled="false"/>

+ </runtime>

+</configuration>

+```

+For information about security and FIPS, see [Azure AD password hash sync, encryption, and FIPS compliance](https://techcommunity.microsoft.com/t5/microsoft-entra-azure-ad-blog/aad-password-sync-encryption-and-fips-compliance/ba-p/243709).

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+- [Create a new configuration for Azure AD Connect cloud sync](how-to-configure.md).

+ Title: 'Azure AD Connect cloud provisioning agent: Manage registry options'

+description: This article describes how to manage registry options in the Azure AD Connect cloud provisioning agent.

+documentationcenter: ''

+editor: ''

+ na

+# Manage agent registry options

+This section describes registry options that you can set to control the runtime processing behavior of the Azure AD Connect provisioning agent.

+## Configure LDAP connection timeout

+When performing LDAP operations on configured Active Directory domain controllers, by default, the provisioning agent uses the default connection timeout value of 30 seconds. If your domain controller takes more time to respond, then you may see the following error message in the agent log file:

+`

+System.DirectoryServices.Protocols.LdapException: The operation was aborted because the client side timeout limit was exceeded.

+`

+LDAP search operations can take longer if the search attribute is not indexed. As a first step, if you get the above error, first check if the search/lookup attribute is [indexed](/windows/win32/ad/indexed-attributes). If the search attributes are indexed and the error persists, you can increase the LDAP connection timeout using the following steps:

+1. Log on as Administrator on the Windows server running the Azure AD Connect Provisioning Agent.

+1. Use the *Run* menu item to open the registry editor (regedit.exe)

+1. Locate the key folder **HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Azure AD Connect Agents\Azure AD Connect Provisioning Agent**

+1. Right-click and select "New -> String Value"

+1. Provide the name:

+ `LdapConnectionTimeoutInMilliseconds`

+1. Double-click on the **Value Name** and enter the value data as `60000` milliseconds.

+ > [!div class="mx-imgBorder"]

+ > 

+1. Restart the Azure AD Connect Provisioning Service from the *Services* console.

+1. If you have deployed multiple provisioning agents, apply this registry change to all agents for consistency.

+## Configure referral chasing

+By default, the Azure AD Connect provisioning agent does not chase [referrals](/windows/win32/ad/referrals).

+You may want to enable referral chasing, to support certain HR inbound provisioning scenarios such as:

+* Checking uniqueness of UPN across multiple domains

+* Resolving cross-domain manager references

+Use the following steps to turn on referral chasing:

+1. Log on as Administrator on the Windows server running the Azure AD Connect Provisioning Agent.

+1. Use the *Run* menu item to open the registry editor (regedit.exe)

+1. Locate the key folder **HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Azure AD Connect Agents\Azure AD Connect Provisioning Agent**

+1. Right-click and select "New -> String Value"

+1. Provide the name:

+ `ReferralChasingOptions`

+1. Double-click on the **Value Name** and enter the value data as `96`. This value corresponds to the constant value for `ReferralChasingOptions.All` and specifies that both subtree and base-level referrals will be followed by the agent.

+ > [!div class="mx-imgBorder"]

+ > 

+1. Restart the Azure AD Connect Provisioning Service from the *Services* console.

+1. If you have deployed multiple provisioning agents, apply this registry change to all agents for consistency.

+> [!NOTE]

+> You can confirm the registry options have been set by enabling [verbose logging](how-to-troubleshoot.md#log-files). The logs emitted during agent startup will display the config values picked from the registry.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Use map UserType with Azure AD Connect cloud sync'

+description: This article describes how to map the UserType attribute with cloud sync.

+# Map UserType with cloud sync

+Cloud sync supports synchronization of the **UserType** attribute for User objects.

+By default, the **UserType** attribute isn't enabled for synchronization because there's no corresponding **UserType** attribute in on-premises Active Directory. You must manually add this mapping for synchronization. Before you do this step, you must take note of the following behavior enforced by Azure Active Directory (Azure AD):

+- Azure AD only accepts two values for the **UserType** attribute: Member and Guest.

+- If the **UserType** attribute isn't mapped in cloud sync, Azure AD users created through directory synchronization would have the **UserType** attribute set to Member.

+Before you add a mapping for the **UserType** attribute, you must first decide how the attribute is derived from on-premises Active Directory. The following approaches are the most common:

+ - Designate an unused on-premises Active Directory attribute, such as extensionAttribute1, to be used as the source attribute. The designated on-premises Active Directory attribute should be of the type string, be single-valued, and contain the value Member or Guest.

+ - If you choose this approach, you must ensure that the designated attribute is populated with the correct value for all existing user objects in on-premises Active Directory that are synchronized to Azure AD before you enable synchronization of the **UserType** attribute.

+## Add the UserType mapping

+To add the **UserType** mapping:

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 1. Select **Azure AD Connect**.

+ 1. Select **Manage cloud sync**.

+ 1. Under **Configuration**, select your configuration.

+ 1. Under **Manage attributes**, select **Click to edit mappings**.

+

+ 

+ 1. Select **Add attribute mapping**.

+

+ 

+1. Select the mapping type. You can do the mapping in one of three ways:

+ - A direct mapping, for example, from an Active Directory attribute

+ - An expression, such as IIF(InStr([userPrincipalName], "@partners") > 0,"Guest","Member")

+ - A constant, for example, make all user objects as Guest

+

+ 

+1. In the **Target attribute** dropdown box, select **UserType**.

+1. Select **Apply** at the bottom of the page to create a mapping for the Azure AD **UserType** attribute.

+## Next steps

+- [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md)

+- [Cloud sync configuration](how-to-configure.md)

+ Title: 'On-demand provisioning in Azure AD Connect cloud sync'

+description: This article describes how to use the cloud sync feature of Azure AD Connect to test configuration changes.

+# On-demand provisioning in Azure AD Connect cloud sync

+You can use the cloud sync feature of Azure Active Directory (Azure AD) Connect to test configuration changes by applying these changes to a single user. This on-demand provisioning helps you validate and verify that the changes made to the configuration were applied properly and are being correctly synchronized to Azure AD.

+> [!IMPORTANT]

+> When you use on-demand provisioning, the scoping filters are not applied to the user that you selected. You can use on-demand provisioning on users who are outside the organization units that you specified.

+For additional information and an example see the following video.

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWK5mW]

+## Validate a user

+To use on-demand provisioning, follow these steps:

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-1.png" alt-text="Screenshot of new UX screen." lightbox="media/how-to-on-demand-provision/new-ux-1.png":::

+ 4. Under **Configuration**, select your configuration.

+ 5. On the left, select **Provision on demand**.

+ 6. Enter the distinguished name of a user and select the **Provision** button.

+

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-2.png" alt-text="Screenshot of user distinguished name." lightbox="media/how-to-on-demand-provision/new-ux-2.png":::

+ 7. After provisioning finishes, a success screen appears with four green check marks. Any errors appear to the left.

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-3.png" alt-text="Screenshot of on-demand success." lightbox="media/how-to-on-demand-provision/new-ux-3.png":::

+## Get details about provisioning

+Now you can look at the user information and determine if the changes that you made in the configuration have been applied. The rest of this article describes the individual sections that appear in the details of a successfully synchronized user.

+### Import user

+The **Import user** section provides information on the user who was imported from Active Directory. This is what the user looks like before provisioning into Azure AD. Select the **View details** link to display this information.

+By using this information, you can see the various attributes (and their values) that were imported. If you created a custom attribute mapping, you can see the value here.

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-4.png" alt-text="Screenshot of import user." lightbox="media/how-to-on-demand-provision/new-ux-4.png":::

+### Determine if user is in scope

+The **Determine if user is in scope** section provides information on whether the user who was imported to Azure AD is in scope. Select the **View details** link to display this information.

+By using this information, you can see if the user is in scope.

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-5.png" alt-text="Screenshot of scope determination." lightbox="media/how-to-on-demand-provision/new-ux-5.png":::

+### Match user between source and target system

+The **Match user between source and target system** section provides information on whether the user already exists in Azure AD and whether a join should occur instead of provisioning a new user. Select the **View details** link to display this information.

+By using this information, you can see whether a match was found or if a new user is going to be created.

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-6.png" alt-text="Screenshot of matching user." lightbox="media/how-to-on-demand-provision/new-ux-6.png":::

+The matching details show a message with one of the three following operations:

+- **Create**: A user is created in Azure AD.

+- **Update**: A user is updated based on a change made in the configuration.

+- **Delete**: A user is removed from Azure AD.

+Depending on the type of operation that you've performed, the message will vary.

+### Perform action

+The **Perform action** section provides information on the user who was provisioned or exported into Azure AD after the configuration was applied. This is what the user looks like after provisioning into Azure AD. Select the **View details** link to display this information.

+By using this information, you can see the values of the attributes after the configuration was applied. Do they look similar to what was imported, or are they different? Was the configuration applied successfully?

+This process enables you to trace the attribute transformation as it moves through the cloud and into your Azure AD tenant.

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-7.png" alt-text="Screenshot of perform action." lightbox="media/how-to-on-demand-provision/new-ux-7.png":::

+## Next steps

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+- [Install Azure AD Connect cloud sync](how-to-install.md)

+

+ Title: 'Prerequisites for Azure AD Connect cloud sync in Azure AD'

+description: This article describes the prerequisites and hardware requirements you need for cloud sync.

+# Prerequisites for Azure AD Connect cloud sync

+This article provides guidance on how to choose and use Azure Active Directory (Azure AD) Connect cloud sync as your identity solution.

+## Cloud provisioning agent requirements

+You need the following to use Azure AD Connect cloud sync:

+- Domain Administrator or Enterprise Administrator credentials to create the Azure AD Connect Cloud Sync gMSA (group Managed Service Account) to run the agent service.

+- A hybrid identity administrator account for your Azure AD tenant that is not a guest user.

+- An on-premises server for the provisioning agent with Windows 2016 or later. This server should be a tier 0 server based on the [Active Directory administrative tier model](/windows-server/identity/securing-privileged-access/securing-privileged-access-reference-material). Installing the agent on a domain controller is supported.

+- High availability refers to the Azure AD Connect cloud sync's ability to operate continuously without failure for a long time. By having multiple active agents installed and running, Azure AD Connect cloud sync can continue to function even if one agent should fail. Microsoft recommends having 3 active agents installed for high availability.

+- On-premises firewall configurations.

+## Group Managed Service Accounts

+A group Managed Service Account is a managed domain account that provides automatic password management, simplified service principal name (SPN) management, the ability to delegate the management to other administrators, and also extends this functionality over multiple servers. Azure AD Connect Cloud Sync supports and uses a gMSA for running the agent. You will be prompted for administrative credentials during setup, in order to create this account. The account will appear as (domain\provAgentgMSA$). For more information on a gMSA, see [group Managed Service Accounts](/windows-server/security/group-managed-service-accounts/group-managed-service-accounts-overview)

+### Prerequisites for gMSA:

+1. The Active Directory schema in the gMSA domain's forest needs to be updated to Windows Server 2012 or later.

+2. [PowerShell RSAT modules](/windows-server/remote/remote-server-administration-tools) on a domain controller

+3. At least one domain controller in the domain must be running Windows Server 2012 or later.

+4. A domain joined server where the agent is being installed needs to be either Windows Server 2016 or later.

+### Custom gMSA account

+If you are creating a custom gMSA account, you need to ensure that the account has the following permissions.

+|Type |Name |Access |Applies To|

+|--|--|--|--|

+|Allow |gMSA Account |Read all properties |Descendant device objects|

+|Allow |gMSA Account|Read all properties |Descendant InetOrgPerson objects|

+|Allow |gMSA Account |Read all properties |Descendant Computer objects|

+|Allow |gMSA Account |Read all properties |Descendant foreignSecurityPrincipal objects|

+|Allow |gMSA Account |Full control |Descendant Group objects|

+|Allow |gMSA Account |Read all properties |Descendant User objects|

+|Allow |gMSA Account |Read all properties |Descendant Contact objects|

+|Allow |gMSA Account |Create/delete User objects|This object and all descendant objects|

+For steps on how to upgrade an existing agent to use a gMSA account see [group Managed Service Accounts](how-to-install.md#group-managed-service-accounts).

+For more information on how to prepare your Active Directory for group Managed Service Account, see [group Managed Service Accounts Overview](/windows-server/security/group-managed-service-accounts/group-managed-service-accounts-overview).

+### In the Azure portal

+1. Create a cloud-only hybrid identity administrator account on your Azure AD tenant. This way, you can manage the configuration of your tenant if your on-premises services fail or become unavailable. Learn about how to [add a cloud-only hybrid identity administrator account](../../fundamentals/add-users-azure-active-directory.md). Finishing this step is critical to ensure that you don't get locked out of your tenant.

+1. Add one or more [custom domain names](../../fundamentals/add-custom-domain.md) to your Azure AD tenant. Your users can sign in with one of these domain names.

+### In your directory in Active Directory

+Run the [IdFix tool](/office365/enterprise/prepare-directory-attributes-for-synch-with-idfix) to prepare the directory attributes for synchronization.

+### In your on-premises environment

+1. Identify a domain-joined host server running Windows Server 2016 or greater with a minimum of 4-GB RAM and .NET 4.7.1+ runtime.

+2. The PowerShell execution policy on the local server must be set to Undefined or RemoteSigned.

+3. If there's a firewall between your servers and Azure AD, see [Firewall and proxy requirements](#firewall-and-proxy-requirements) below.

+>[!NOTE]

+> Installing the cloud provisioning agent on Windows Server Core is not supported.

+### Additional requirements

+- [Microsoft .NET Framework 4.7.1](https://dotnet.microsoft.com/download/dotnet-framework/net471)

+#### TLS requirements

+> [!NOTE]

+> Transport Layer Security (TLS) is a protocol that provides for secure communications. Changing the TLS settings affects the entire forest. For more information, see [Update to enable TLS 1.1 and TLS 1.2 as default secure protocols in WinHTTP in Windows](https://support.microsoft.com/help/3140245/update-to-enable-tls-1-1-and-tls-1-2-as-default-secure-protocols-in-wi).

+The Windows server that hosts the Azure AD Connect cloud provisioning agent must have TLS 1.2 enabled before you install it.

+To enable TLS 1.2, follow these steps.

+1. Set the following registry keys:

+ ```

+ [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2]

+ [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] "DisabledByDefault"=dword:00000000 "Enabled"=dword:00000001

+ [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "DisabledByDefault"=dword:00000000 "Enabled"=dword:00000001

+ [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319] "SchUseStrongCrypto"=dword:00000001

+ ```

+1. Restart the server.

+## Firewall and Proxy requirements

+If there's a firewall between your servers and Azure AD, configure the following items:

+- Ensure that agents can make *outbound* requests to Azure AD over the following ports:

+ | Port number | How it's used |

+ | | |

+ | **80** | Downloads the certificate revocation lists (CRLs) while validating the TLS/SSL certificate. |

+ | **443** | Handles all outbound communication with the service. |

+ | **8080** (optional) | Agents report their status every 10 minutes over port 8080, if port 443 is unavailable. This status is displayed in the Azure portal. |

+

+- If your firewall enforces rules according to the originating users, open these ports for traffic from Windows services that run as a network service.

+- If your firewall or proxy allows you to specify safe suffixes, add connections:

+#### [Public Cloud](#tab/public-cloud)

+ |URL |How it's used|

+ |--|--|

+ |&#42;.msappproxy.net</br>&#42;.servicebus.windows.net|The agent uses these URLs to communicate with the Azure AD cloud service. |

+ |&#42;.microsoftonline.com</br>&#42;.microsoft.com</br>&#42;.msappproxy.com</br>&#42;.windowsazure.com|The agent uses these URLs to communicate with the Azure AD cloud service. |

+ |`mscrl.microsoft.com:80` </br>`crl.microsoft.com:80` </br>`ocsp.msocsp.com:80` </br>`www.microsoft.com:80`| The agent uses these URLs to verify certificates.|

+ |login.windows.net</br>|The agent uses these URLs during the registration process.

+#### [U.S. Government Cloud](#tab/us-government-cloud)

+ |URL |How it's used|

+ |--|--|

+ |&#42;.msappproxy.us</br>&#42;.servicebus.usgovcloudapi.net|The agent uses these URLs to communicate with the Azure AD cloud service. |

+ |`mscrl.microsoft.us:80` </br>`crl.microsoft.us:80` </br>`ocsp.msocsp.us:80` </br>`www.microsoft.us:80`| The agent uses these URLs to verify certificates.|

+ |login.windows.us </br>secure.aadcdn.microsoftonline-p.com </br>&#42;.microsoftonline.us </br>&#42;.microsoftonline-p.us </br>&#42;.msauth.net </br>&#42;.msauthimages.net </br>&#42;.msecnd.net</br>&#42;.msftauth.net </br>&#42;.msftauthimages.net</br>&#42;.phonefactor.net </br>enterpriseregistration.windows.net</br>management.azure.com </br>policykeyservice.dc.ad.msft.net</br>ctldl.windowsupdate.us:80 </br>aadcdn.msftauthimages.us </br>*.microsoft.us </br>msauthimages.us </br>mfstauthimages.us| The agent uses these URLs during the registration process.

+- If you are unable to add connections, allow access to the [Azure datacenter IP ranges](https://www.microsoft.com/download/details.aspx?id=41653), which are updated weekly.

+## NTLM requirement

+You should not enable NTLM on the Windows Server that is running the Azure AD Connect Provisioning Agent and if it is enabled you should make sure you disable it.

+## Known limitations

+The following are known limitations:

+### Delta Synchronization

+- Group scope filtering for delta sync does not support more than 50,000 members.

+- When you delete a group that's used as part of a group scoping filter, users who are members of the group, don't get deleted.

+- When you rename the OU or group that's in scope, delta sync will not remove the users.

+### Provisioning Logs

+- Provisioning logs do not clearly differentiate between create and update operations. You may see a create operation for an update and an update operation for a create.

+### Group re-naming or OU re-naming

+- If you rename a group or OU in AD that's in scope for a given configuration, the cloud sync job will not be able to recognize the name change in AD. The job won't go into quarantine and will remain healthy.

+### Scoping filter

+When using OU scoping filter

+- You can only sync up to 59 separate OUs or Security Groups for a given configuration.

+- Nested OUs are supported (that is, you **can** sync an OU that has 130 nested OUs, but you **cannot** sync 60 separate OUs in the same configuration).

+### Password Hash Sync

+- Using password hash sync with InetOrgPerson is not supported.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'How to use single sign-on with cloud sync'

+description: This article describes how to install and use single sign-on with cloud sync.

+# Using single sign-on with cloud sync

+The following document describes how to use single sign-on with cloud sync.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Azure AD Connect cloud sync transformations

+description: This article describes how to use transformations to alter the default attribute mappings.

+ms.technology: identity-adfs

+# Transformations

+With a transformation, you can change the default behavior of how an attribute is synchronized with Azure Active Directory (Azure AD) by using cloud sync.

+To do this task, you need to edit the schema and then resubmit it via a web request.

+For more information on cloud sync attributes, see [Understanding the Azure AD schema](concept-attributes.md).

+## Retrieve the schema

+To retrieve the schema, follow the steps in [View the schema](concept-attributes.md#view-the-schema).

+## Custom attribute mapping

+To add a custom attribute mapping, follow these steps.

+1. Copy the schema into a text or code editor such as [Visual Studio Code](https://code.visualstudio.com/).

+1. Locate the object that you want to update in the schema.

+ </br>

+1. Locate the code for `ExtensionAttribute3` under the user object.

+ ```

+ {

+ "defaultValue": null,

+ "exportMissingReferences": false,

+ "flowBehavior": "FlowWhenChanged",

+ "flowType": "Always",

+ "matchingPriority": 0,

+ "targetAttributeName": "ExtensionAttribute3",

+ "source": {

+ "expression": "Trim([extensionAttribute3])",

+ "name": "Trim",

+ "type": "Function",

+ "parameters": [

+ {

+ "key": "source",

+ "value": {

+ "expression": "[extensionAttribute3]",

+ "name": "extensionAttribute3",

+ "type": "Attribute",

+ "parameters": []

+ }

+ }

+ ]

+ }

+ },

+ ```

+1. Edit the code so that the company attribute is mapped to `ExtensionAttribute3`.

+ ```

+ {

+ "defaultValue": null,

+ "exportMissingReferences": false,

+ "flowBehavior": "FlowWhenChanged",

+ "flowType": "Always",

+ "matchingPriority": 0,

+ "targetAttributeName": "ExtensionAttribute3",

+ "source": {

+ "expression": "Trim([company])",

+ "name": "Trim",

+ "type": "Function",

+ "parameters": [

+ {

+ "key": "source",

+ "value": {

+ "expression": "[company]",

+ "name": "company",

+ "type": "Attribute",

+ "parameters": []

+ }

+ }

+ ]

+ }

+ },

+ ```

+ 1. Copy the schema back into Graph Explorer, change the **Request Type** to **PUT**, and select **Run Query**.

+ 

+ 1. Now, in the Azure portal, go to the cloud sync configuration and select **Restart provisioning**.

+ 

+ 1. After a little while, verify the attributes are being populated by running the following query in Graph Explorer: `https://graph.microsoft.com/beta/users/{Azure AD user UPN}`.

+ 1. You should now see the value.

+ 

+## Custom attribute mapping with function

+For more advanced mapping, you can use functions that allow you to manipulate the data and create values for attributes to suit your organization's needs.

+To do this task, follow the previous steps and then edit the function that's used to construct the final value.

+For information on the syntax and examples of expressions, see [Writing expressions for attribute mappings in Azure Active Directory](reference-expressions.md).

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Azure AD Connect cloud sync troubleshooting

+description: This article describes how to troubleshoot problems that might arise with the cloud provisioning agent.

+ms.technology: identity-adfs

+# Cloud sync troubleshooting

+Cloud sync has many different dependencies and interactions, which can give rise to various problems. This article helps you troubleshoot these problems. It introduces the typical areas for you to focus on, how to gather additional information, and the various techniques you can use to track down problems.

+## Agent problems

+When you troubleshoot agent problems, you verify that the agent was installed correctly, and that it communicates with Azure Active Directory (Azure AD). In particular, some of the first things that you want to verify with the agent are:

+- Is it installed?

+- Is the agent running locally?

+- Is the agent in the portal?

+- Is the agent marked as healthy?

+You can verify these items in the Azure portal and on the local server that's running the agent.

+### Azure portal agent verification

+To verify that Azure detects the agent, and that the agent is healthy, follow these steps:

+1. Sign in to the Azure portal.

+1. On the left, select **Azure Active Directory** > **Azure AD Connect**. In the center, select **Manage sync**.

+1. On the **Azure AD Connect cloud sync** screen, select **Review all agents**.

+ 

+1. On the **On-premises provisioning agents** screen, you see the agents you've installed. Verify that the agent in question is there. If all is well, you will see the *active* (green) status for the agent.

+ 

+### Verify the required open ports

+Verify that the Azure AD Connect provisioning agent is able to communicate successfully with Azure datacenters. If there's a firewall in the path, make sure that the following ports to outbound traffic are open:

+| Port number | How it's used |

+| -- | |

+| 80 | Downloading certificate revocation lists (CRLs), while validating the TLS/SSL certificate. |

+| 443 | Handling all outbound communication with the Application Proxy service. |

+If your firewall enforces traffic according to originating users, also open ports 80 and 443 for traffic from Windows services that run as a network service.

+### Allow access to URLs

+Allow access to the following URLs:

+| URL | Port | How it's used |

+| | | |

+| `*.msappproxy.net` <br> `*.servicebus.windows.net` | 443/HTTPS | Communication between the connector and the Application Proxy cloud service. |

+| `crl3.digicert.com` <br> `crl4.digicert.com` <br> `ocsp.digicert.com` <br> `crl.microsoft.com` <br> `oneocsp.microsoft.com` <br> `ocsp.msocsp.com`<br> | 80/HTTP | The connector uses these URLs to verify certificates. |

+| `login.windows.net` <br> `secure.aadcdn.microsoftonline-p.com` <br> `*.microsoftonline.com` <br> `*.microsoftonline-p.com` <br> `*.msauth.net` <br> `*.msauthimages.net` <br> `*.msecnd.net` <br> `*.msftauth.net` <br> `*.msftauthimages.net` <br> `*.phonefactor.net` <br> `enterpriseregistration.windows.net` <br> `management.azure.com` <br> `policykeyservice.dc.ad.msft.net` <br> `ctldl.windowsupdate.com` <br> `www.microsoft.com/pkiops` | 443/HTTPS | The connector uses these URLs during the registration process. |

+| `ctldl.windowsupdate.com` | 80/HTTP | The connector uses this URL during the registration process. |

+You can allow connections to `*.msappproxy.net`, `*.servicebus.windows.net`, and other of the preceding URLs, if your firewall or proxy lets you configure access rules based on domain suffixes. If not, you need to allow access to the [Azure IP ranges and service tags - public cloud](https://www.microsoft.com/download/details.aspx?id=56519). The IP ranges are updated each week.

+> [!IMPORTANT]

+> Avoid all forms of inline inspection and termination on outbound TLS communications between Azure AD Application Proxy connectors and Azure AD Application Proxy cloud services.

+### DNS name resolution for Azure AD Application Proxy endpoints

+Public DNS records for Azure AD Application Proxy endpoints are chained CNAME records, pointing to an A record. This ensures fault tolerance and flexibility. ItΓÇÖs guaranteed that the Azure AD Application Proxy connector always accesses host names with the domain suffixes `*.msappproxy.net` or `*.servicebus.windows.net`.

+However, during the name resolution, the CNAME records might contain DNS records with different host names and suffixes. Due to this, you must ensure that the device can resolve all the records in the chain, and allows connection to the resolved IP addresses. Because the DNS records in the chain might be changed from time to time, we can't provide you with any list DNS records.

+### On the local server

+To verify that the agent is running, follow these steps:

+1. On the server with the agent installed, open **Services**. Do this by going to **Start** > **Run** > **Services.msc**.

+1. Under **Services**, make sure **Microsoft Azure AD Connect Agent Updater** and **Microsoft Azure AD Connect Provisioning Agent** are there. Also confirm that their status is *Running*.

+ 

+### Common agent installation problems

+The following sections describe some common agent installation problems, and typical resolutions of those problems.

+#### Agent failed to start

+You might receive an error message that states:

+*Service 'Microsoft Azure AD Connect Provisioning Agent' failed to start. Verify that you have sufficient privileges to start the system services.*

+This problem is typically caused by a group policy. The policy prevented permissions from being applied to the local NT Service sign-in account created by the installer (`NT SERVICE\AADConnectProvisioningAgent`). These permissions are required to start the service.

+To resolve this problem, follow these steps:

+1. Sign in to the server with an administrator account.

+1. Open **Services** by going to **Start** > **Run** > **Services.msc**.

+1. Under **Services**, double-click **Microsoft Azure AD Connect Provisioning Agent**.

+1. On the **Log On** tab, change **This account** to a domain admin. Then restart the service.

+ 

+#### Agent times out or certificate isn't valid

+You might get the following error message when you attempt to register the agent.

+

+This problem is usually caused by the agent being unable to connect to the hybrid identity service. To resolve this problem, configure an outbound proxy.

+The provisioning agent supports the use of an outbound proxy. You can configure it by editing the following agent .config file: *C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\AADConnectProvisioningAgent.exe.config*.

+Add the following lines into it, toward the end of the file, just before the closing `</configuration>` tag. Replace the variables `[proxy-server]` and `[proxy-port]` with your proxy server name and port values.

+```xml

+ <system.net>

+ <defaultProxy enabled="true" useDefaultCredentials="true">

+ <proxy

+ usesystemdefault="true"

+ proxyaddress="http://[proxy-server]:[proxy-port]"

+ bypassonlocal="true"

+ />

+ </defaultProxy>

+ </system.net>

+```

+#### Agent registration fails with security error

+You might get an error message when you install the cloud provisioning agent. This problem is typically caused by the agent being unable to run the PowerShell registration scripts, due to local PowerShell execution policies.

+To resolve this problem, change the PowerShell execution policies on the server. You need to have machine and user policies set as `Undefined` or `RemoteSigned`. If they're set as `Unrestricted`, you'll see this error. For more information, see [PowerShell execution policies](/powershell/module/microsoft.powershell.core/about/about_execution_policies).

+### Log files

+By default, the agent emits minimal error messages and stack trace information. You can find these trace logs in the following folder: *C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace*.

+To gather additional details for troubleshooting agent-related problems, follow these steps.

+1. [Install the AADCloudSyncTools PowerShell module](reference-powershell.md#install-the-aadcloudsynctools-powershell-module).

+1. Use the `Export-AADCloudSyncToolsLogs` PowerShell cmdlet to capture the information. You can use the following options to fine-tune your data collection.

+ - `SkipVerboseTrace` to only export current logs without capturing verbose logs (default = false).

+ - `TracingDurationMins` to specify a different capture duration (default = 3 minutes).

+ - `OutputPath` to specify a different output path (default = userΓÇÖs Documents folder).

+## Object synchronization problems

+In the Azure portal, you can use provisioning logs to help track down and troubleshoot object synchronization problems. To view the logs, select **Logs**.

+

+Provisioning logs provide a wealth of information on the state of the objects being synchronized between your on-premises Active Directory environment and Azure.

+

+You can filter the view to focus on specific problems, such as dates. Double-click an individual event to see additional information.

+

+This information provides detailed steps and where the synchronization problem is occurring. In this way, you can pinpoint the exact spot of the problem.

+## Provisioning quarantined problems

+Cloud sync monitors the health of your configuration, and places unhealthy objects in a quarantine state. If most or all of the calls made against the target system consistently fail because of an error (for example, invalid admin credentials), the sync job is marked as in quarantine.

+

+By selecting the status, you can see additional information about the quarantine. You can also obtain the error code and message.

+

+Right-clicking on the status will bring up additional options to:

+- View the provisioning logs.

+- View the agents.

+- Clear the quarantine.

+

+### Resolve a quarantine

+There are two different ways to resolve a quarantine. You can clear the quarantine, or you can restart the provisioning job.

+#### Clear the quarantine

+To clear the watermark and run a delta sync on the provisioning job after you have verified it, simply right-click on the status and select **Clear quarantine**.

+You should see a notice that the quarantine is clearing.

+

+Then you should see the status on your agent as healthy.

+

+#### Restart the provisioning job

+Use the Azure portal to restart the provisioning job. On the agent configuration page, select **Restart sync**.

+ 

+Alternatively, you can use Microsoft Graph to [restart the provisioning job](/graph/api/synchronization-synchronizationjob-restart?tabs=http&view=graph-rest-beta&preserve-view=true). You have full control over what you restart. You can choose to clear:

+- Escrows, to restart the escrow counter that accrues toward quarantine status.

+- Quarantine, to remove the application from quarantine.

+- Watermarks.

+

+Use the following request:

+

+ `POST /servicePrincipals/{id}/synchronization/jobs/{jobId}/restart`

+## Repair the cloud sync service account

+If you need to repair the cloud sync service account, you can use the `Repair-AADCloudSyncToolsAccount` command.

+ 1. [Install the AADCloudSyncTools PowerShell module](reference-powershell.md#install-the-aadcloudsynctools-powershell-module).

+ 1. From a PowerShell session with administrative privileges, type, or copy and paste, the following:

+ ```powershell

+ Connect-AADCloudSyncTools

+ ```

+ 1. Enter your Azure AD Global Administrator credentials.

+ 1. Type, or copy and paste, the following:

+ ```powershell

+ Repair-AADCloudSyncToolsAccount

+ ```

+ 1. After this completes, it should say that the account was repaired successfully.

+## Password writeback

+To enable and use password writeback with cloud sync, keep the following in mind:

+- If you need to update the [gMSA permissions](how-to-gmsa-cmdlets.md#using-set-aadcloudsyncpermissions), it might take an hour or more for these permissions to replicate to all the objects in your directory. If you don't assign these permissions, writeback can appear to be configured correctly, but users might encounter errors when they update their on-premises passwords from the cloud. Permissions must be applied to **This object and all descendant objects** for **Unexpire Password** to appear.

+- If passwords for some user accounts aren't written back to the on-premises directory, make sure that inheritance isn't disabled for the account in the on-premises Active Directory Domain Services (AD DS) environment. Write permissions for passwords must be applied to descendant objects for the feature to work correctly.

+- Password policies in the on-premises AD DS environment might prevent password resets from being correctly processed. If you're testing this feature and want to reset passwords for users more than once per day, the group policy for the minimum password age must be set to 0. You can find this setting in the following location: **Computer Configuration** > **Policies** > **Windows Settings** > **Security Settings** > **Account Policies**, within **gpmc.msc**.

+ - If you update the group policy, wait for the updated policy to replicate, or use the `gpupdate /force` command.

+ - For passwords to be changed immediately, the minimum password age must be set to 0. However, if users adhere to the on-premises policies, and the minimum password age is set to a value greater than 0, password writeback doesn't work after the on-premises policies are evaluated.

+## Next steps

+- [Known limitations](how-to-prerequisites.md#known-limitations)

+- [Error codes](reference-error-codes.md)

+ Title: 'Migrate Azure AD Connect to Azure AD Connect cloud sync| Microsoft Docs'

+description: Describes steps to migrate Azure AD Connect to Azure AD Connect cloud sync.

+# Migrating from Azure AD Connect to Azure AD Connect cloud sync

+Azure AD Connect cloud sync is the future for accomplishing your hybrid identity goals for synchronization of users, groups, and contacts to Azure AD. It uses the Azure AD cloud provisioning agent instead of the Azure AD Connect application. If you're currently using Azure AD Connect and wish to move to cloud sync, the following document provides guidance.

+## Steps for migrating from Azure AD Connect to cloud sync

+|Step|Description|

+|--|--|

+|Choose the best sync tool|Before moving to cloud sync, you should verify that cloud sync is currently the best synchronization tool for you. You can do this task by going through the wizard [here](https://setup.microsoft.com/azure/add-or-sync-users-to-microsoft-365).|

+|Verify the pre-requisites for migrating|The following guidance is only for users who have installed Azure AD Connect using the Express settings and aren't synchronizing devices. Also you should verify the cloud sync [pre-requisites](how-to-prerequisites.md).|

+|Back up your Azure AD Connect configuration|Before making any changes, you should back up your Azure AD Connect configuration. This way, you can role-back. For more information, see [Import and export Azure AD Connect configuration settings](../connect/how-to-connect-import-export-config.md).|

+|Review the migration tutorial|To become familiar with the migration process, review the [Migrate to Azure AD Connect cloud sync for an existing synced AD forest](tutorial-pilot-aadc-aadccp.md) tutorial. This tutorial guides you through the migration process in a sandbox environment.|

+|Create or identify an OU for the migration|Create a new OU or identify an existing OU that contains the users you'll test migration on.|

+|Move users into new OU (optional)|If you're using a new OU, move the users that are in scope for this pilot into that OU now. Before continuing, let Azure AD Connect pick up the changes so that it's synchronizing them in the new OU.|

+|Run PowerShell on OU|You can run the following PowerShell cmdlet to get the counts of the users that are in the pilot OU. </br>`Get-ADUser -Filter * -SearchBase "<DN path of OU>"`</br> Example: `Get-ADUser -Filter * -SearchBase "OU=Finance,OU=UserAccounts,DC=FABRIKAM,DC=COM"`|

+|Stop the scheduler|Before creating new sync rules, you need to stop the Azure AD Connect scheduler. For more information, see [how to stop the scheduler](../connect/how-to-connect-sync-feature-scheduler.md#stop-the-scheduler).

+|Create the custom sync rules|In the Azure AD Connect Synchronization Rules editor, you need to create an inbound sync rule that filters out users in the OU you created or identified previously. The inbound sync rule is a join rule with a target attribute of cloudNoFlow. You'll also need an outbound sync rule with a link type of JoinNoFlow and the scoping filter that has the cloudNoFlow attribute set to True. For more information, see [Migrate to Azure AD Connect cloud sync for an existing synced AD forest](tutorial-pilot-aadc-aadccp.md#create-custom-user-inbound-rule) tutorial for how to create these rules.|

+|Install the provisioning agent|If you haven't done so, install the provisioning agent. For more information, see [how to install the agent](how-to-install.md).|

+|Configure cloud sync|Once the agent is installed, you need to configure cloud sync. In the configuration, you need to create a scope to the OU that was created or identified previously. For more information, see [Configuring cloud sync](how-to-configure.md).|

+|Verify pilot users are synchronizing and being provisioned|Verify that the users are now being synchronized in the portal. You can use the PowerShell script below to get a count of the number of users that have the on-premises pilot OU in their distinguished name. This number should match the count of users in the previous step. If you create a new user in this OU, verify that it's being provisioned.|

+|Start the scheduler|Now that you've verified users are provisioning and synchronizing, you can go ahead and start the Azure AD Connect scheduler. For more information, see [how to start the scheduler](../connect/how-to-connect-sync-feature-scheduler.md#start-the-scheduler).

+|Schedule you remaining users|Now you should come up with a plan on migrating more users. You should use a phased approach so that you can verify that the migrations are successful.|

+|Verify all users are provisioned|As you migrate users, verify that they're provisioning and synchronizing correctly.|

+|Stop Azure AD Connect|Once you've verified that all of your users are migrated, you can turn off the Azure AD Connect synchronization service. Microsoft recommends that you leave the server is a disabled state for a period of time, so you can verify the migration was successful

+|Verify everything is good|After a period of time, verify that everything is good.|

+|Decommission the Azure AD Connect server|Once you've verified everything is good you can use the steps below to take the Azure AD Connect server offline.|

+## Verify Users script

+```PowerShell

+# Filename: VerifyAzureUsers.ps1

+# Description: Counts the number of users in Azure that have a specific on-premises distinguished name.

+#

+# DISCLAIMER:

+# Copyright (c) Microsoft Corporation. All rights reserved. This

+# script is made available to you without any express, implied or

+# statutory warranty, not even the implied warranty of

+# merchantability or fitness for a particular purpose, or the

+# warranty of title or non-infringement. The entire risk of the

+# use or the results from the use of this script remains with you.

+#

+#

+#

+#

+Connect-AzureAD -Confirm

+#Declare variables

+$Users = Get-AzureADUser -All:$true -Filter "DirSyncEnabled eq true"

+$OU = "OU=Sales,DC=contoso,DC=com"

+$counter = 0

+#Search users

+foreach ($user in $Users) {

+ $test = $User.ExtensionProperty

+ $DN = $test["onPremisesDistinguishedName"]

+ if ($DN -match $OU)

+ {

+ $counter++

+ }

+}

+Write-Host "Total Users found:" + $counter

+```

+## More information

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+- [Create a new configuration for Azure AD Connect cloud sync](how-to-configure.md).

+- [Migrate to Azure AD Connect cloud sync for an existing synced AD forest](tutorial-pilot-aadc-aadccp.md)

+``

+ Title: Azure AD Connect cloud sync supported topologies and scenarios

+description: Learn about various on-premises and Azure Active Directory (Azure AD) topologies that use Azure AD Connect cloud sync.

+# Azure AD Connect cloud sync supported topologies and scenarios

+This article describes various on-premises and Azure Active Directory (Azure AD) topologies that use Azure AD Connect cloud sync. This article includes only supported configurations and scenarios.

+> [!IMPORTANT]

+> Microsoft doesn't support modifying or operating Azure AD Connect cloud sync outside of the configurations or actions that are formally documented. Any of these configurations or actions might result in an inconsistent or unsupported state of Azure AD Connect cloud sync. As a result, Microsoft can't provide technical support for such deployments.

+For more information, see the following video.

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWJ8l5]

+## Things to remember about all scenarios and topologies

+The information below should be kept in mind, when selecting a solution.

+- Users and groups must be uniquely identified across all forests

+- Matching across forests doesn't occur with cloud sync

+- The source anchor for objects is chosen automatically. It uses ms-DS-ConsistencyGuid if present, otherwise ObjectGUID is used.

+- You can't change the attribute that is used for source anchor.

+## Single forest, single Azure AD tenant

+

+The simplest topology is a single on-premises forest, with one or multiple domains, and a single Azure AD tenant. For an example of this scenario see [Tutorial: A single forest with a single Azure AD tenant](tutorial-single-forest.md)

+## Multi-forest, single Azure AD tenant

+

+Multiple AD forests is a common topology, with one or multiple domains, and a single Azure AD tenant.

+## Existing forest with Azure AD Connect, new forest with cloud Provisioning

+

+This scenario is topology is similar to the multi-forest scenario, however this one involves an existing Azure AD Connect environment and then bringing on a new forest using Azure AD Connect cloud sync. For an example of this scenario see [Tutorial: An existing forest with a single Azure AD tenant](tutorial-existing-forest.md)

+## Piloting Azure AD Connect cloud sync in an existing hybrid AD forest

+

+The piloting scenario involves the existence of both Azure AD Connect and Azure AD Connect cloud sync in the same forest and scoping the users and groups accordingly. NOTE: An object should be in scope in only one of the tools.

+For an example of this scenario see [Tutorial: Pilot Azure AD Connect cloud sync in an existing synced AD forest](tutorial-pilot-aadc-aadccp.md)

+## Merging objects from disconnected sources

+### (Public Preview)

+

+In this scenario, the attributes of a user are contributed to by two disconnected Active Directory forests.

+An example would be:

+ - one forest (1) contains most of the attributes

+ - a second forest (2) contains a few attributes

+ Since the second forest doesn't have network connectivity to the Azure AD Connect server, the object can't be merged through Azure AD Connect. Cloud Sync in the second forest allows the attribute value to be retrieved from the second forest. The value can then be merged with the object in Azure AD that is synced by Azure AD Connect.

+This configuration is advanced and there are a few caveats to this topology:

+ 1. You must use `msdsConsistencyGuid` as the source anchor in the Cloud Sync configuration.

+ 2. The `msdsConsistencyGuid` of the user object in the second forest must match that of the corresponding object in Azure AD.

+ 3. You must populate the `UserPrincipalName` attribute and the `Alias` attribute in the second forest and it must match the ones that are synced from the first forest.

+ 4. You must remove all attributes from the attribute mapping in the Cloud Sync configuration that don't have a value or may have a different value in the second forest ΓÇô you can't have overlapping attribute mappings between the first forest and the second one.

+ 5. If there's no matching object in the first forest, for an object that is synced from the second forest, then Cloud Sync will still create the object in Azure AD. The object will only have the attributes that are defined in the mapping configuration of Cloud Sync for the second forest.

+ 6. If you delete the object from the second forest, it will be temporarily soft deleted in Azure AD. It will be restored automatically after the next Azure AD Connect sync cycle.

+ 7. If you delete the object from the first forest, it will be soft deleted from Azure AD. The object won't be restored unless a change is made to the object in the second forest. After 30 days the object will be hard deleted from Azure AD and if a change is made to the object in the second forest it will be created as a new object in Azure AD.

+

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Azure AD Connect cloud sync error codes and descriptions

+description: reference article for cloud sync error codes

+# Azure AD Connect cloud sync error codes and descriptions

+The following is a list of error codes and their description

+## Error codes

+|Error code|Details|Scenario|Resolution|

+|--|--|--|--|

+|TimeOut|Error Message: We've detected a request timeout error when contacting the on-premises agent and synchronizing your configuration. For additional issues related to your cloud sync agent, please see our troubleshooting guidance.|Request to HIS timed out. Current Timeout value is 10 minutes.|See our [troubleshooting guidance](how-to-troubleshoot.md)|

+|HybridSynchronizationActiveDirectoryInternalServerError|Error Message: We were unable to process this request at this point. If this issue persists, please contact support and provide the following job identifier: AD2AADProvisioning.30b500eaf9c643b2b78804e80c1421fe.5c291d3c-d29f-4570-9d6b-f0c2fa3d5926. Additional details: Processing of the HTTP request resulted in an exception. |Couldn't process the parameters received in SCIM request to a Search request.|Please see the HTTP response returned by the 'Response' property of this exception for details.|

+|HybridIdentityServiceNoAgentsAssigned|Error Message: We're unable to find an active agent for the domain you're trying to sync. Please check to see if the agents have been removed. If so, re-install the agent again.|There are no agents running. Probably agents have been removed. Register a new agent.|"In this case, you won't see any agent assigned to the domain in portal.|

+|HybridIdentityServiceNoActiveAgents|Error Message: We're unable to find an active agent for the domain you're trying to sync. Please check to see if the agent is running by going to the server, where the agent is installed, and check to see if "Microsoft Azure AD Cloud Sync Agent" under Services is running.|"Agents aren't listening to the ServiceBus endpoint. [The agent is behind a firewall that doesn't allow connections to service bus](../../app-proxy/application-proxy-configure-connectors-with-proxy-servers.md#use-the-outbound-proxy-server)|

+|HybridIdentityServiceInvalidResource|Error Message: We were unable to process this request at this point. If this issue persists, please contact support and provide the following job identifier: AD2AADProvisioning.3a2a0d8418f34f54a03da5b70b1f7b0c.d583d090-9cd3-4d0a-aee6-8d666658c3e9. Additional details: There seems to be an issue with your cloud sync setup. Please re-register your cloud sync agent on your on-premises AD domain and restart configuration from Azure portal.|The resource name must be set so HIS knows which agent to contact.|Please re-register your cloud sync agent on your on-premises AD domain and restart configuration from Azure portal.|

+|HybridIdentityServiceAgentSignalingError|Error Message: We were unable to process this request at this point. If this issue persists, please contact support and provide the following job identifier: AD2AADProvisioning.92d2e8750f37407fa2301c9e52ad7e9b.efb835ef-62e8-42e3-b495-18d5272eb3f9. Additional details: We were unable to process this request at this point. If this issue persists, please contact support with Job ID (from status pane of your configuration).|Service Bus isn't able to send a message to the agent. Could be an outage in service bus, or the agent isn't responsive.|If this issue persists, please contact support with Job ID (from status pane of your configuration).|

+|AzureDirectoryServiceServerBusy|Error Message: An error occurred. Error Code: 81. Error Description: Azure Active Directory is currently busy. This operation will be retried automatically. If this issue persists for more than 24 hours, contact Technical Support. Tracking ID: 8a4ab3b5-3664-4278-ab64-9cff37fd3f4f Server Name:|Azure Active Directory is currently busy.|If this issue persists for more than 24 hours, contact Technical Support.|

+|AzureActiveDirectoryInvalidCredential|Error Message: We found an issue with the service account that is used to run Azure AD Connect Cloud Sync. You can repair the cloud service account by following the instructions at [here](./how-to-troubleshoot.md). If the error persists, please contact support with Job ID (from status pane of your configuration). Additional Error Details: CredentialsInvalid AADSTS50034: The user account {EmailHidden} doesn't exist in the skydrive365.onmicrosoft.com directory. To sign into this application, the account must be added to the directory. Trace ID: 14b63033-3bc9-4bd4-b871-5eb4b3500200 Correlation ID: 57d93ed1-be4d-483c-997c-a3b6f03deb00 Timestamp: 2021-01-12 21:08:29Z |This error is thrown when the sync service account ADToAADSyncServiceAccount doesn't exist in the tenant. It can be due to accidental deletion of the account.|Use [Repair-AADCloudSyncToolsAccount](reference-powershell.md#repair-aadcloudsynctoolsaccount) to fix the service account.|

+|AzureActiveDirectoryExpiredCredentials|Error Message: We were unable to process this request at this point. If this issue persists, please contact support with Job ID (from status pane of your configuration). Additional Error Details: CredentialsExpired AADSTS50055: The password is expired. Trace ID: 989b1841-dbe5-49c9-ab6c-9aa25f7b0e00 Correlation ID: 1c69b196-1c3a-4381-9187-c84747807155 Timestamp: 2021-01-12 20:59:31Z | Response status code doesn't indicate success: 401 (Unauthorized).<br> Azure AD Sync service account credentials are expired.|You can repair the cloud service account by following the instructions at https://go.microsoft.com/fwlink/?linkid=2150988. If the error persists, please contact support with Job ID (from status pane of your configuration). Additional Error Details: Your administrative Azure Active Directory tenant credentials were exchanged for an OAuth token that has since expired."|

+|AzureActiveDirectoryAuthenticationFailed|Error Message: We were unable to process this request at this point. If this issue persists, please contact support and provide the following job identifier: AD2AADProvisioning.60b943e88f234db2b887f8cb91dee87c.707be0d2-c6a9-405d-a3b9-de87761dc3ac. Additional details: We were unable to process this request at this point. If this issue persists, please contact support with Job ID (from status pane of your configuration). Additional Error Details: UnexpectedError.|Unknown error.|If this issue persists, please contact support with Job ID (from status pane of your configuration).|

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Azure AD Connect cloud sync expressions and function reference

+description: reference

+# Writing expressions for attribute mappings in Azure Active Directory

+When you configure cloud sync, one of the types of attribute mappings that you can specify is an expression mapping.

+The expression mapping allows you to customize attributes using a script-like expression. This allows you to transform the on-premises data into a new or different value. For example, you may want to combine two attributes into a single attribute because this single attribute is used by one of your cloud applications.

+The following document will cover the script-like expressions that are used to transform the data. This is only part of the process. Next you will need to use this expression and place it in a web request to your tenant. For more information on that see [Transformations](how-to-transformation.md)

+## Syntax overview

+The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic for Applications (VBA) functions.

+* The entire expression must be defined in terms of functions, which consist of a name followed by arguments in parentheses: <br>

+ *FunctionName(`<<argument 1>>`,`<<argument N>>`)*

+* You may nest functions within each other. For example: <br> *FunctionOne(FunctionTwo(`<<argument1>>`))*

+* You can pass three different types of arguments into functions:

+

+ 1. Attributes, which must be enclosed in square brackets. For example: [attributeName]

+ 2. String constants, which must be enclosed in double quotes. For example: "United States"

+ 3. Other Functions. For example: FunctionOne(`<<argument1>>`, FunctionTwo(`<<argument2>>`))

+* For string constants, if you need a backslash ( \ ) or quotation mark ( " ) in the string, it must be escaped with the backslash ( \ ) symbol. For example: "Company name: \\"Contoso\\""

+## List of functions

+| List of functions | Description |

+|--|-|

+|[Append](#append)|Takes a source string value and appends the suffix to the end of it.|

+|[BitAnd](#bitand)|The BitAnd function sets specified bits on a value.|

+|[CBool](#cbool)|The CBool function returns a Boolean based on the evaluated expression|

+|[ConvertFromBase64](#convertfrombase64)|The ConvertFromBase64 function converts the specified base64 encoded value to a regular string.|

+|[ConvertToBase64](#converttobase64)|The ConvertToBase64 function converts a string to a Unicode base64 string. |

+|[ConvertToUTF8Hex](#converttoutf8hex)|The ConvertToUTF8Hex function converts a string to a UTF8 Hex encoded value.|

+|[Count](#count)|The Count function returns the number of elements in a multi-valued attribute|

+|[Cstr](#cstr)|The CStr function converts to a string data type.|

+|[DateFromNum](#datefromnum)|The DateFromNum function converts a value in ADΓÇÖs date format to a DateTime type.|

+|[DNComponent](#dncomponent)|The DNComponent function returns the value of a specified DN component going from left.|

+|[Error](#error)|The Error function is used to return a custom error.|

+|[FormatDateTime](#formatdatetime) |Takes a date string from one format and converts it into a different format.|

+|[GUID](#guid)|The function Guid generates a new random GUID.|

+|[IIF](#iif)|The IIF function returns one of a set of possible values based on a specified condition.|

+|[InStr](#instr)|The InStr function finds the first occurrence of a substring in a string.|

+|[IsNull](#isnull)|If the expression evaluates to Null, then the IsNull function returns true.|

+|[IsNullOrEmpty](#isnullorempty)|If the expression is null or an empty string, then the IsNullOrEmpty function returns true.|

+|[IsPresent](#ispresent)|If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true.|

+|[IsString](#isstring)|If the expression can be evaluated to a string type, then the IsString function evaluates to True.|

+|[Item](#item)|The Item function returns one item from a multi-valued string/attribute.|

+|[Join](#join) |Join() is similar to Append(), except that it can combine multiple **source** string values into a single string, and each value will be separated by a **separator** string.|

+|[Left](#left)|The Left function returns a specified number of characters from the left of a string.|

+|[Mid](#mid) |Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string.|

+|[NormalizeDiacritics](#normalizediacritics)|Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters.|

+|[Not](#not) |Flips the boolean value of the **source**. If **source** value is "*True*", returns "*False*". Otherwise, returns "*True*".|

+|[RemoveDuplicates](#removeduplicates)|The RemoveDuplicates function takes a multi-valued string and make sure each value is unique.|

+|[Replace](#replace) |Replaces values within a string. |

+|[SelectUniqueValue](#selectuniquevalue)|Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory.|

+|[SingleAppRoleAssignment](#singleapproleassignment)|Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application.|

+|[Split](#split)|Splits a string into a multi-valued array, using the specified delimiter character.|

+|[StringFromSID](#stringfromsid)|The StringFromSid function converts a byte array containing a security identifier to a string.|

+|[StripSpaces](#stripspaces) |Removes all space (" ") characters from the source string.|

+|[Switch](#switch)|When **source** value matches a **key**, returns **value** for that **key**. |

+|[ToLower](#tolower)|Takes a *source* string value and converts it to lower case using the culture rules that are specified.|

+|[ToUpper](#toupper)|Takes a *source* string value and converts it to upper case using the culture rules that are specified.|

+|[Trim](#trim)|The Trim function removes leading and trailing white spaces from a string.|

+|[Word](#word)|The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return.|

+### Append

+**Function:**<br>

+Append(source, suffix)

+**Description:**<br>

+Takes a source string value and appends the suffix to the end of it.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |Usually name of the attribute from the source object. |

+ | **suffix** |Required |String |The string that you want to append to the end of the source value. |

+### BitAnd

+**Description:**

+The BitAnd function sets specified bits on a value.

+**Syntax:**

+`num BitAnd(num value1, num value2)`

+* value1, value2: numeric values that should be ANDΓÇÖed together

+**Remarks:**

+This function converts both parameters to the binary representation and sets a bit to:

+* 0 - if one or both of the corresponding bits in *value1* and *value2* are 0

+* 1 - if both of the corresponding bits are 1.

+In other words, it returns 0 in all cases except when the corresponding bits of both parameters are 1.

+**Example:**

+

+ `BitAnd(&HF, &HF7)`</br>

+ Returns 7 because hexadecimal "F" AND "F7" evaluate to this value.

+### CBool

+**Description:**

+The CBool function returns a Boolean based on the evaluated expression

+**Syntax:**

+`bool CBool(exp Expression)`

+**Remarks:**

+If the expression evaluates to a non-zero value, then CBool returns True, else it returns False.

+**Example:**

+`CBool([attrib1] = [attrib2])`

+Returns True if both attributes have the same value.

+### ConvertFromBase64

+**Description:**

+The ConvertFromBase64 function converts the specified base64 encoded value to a regular string.

+**Syntax:**

+`str ConvertFromBase64(str source)` - assumes Unicode for encoding

+`str ConvertFromBase64(str source, enum Encoding)`

+* source: Base64 encoded string

+* Encoding: Unicode, ASCII, UTF8

+**Example**

+`ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")`

+`ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)`

+Both examples return "*Hello world!*"

+### ConvertToBase64

+**Description:**

+The ConvertToBase64 function converts a string to a Unicode base64 string.

+Converts the value of an array of integers to its equivalent string representation that is encoded with base-64 digits.

+**Syntax:**

+`str ConvertToBase64(str source)`

+**Example:**

+`ConvertToBase64("Hello world!")`

+Returns "SABlAGwAbABvACAAdwBvAHIAbABkACEA"

+### ConvertToUTF8Hex

+**Description:**

+The ConvertToUTF8Hex function converts a string to a UTF8 Hex encoded value.

+**Syntax:**

+`str ConvertToUTF8Hex(str source)`

+**Remarks:**

+The output format of this function is used by Azure Active Directory as DN attribute format.

+**Example:**

+`ConvertToUTF8Hex("Hello world!")`

+Returns 48656C6C6F20776F726C6421

+### Count

+**Description:**

+The Count function returns the number of elements in a multi-valued attribute

+**Syntax:**

+`num Count(mvstr attribute)`

+### CStr

+**Description:**

+The CStr function converts to a string data type.

+**Syntax:**

+`str CStr(num value)`

+`str CStr(ref value)`

+`str CStr(bool value)`

+* value: Can be a numeric value, reference attribute, or Boolean.

+**Example:**

+`CStr([dn])`

+Could return "cn=Joe,dc=contoso,dc=com"

+### DateFromNum

+**Description:**

+The DateFromNum function converts a value in ADΓÇÖs date format to a DateTime type.

+**Syntax:**

+`dt DateFromNum(num value)`

+**Example:**

+`DateFromNum([lastLogonTimestamp])`

+`DateFromNum(129699324000000000)`

+Returns a DateTime representing 2012-01-01 23:00:00

+### DNComponent

+**Description:**

+The DNComponent function returns the value of a specified DN component going from left.

+**Syntax:**

+`str DNComponent(ref dn, num ComponentNumber)`

+* dn: the reference attribute to interpret

+* ComponentNumber: The component in the DN to return

+**Example:**

+`DNComponent(CRef([dn]),1)`

+If dn is "cn=Joe,ou=…," it returns Joe

+### Error

+**Description:**

+The Error function is used to return a custom error.

+**Syntax:**

+`void Error(str ErrorMessage)`

+**Example:**

+`IIF(IsPresent([accountName]),[accountName],Error("AccountName is required"))`

+If the attribute accountName is not present, throw an error on the object.

+### FormatDateTime

+**Function:**<br>

+FormatDateTime(source, inputFormat, outputFormat)

+**Description:**<br>

+Takes a date string from one format and converts it into a different format.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |Usually name of the attribute from the source object. |

+ | **inputFormat** |Required |String |Expected format of the source value. For supported formats, see [/dotnet/standard/base-types/custom-date-and-time-format-strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |

+ | **outputFormat** |Required |String |Format of the output date. |

+### Guid

+**Description:**

+The function Guid generates a new random GUID

+**Syntax:**

+`str Guid()`

+### IIF

+**Description:**

+The IIF function returns one of a set of possible values based on a specified condition.

+**Syntax:**

+`var IIF(exp condition, var valueIfTrue, var valueIfFalse)`

+* condition: any value or expression that can be evaluated to true or false.

+* valueIfTrue: If the condition evaluates to true, the returned value.

+* valueIfFalse: If the condition evaluates to false, the returned value.

+**Example:**

+`IIF([employeeType]="Intern","t-" & [alias],[alias])`

+ If the user is an intern, returns the alias of a user with "t-" added to the beginning of it, else returns the userΓÇÖs alias as is.

+### InStr

+**Description:**

+The InStr function finds the first occurrence of a substring in a string

+**Syntax:**

+`num InStr(str stringcheck, str stringmatch)`

+`num InStr(str stringcheck, str stringmatch, num start)`

+`num InStr(str stringcheck, str stringmatch, num start, enum compare)`

+* stringcheck: string to be searched

+* stringmatch: string to be found

+* start: starting position to find the substring

+* compare: vbTextCompare or vbBinaryCompare

+**Remarks:**

+Returns the position where the substring was found or 0 if not found.

+**Example:**

+`InStr("The quick brown fox","quick")`

+Evalues to 5

+`InStr("repEated","e",3,vbBinaryCompare)`

+Evaluates to 7

+### IsNull

+**Description:**

+If the expression evaluates to Null, then the IsNull function returns true.

+**Syntax:**

+`bool IsNull(var Expression)`

+**Remarks:**

+For an attribute, a Null is expressed by the absence of the attribute.

+**Example:**

+`IsNull([displayName])`

+Returns True if the attribute is not present in the CS or MV.

+### IsNullOrEmpty

+**Description:**

+If the expression is null or an empty string, then the IsNullOrEmpty function returns true.

+**Syntax:**

+`bool IsNullOrEmpty(var Expression)`

+**Remarks:**

+For an attribute, this would evaluate to True if the attribute is absent or is present but is an empty string.

+The inverse of this function is named IsPresent.

+**Example:**

+`IsNullOrEmpty([displayName])`

+Returns True if the attribute is not present or is an empty string in the CS or MV.

+### IsPresent

+**Description:**

+If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true.

+**Syntax:**

+`bool IsPresent(var expression)`

+**Remarks:**

+The inverse of this function is named IsNullOrEmpty.

+**Example:**

+`Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])`

+### Item

+**Description:**

+The Item function returns one item from a multi-valued string/attribute.

+**Syntax:**

+`var Item(mvstr attribute, num index)`

+* attribute: multi-valued attribute

+* index: index to an item in the multi-valued string.

+**Remarks:**

+The Item function is useful together with the Contains function since the latter function returns the index to an item in the multi-valued attribute.

+Throws an error if index is out of bounds.

+**Example:**

+`Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)`

+Returns the primary email address.

+### IsString

+**Description:**

+If the expression can be evaluated to a string type, then the IsString function evaluates to True.

+**Syntax:**

+`bool IsString(var expression)`

+**Remarks:**

+Used to determine if CStr() can be successful to parse the expression.

+### Join

+**Function:**<br>

+Join(separator, source1, source2, …)

+**Description:**<br>

+Join() is similar to Append(), except that it can combine multiple **source** string values into a single string, and each value will be separated by a **separator** string.

+If one of the source values is a multi-value attribute, then every value in that attribute will be joined together, separated by the separator value.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **separator** |Required |String |String used to separate source values when they are concatenated into one string. Can be "" if no separator is required. |

+ | **source1 … sourceN** |Required, variable-number of times |String |String values to be joined together. |

+### Left

+**Description:**

+The Left function returns a specified number of characters from the left of a string.

+**Syntax:**

+`str Left(str string, num NumChars)`

+* string: the string to return characters from

+* NumChars: a number identifying the number of characters to return from the beginning (left) of string

+**Remarks:**

+A string containing the first numChars characters in string:

+* If numChars = 0, return empty string.

+* If numChars < 0, return input string.

+* If string is null, return empty string.

+If string contains fewer characters than the number specified in numChars, a string identical to string (that is, containing all characters in parameter 1) is returned.

+**Example:**

+`Left("John Doe", 3)`

+Returns `Joh`.

+### Mid

+**Function:**<br>

+Mid(source, start, length)

+**Description:**<br>

+Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |Usually name of the attribute. |

+ | **start** |Required |integer |Index in the **source** string where substring should start. First character in the string will have index of 1, second character will have index 2, and so on. |

+ | **length** |Required |integer |Length of the substring. If length ends outside the **source** string, function will return substring from **start** index till end of **source** string. |

+### NormalizeDiacritics

+**Function:**<br>

+NormalizeDiacritics(source)

+**Description:**<br>

+Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters. Typically used to convert first names and last names containing diacritical characters (accent marks) into legal values that can be used in various user identifiers such as user principal names, SAM account names, and email addresses.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String | Usually a first name or last name attribute. |

+### Not

+**Function:**<br>

+Not(source)

+**Description:**<br>

+Flips the boolean value of the **source**. If **source** value is "*True*", returns "*False*". Otherwise, returns "*True*".

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |Boolean String |Expected **source** values are "True" or "False". |

+### RemoveDuplicates

+**Description:**

+The RemoveDuplicates function takes a multi-valued string and make sure each value is unique.

+**Syntax:**

+`mvstr RemoveDuplicates(mvstr attribute)`

+**Example:**

+`RemoveDuplicates([proxyAddresses])`

+Returns a sanitized proxyAddress attribute where all duplicate values have been removed.

+### Replace

+**Function:**<br>

+Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)

+**Description:**<br>

+Replaces values within a string. It works differently depending on the parameters provided:

+* When **oldValue** and **replacementValue** are provided:

+

+ * Replaces all occurrences of **oldValue** in the **source** with **replacementValue**

+* When **oldValue** and **template** are provided:

+

+ * Replaces all occurrences of the **oldValue** in the **template** with the **source** value

+* When **regexPattern** and **replacementValue** are provided:

+ * The function applies the **regexPattern** to the **source** string and you can use the regex group names to construct the string for **replacementValue**

+* When **regexPattern**, **regexGroupName**, **replacementValue** are provided:

+

+ * The function applies the **regexPattern** to the **source** string and replaces all values matching **regexGroupName** with **replacementValue**

+* When **regexPattern**, **regexGroupName**, **replacementAttributeName** are provided:

+

+ * If **source** has no value, **source** is returned

+ * If **source** has a value, the function applies the **regexPattern** to the **source** string and replaces all values matching **regexGroupName** with the value associated with **replacementAttributeName**

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |Usually name of the attribute from the **source** object. |

+ | **oldValue** |Optional |String |Value to be replaced in **source** or **template**. |

+ | **regexPattern** |Optional |String |Regex pattern for the value to be replaced in **source**. Or, when **replacementPropertyName** is used, pattern to extract value from **replacementPropertyName**. |

+ | **regexGroupName** |Optional |String |Name of the group inside **regexPattern**. Only when **replacementPropertyName** is used, we will extract value of this group as **replacementValue** from **replacementPropertyName**. |

+ | **replacementValue** |Optional |String |New value to replace old one with. |

+ | **replacementAttributeName** |Optional |String |Name of the attribute to be used for replacement value |

+ | **template** |Optional |String |When **template** value is provided, we will look for **oldValue** inside the template and replace it with **source** value. |

+### SelectUniqueValue

+**Function:**<br>

+SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …)

+**Description:**<br>

+Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory. The first unique value found will be the one returned. If all of the values already exist in the target, the entry will get escrowed and the reason gets logged in the audit logs. There is no upper bound to the number of arguments that can be provided.

+> [!NOTE]

+> - This is a top-level function, it cannot be nested.

+> - This function cannot be applied to attributes that have a matching precedence.

+> - This function is only meant to be used for entry creations. When using it with an attribute, set the **Apply Mapping** property to **Only during object creation**.

+> - This function is currently only supported for "Workday and SuccessFactors to Active Directory User Provisioning". It cannot be used with other provisioning applications.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **uniqueValueRule1 … uniqueValueRuleN** |At least 2 are required, no upper bound |String | List of unique value generation rules to evaluate. |

+### SingleAppRoleAssignment

+**Function:**<br>

+SingleAppRoleAssignment([appRoleAssignments])

+**Description:**<br>

+Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. Note that the best practice is to ensure only one appRoleAssignment is assigned to one user at a time, and if multiple roles are assigned the role string returned may not be predictable.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **[appRoleAssignments]** |Required |String |**[appRoleAssignments]** object. |

+### Split

+**Function:**<br>

+Split(source, delimiter)

+**Description:**<br>

+Splits a string into a multi-valued array, using the specified delimiter character.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |**source** value to update. |

+ | **delimiter** |Required |String |Specifies the character that will be used to split the string (example: ",") |

+### StringFromSid

+**Description:**

+The StringFromSid function converts a byte array containing a security identifier to a string.

+**Syntax:**

+`str StringFromSid(bin ObjectSID)`

+### StripSpaces

+**Function:**<br>

+StripSpaces(source)

+**Description:**<br>

+Removes all space (" ") characters from the source string.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |**source** value to update. |

+### Switch

+**Function:**<br>

+Switch(source, defaultValue, key1, value1, key2, value2, …)

+**Description:**<br>

+When **source** value matches a **key**, returns **value** for that **key**. If **source** value doesn't match any keys, returns **defaultValue**. **Key** and **value** parameters must always come in pairs. The function always expects an even number of parameters.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |**Source** value to check. |

+ | **defaultValue** |Optional |String |Default value to be used when source doesn't match any keys. Can be empty string (""). |

+ | **key** |Required |String |**Key** to compare **source** value with. |

+ | **value** |Required |String |Replacement value for the **source** matching the key. |

+### ToLower

+**Function:**<br>

+ToLower(source, culture)

+**Description:**<br>

+Takes a *source* string value and converts it to lower case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |Usually name of the attribute from the source object |

+ | **culture** |Optional |String |The format for the culture name based on RFC 4646 is *languagecode2-country/regioncode2*, where *languagecode2* is the two-letter language code and *country/regioncode2* is the two-letter subculture code. Examples include ja-JP for Japanese (Japan) and en-US for English (United States). In cases where a two-letter language code is not available, a three-letter code derived from ISO 639-2 is used.|

+### ToUpper

+**Function:**<br>

+ToUpper(source, culture)

+**Description:**<br>

+Takes a *source* string value and converts it to upper case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture.

+**Parameters:**<br>

+ | Name | Required/ Repeating | Type | Notes |

+ | | | | |

+ | **source** |Required |String |Usually name of the attribute from the source object. |

+ | **culture** |Optional |String |The format for the culture name based on RFC 4646 is *languagecode2-country/regioncode2*, where *languagecode2* is the two-letter language code and *country/regioncode2* is the two-letter subculture code. Examples include ja-JP for Japanese (Japan) and en-US for English (United States). In cases where a two-letter language code is not available, a three-letter code derived from ISO 639-2 is used.|

+### Trim

+**Description:**

+The Trim function removes leading and trailing white spaces from a string.

+**Syntax:**

+`str Trim(str value)`

+**Example:**

+`Trim(" Test ")`

+Returns "Test".

+`Trim([proxyAddresses])`

+Removes leading and trailing spaces for each value in the proxyAddress attribute.

+### Word

+**Description:**

+The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return.

+**Syntax:**

+`str Word(str string, num WordNumber, str delimiters)`

+* string: the string to return a word from.

+* WordNumber: a number identifying which word number should return.

+* delimiters: a string representing the delimiter(s) that should be used to identify words

+**Remarks:**

+Each string of characters in string separated by the one of the characters in delimiters are identified as words:

+* If number < 1, returns empty string.

+* If string is null, returns empty string.

+If string contains less than number words, or string does not contain any words identified by delimiters, an empty string is returned.

+**Example:**

+`Word("The quick brown fox",3," ")`

+Returns "brown"

+`Word("This,string!has&many separators",3,",!&#")`

+Would return "has"

+## Examples

+### Strip known domain name

+You need to strip a known domain name from a userΓÇÖs email to obtain a user name. <br>

+For example, if the domain is "contoso.com", then you could use the following expression:

+**Expression:** <br>

+`Replace([mail], "@contoso.com", , ,"", ,)`

+**Sample input / output:** <br>

+* **INPUT** (mail): "john.doe@contoso.com"

+* **OUTPUT**: "john.doe"

+### Append constant suffix to user name

+If you are using a Salesforce Sandbox, you might need to append an additional suffix to all your user names before synchronizing them.

+**Expression:** <br>

+`Append([userPrincipalName], ".test")`

+**Sample input/output:** <br>

+* **INPUT**: (userPrincipalName): "John.Doe@contoso.com"

+* **OUTPUT**: "John.Doe@contoso.com.test"

+### Generate user alias by concatenating parts of first and last name

+You need to generate a user alias by taking first 3 letters of user's first name and first 5 letters of user's last name.

+**Expression:** <br>

+`Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))`

+**Sample input/output:** <br>

+* **INPUT** (givenName): "John"

+* **INPUT** (surname): "Doe"

+* **OUTPUT**: "JohDoe"

+### Remove diacritics from a string

+You need to replace characters containing accent marks with equivalent characters that don't contain accent marks.

+**Expression:** <br>

+NormalizeDiacritics([givenName])

+**Sample input/output:** <br>

+* **INPUT** (givenName): "Zoë"

+* **OUTPUT**: "Zoe"

+### Split a string into a multi-valued array

+You need to take a comma-delimited list of strings, and split them into an array that can be plugged into a multi-value attribute like Salesforce's PermissionSets attribute. In this example, a list of permission sets has been populated in extensionAttribute5 in Azure AD.

+**Expression:** <br>

+Split([extensionAttribute5], ",")

+**Sample input/output:** <br>

+* **INPUT** (extensionAttribute5): "PermissionSetOne, PermissionSetTwo"

+* **OUTPUT**: ["PermissionSetOne", "PermissionSetTwo"]

+### Output date as a string in a certain format

+You want to send dates to a SaaS application in a certain format. <br>

+For example, you want to format dates for ServiceNow.

+**Expression:** <br>

+`FormatDateTime([extensionAttribute1], "yyyyMMddHHmmss.fZ", "yyyy-MM-dd")`

+**Sample input/output:**

+* **INPUT** (extensionAttribute1): "20150123105347.1Z"

+* **OUTPUT**: "2015-01-23"

+### Replace a value based on predefined set of options

+You need to define the time zone of the user based on the state code stored in Azure AD. <br>

+If the state code doesn't match any of the predefined options, use default value of "Australia/Sydney".

+**Expression:** <br>

+`Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD", "Australia/Brisbane", "SA", "Australia/Adelaide")`

+**Sample input/output:**

+* **INPUT** (state): "QLD"

+* **OUTPUT**: "Australia/Brisbane"

+### Replace characters using a regular expression

+You need to find characters that match a regular expression value and remove them.

+**Expression:** <br>

+Replace([mailNickname], , "[a-zA-Z_]*", , "", , )

+**Sample input/output:**

+* **INPUT** (mailNickname: "john_doe72"

+* **OUTPUT**: "72"

+### Convert generated userPrincipalName (UPN) value to lower case

+In the example below, the UPN value is generated by concatenating the PreferredFirstName and PreferredLastName source fields and the ToLower function operates on the generated string to convert all characters to lower case.

+`ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))`

+**Sample input/output:**

+* **INPUT** (PreferredFirstName): "John"

+* **INPUT** (PreferredLastName): "Smith"

+* **OUTPUT**: "john.smith@contoso.com"

+### Generate unique value for userPrincipalName (UPN) attribute

+Based on the user's first name, middle name and last name, you need to generate a value for the UPN attribute and check for its uniqueness in the target AD directory before assigning the value to the UPN attribute.

+**Expression:** <br>

+```ad-attr-mapping-expr

+ SelectUniqueValue(

+ Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"),

+ Join("@", NormalizeDiacritics(StripSpaces(Join(".", Mid([PreferredFirstName], 1, 1), [PreferredLastName]))), "contoso.com"),

+ Join("@", NormalizeDiacritics(StripSpaces(Join(".", Mid([PreferredFirstName], 1, 2), [PreferredLastName]))), "contoso.com")

+ )

+```

+**Sample input/output:**

+* **INPUT** (PreferredFirstName): "John"

+* **INPUT** (PreferredLastName): "Smith"

+* **OUTPUT**: "John.Smith@contoso.com" if UPN value of John.Smith@contoso.com doesn't already exist in the directory

+* **OUTPUT**: "J.Smith@contoso.com" if UPN value of John.Smith@contoso.com already exists in the directory

+* **OUTPUT**: "Jo.Smith@contoso.com" if the above two UPN values already exist in the directory

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'AADCloudSyncTools PowerShell module for Azure AD Connect cloud sync'

+description: This article describes how to install the Azure AD Connect cloud provisioning agent.

+# AADCloudSyncTools PowerShell module for Azure AD Connect cloud sync

+The AADCloudSyncTools module provides a set of useful tools that can help you manage your deployments of Azure Active Directory Connect (Azure AD Connect) cloud sync.

+## Prerequisites

+You can automatically install all the prerequisites for the AADCloudSyncTools module by using `Install-AADCloudSyncToolsPrerequisites`. You'll do that in the next section of this article.

+Here are some details about what you need:

+- The AADCloudSyncTools module uses Microsoft Authentication Library (MSAL) authentication, so it requires installation of the MSAL.PS module. To verify the installation, in a PowerShell window, run `Get-module MSAL.PS -ListAvailable`. If the module is installed correctly, you'll get a response. If necessary, you can use `Install-AADCloudSyncToolsPrerequisites` to install the latest version of MSAL.PS.

+- Although the Azure AD PowerShell module is not required for any functionality of the AADCloudSyncTools module, it is useful. So it's automatically installed when you use `Install-AADCloudSyncToolsPrerequisites`.

+- Installing modules from the PowerShell Gallery requires Transport Layer Security (TLS) 1.2 enforcement. The cmdlet `Install-AADCloudSyncToolsPrerequisites` sets TLS 1.2 enforcement before installing all the prerequisites. To ensure that you can manually install modules, set the following in the PowerShell session before using the cmdlet:

+ ```

+ [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

+ ```

+- The AADCloudSyncTools module might not work correctly if the Azure AD Connect cloud provisioning agent is not running or the configuration wizard has not finished successfully.

+## Install the AADCloudSyncTools PowerShell module

+1. Open Windows PowerShell with administrative privileges.

+2. Run `Import-module -Name "C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\Utility\AADCloudSyncTools"`.

+3. To verify that the module was imported, run `Get-module AADCloudSyncTools`.

+ You should now see information about the module.

+4. To install the AADCloudSyncTools module prerequisites, run `Install-AADCloudSyncToolsPrerequisites`.

+5. On the first run, the PowerShellGet module will be installed if it's not present. To load the new PowerShellGet module, close the PowerShell window and open a new PowerShell session with administrative privileges.

+6. Import the module again by running `Import-module -Name "C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\Utility\AADCloudSyncTools"`.

+7. Run `Install-AADCloudSyncToolsPrerequisites` again to install the MSAL and Azure AD modules.

+ All prerequisites should now be installed.

+ 

+8. Every time you want to use the AADCloudSyncTools module in a new PowerShell session, run the following command:

+ ```

+ Import-module "C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\Utility\AADCloudSyncTools"

+ ```

+## AADCloudSyncTools cmdlets

+> [!NOTE]

+> Before using AADCloudSyncTools module make sure the Azure AD Connect cloud provisioning agent is running and the configuration wizard has finished successfully. To troubleshoot wizard issues, you can find trace logs in the folder *C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace*, see [Cloud sync troubleshooting](how-to-troubleshoot.md) for more information.

+### Connect-AADCloudSyncTools

+This cmdlet uses the MSAL.PS module to request a token for the Azure AD administrator to access Microsoft Graph.

+### Export-AADCloudSyncToolsLogs

+This cmdlet exports and packages all the troubleshooting data in a compressed file, as follows:

+1. Sets verbose tracing and starts collecting data from the provisioning agent (same as `Start-AADCloudSyncToolsVerboseLogs`).

+2. Stops data collection after three minutes and disables verbose tracing (same as `Stop-AADCloudSyncToolsVerboseLogs`).

+3. Collects Event Viewer logs for the last 24 hours.

+4. Compresses all the agent logs, verbose logs, and Event Viewer logs into a .zip file in the user's *Documents* folder.

+You can use the following options to fine-tune your data collection:

+- `SkipVerboseTrace` to only export current logs without capturing verbose logs (default = false).

+- `TracingDurationMins` to specify a different capture duration (default = 3 minutes).

+- `OutputPath` to specify a different output path (default = userΓÇÖs Documents folder).

+### Get-AADCloudSyncToolsInfo

+This cmdlet shows Azure AD tenant details and the state of internal variables.

+### Get-AADCloudSyncToolsJob

+This cmdlet uses Microsoft Graph to get Azure AD service principals and returns the sync job's information. You can also call it by using the specific sync job ID as a parameter.

+### Get-AADCloudSyncToolsJobSchedule

+This cmdlet uses Microsoft Graph to get Azure AD service principals and returns the sync job's schedule. You can also call it by using the specific sync job ID as a parameter.

+### Get-AADCloudSyncToolsJobSchema

+This cmdlet uses Microsoft Graph to get Azure AD service principals and returns the sync job's schema.

+### Get-AADCloudSyncToolsJobScope

+This cmdlet uses Microsoft Graph to get the sync job's schema for the provided sync job ID and outputs all filter groups' scopes.

+### Get-AADCloudSyncToolsJobSettings

+This cmdlet uses Microsoft Graph to get Azure AD service principals and returns the sync job's settings. You can also call it by using the specific sync job ID as a parameter.

+### Get-AADCloudSyncToolsJobStatus

+This cmdlet uses Microsoft Graph to get Azure AD service principals and returns the sync job's status. You can also call it by using the specific sync job ID as a parameter.

+### Get-AADCloudSyncToolsServicePrincipal

+This cmdlet uses Microsoft Graph to get the service principals for Azure AD and/or Azure Service Fabric. Without parameters, it will return only Azure AD service principals.

+### Install-AADCloudSyncToolsPrerequisites

+This cmdlet checks for the presence of PowerShellGet v2.2.4.1 or later, the Azure AD module, and the MSAL.PS module. It installs these items if they're missing.

+### Invoke-AADCloudSyncToolsGraphQuery

+This cmdlet invokes a web request for the URI, method, and body specified as parameters.

+### Repair-AADCloudSyncToolsAccount

+This cmdlet uses Azure AD PowerShell to delete the current account (if present). It then resets the sync account authentication with a new sync account in Azure AD.

+### Restart-AADCloudSyncToolsJob

+This cmdlet restarts a full synchronization.

+### Resume-AADCloudSyncToolsJob

+This cmdlet continues synchronization from the previous watermark.

+### Start-AADCloudSyncToolsVerboseLogs

+This cmdlet modifies *AADConnectProvisioningAgent.exe.config* to enable verbose tracing and restarts the AADConnectProvisioningAgent service. You can use `-SkipServiceRestart` to prevent service restart, but any configuration changes will not take effect. You can find these trace logs in the folder *C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace*.

+### Stop-AADCloudSyncToolsVerboseLogs

+This cmdlet modifies *AADConnectProvisioningAgent.exe.config* to disable verbose tracing and restarts the AADConnectProvisioningAgent service. You can use `-SkipServiceRestart` to prevent service restart, but any configuration changes will not take effect.

+### Suspend-AADCloudSyncToolsJob

+This cmdlet pauses synchronization.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: 'Azure AD Connect cloud provisioning agent: Version release history'

+description: This article lists all releases of Azure AD Connect cloud provisioning agent and describes new features and fixed issues

+# Azure AD Connect cloud provisioning agent: Version release history

+ Title: Tutorial - Basic Active Directory on-premises and Azure AD environment.

+description: Learn how to create a basic AD and Azure AD environment.

+# Tutorial: Basic Active Directory environment

+This tutorial walks you through creating a basic Active Directory environment.

+

+You can use the environment you create in the tutorial to test various aspects of hybrid identity scenarios and will be a prerequisite for some of the tutorials. If you already have an existing Active Directory environment you can use that as a substitute. This information is provided for individuals who may be starting from nothing.

+This tutorial consists of

+## Prerequisites

+The following are prerequisites required for completing this tutorial

+- A computer with [Hyper-V](/windows-server/virtualization/hyper-v/hyper-v-technology-overview) installed. It's suggested to do this on either a [Windows 10](/virtualization/hyper-v-on-windows/about/supported-guest-os) or a [Windows Server 2016](/windows-server/virtualization/hyper-v/supported-windows-guest-operating-systems-for-hyper-v-on-windows) computer.

+- An [external network adapter](/virtualization/hyper-v-on-windows/quick-start/connect-to-network) to allow the virtual machine to communicate with the internet.

+- An [Azure subscription](https://azure.microsoft.com/free)

+- A copy of Windows Server 2016

+- [Microsoft .NET framework 4.7.1](https://dotnet.microsoft.com/download/dotnet-framework/net471)

+> [!NOTE]

+> This tutorial uses PowerShell scripts so that you can create the tutorial environment in the quickest amount of time. Each of the scripts uses variables that are declared at the beginning of the scripts. You can and should change the variables to reflect your environment.

+>

+>The scripts used create a general Active Directory environment prior to installing the Azure AD Connect cloud provisioning agent. They are relevant for all of the tutorials.

+>

+> Copies of the PowerShell scripts that are used in this tutorial are available on GitHub [here](https://github.com/billmath/tutorial-phs).

+## Create a virtual machine

+The first thing that you need to do, in order to get our hybrid identity environment up and running is to create a virtual machine that will be used as our on-premises Active Directory server. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ #Declare variables

+ $VMName = 'DC1'

+ $Switch = 'External'

+ $InstallMedia = 'D:\ISO\en_windows_server_2016_updated_feb_2018_x64_dvd_11636692.iso'

+ $Path = 'D:\VM'

+ $VHDPath = 'D:\VM\DC1\DC1.vhdx'

+ $VHDSize = '64424509440'

+ #Create New Virtual Machine

+ New-VM -Name $VMName -MemoryStartupBytes 16GB -BootDevice VHD -Path $Path -NewVHDPath $VHDPath -NewVHDSizeBytes $VHDSize -Generation 2 -Switch $Switch

+ #Set the memory to be non-dynamic

+ Set-VMMemory $VMName -DynamicMemoryEnabled $false

+ #Add DVD Drive to Virtual Machine

+ Add-VMDvdDrive -VMName $VMName -ControllerNumber 0 -ControllerLocation 1 -Path $InstallMedia

+ #Mount Installation Media

+ $DVDDrive = Get-VMDvdDrive -VMName $VMName

+ #Configure Virtual Machine to Boot from DVD

+ Set-VMFirmware -VMName $VMName -FirstBootDevice $DVDDrive

+ ```

+## Complete the operating system deployment

+In order to finish building the virtual machine, you need to finish the operating system installation.

+1. Hyper-V Manager, double-click on the virtual machine

+2. Click on the Start button.

+3. You'll be prompted to ΓÇÿPress any key to boot from CD or DVDΓÇÖ. Go ahead and do so.

+4. On the Windows Server start up screen select your language and click **Next**.

+5. Click **Install Now**.

+6. Enter your license key and click **Next**.

+7. Check **I accept the license terms and click **Next**.

+8. Select **Custom: Install Windows Only (Advanced)**

+9. Click **Next**

+10. Once the installation has completed, restart the virtual machine, sign-in and run Windows updates to ensure the VM is the most up-to-date. Install the latest updates.

+## Install Active Directory prerequisites

+Now that you have a virtual machine up, you need to do a few things prior to installing Active Directory. That is, you need to rename the virtual machine, set a static IP address and DNS information, and install the Remote Server Administration tools. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ #Declare variables

+ $ipaddress = "10.0.1.117"

+ $ipprefix = "24"

+ $ipgw = "10.0.1.1"

+ $ipdns = "10.0.1.117"

+ $ipdns2 = "8.8.8.8"

+ $ipif = (Get-NetAdapter).ifIndex

+ $featureLogPath = "c:\poshlog\featurelog.txt"

+ $newname = "DC1"

+ $addsTools = "RSAT-AD-Tools"

+ #Set static IP address

+ New-NetIPAddress -IPAddress $ipaddress -PrefixLength $ipprefix -InterfaceIndex $ipif -DefaultGateway $ipgw

+ # Set the DNS servers

+ Set-DnsClientServerAddress -InterfaceIndex $ipif -ServerAddresses ($ipdns, $ipdns2)

+ #Rename the computer

+ Rename-Computer -NewName $newname -force

+ #Install features

+ New-Item $featureLogPath -ItemType file -Force

+ Add-WindowsFeature $addsTools

+ Get-WindowsFeature | Where installed >>$featureLogPath

+ #Restart the computer

+ Restart-Computer

+ ```

+## Create a Windows Server AD environment

+Now that you have the VM created and it has been renamed and has a static IP address, you can go ahead and install and configure Active Directory Domain Services. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ #Declare variables

+ $DatabasePath = "c:\windows\NTDS"

+ $DomainMode = "WinThreshold"

+ $DomainName = "contoso.com"

+ $DomaninNetBIOSName = "CONTOSO"

+ $ForestMode = "WinThreshold"

+ $LogPath = "c:\windows\NTDS"

+ $SysVolPath = "c:\windows\SYSVOL"

+ $featureLogPath = "c:\poshlog\featurelog.txt"

+ $Password = "Pass1w0rd"

+ $SecureString = ConvertTo-SecureString $Password -AsPlainText -Force

+ #Install AD DS, DNS and GPMC

+ start-job -Name addFeature -ScriptBlock {

+ Add-WindowsFeature -Name "ad-domain-services" -IncludeAllSubFeature -IncludeManagementTools

+ Add-WindowsFeature -Name "dns" -IncludeAllSubFeature -IncludeManagementTools

+ Add-WindowsFeature -Name "gpmc" -IncludeAllSubFeature -IncludeManagementTools }

+ Wait-Job -Name addFeature

+ Get-WindowsFeature | Where installed >>$featureLogPath

+ #Create New AD Forest

+ Install-ADDSForest -CreateDnsDelegation:$false -DatabasePath $DatabasePath -DomainMode $DomainMode -DomainName $DomainName -SafeModeAdministratorPassword $SecureString -DomainNetbiosName $DomainNetBIOSName -ForestMode $ForestMode -InstallDns:$true -LogPath $LogPath -NoRebootOnCompletion:$false -SysvolPath $SysVolPath -Force:$true

+ ```

+## Create a Windows Server AD user

+Now that you have our Active Directory environment, you need to a test account. This account will be created in our on-premises AD environment and then synchronized to Azure AD. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ # Filename: 4_CreateUser.ps1

+ # Description: Creates a user in Active Directory. This is part of

+ # the Azure AD Connect password hash sync tutorial.

+ #

+ # DISCLAIMER:

+ # Copyright (c) Microsoft Corporation. All rights reserved. This

+ # script is made available to you without any express, implied or

+ # statutory warranty, not even the implied warranty of

+ # merchantability or fitness for a particular purpose, or the

+ # warranty of title or non-infringement. The entire risk of the

+ # use or the results from the use of this script remains with you.

+ #

+ #

+ #

+ #

+ #Declare variables

+ $Givenname = "Allie"

+ $Surname = "McCray"

+ $Displayname = "Allie McCray"

+ $Name = "amccray"

+ $Password = "Pass1w0rd"

+ $Identity = "CN=ammccray,CN=Users,DC=contoso,DC=com"

+ $SecureString = ConvertTo-SecureString $Password -AsPlainText -Force

+ #Create the user

+ New-ADUser -Name $Name -GivenName $Givenname -Surname $Surname -DisplayName $Displayname -AccountPassword $SecureString

+ #Set the password to never expire

+ Set-ADUser -Identity $Identity -PasswordNeverExpires $true -ChangePasswordAtLogon $false -Enabled $true

+ ```

+## Create an Azure AD tenant

+Now you need to create an Azure AD tenant so that you can synchronize our users to the cloud. To create a new Azure AD tenant, do the following.

+1. Browse to the [Azure portal](https://portal.azure.com) and sign in with an account that has an Azure subscription.

+2. Select the **plus icon (+)** and search for **Azure Active Directory**.

+3. Select **Azure Active Directory** in the search results.

+4. Select **Create**.</br>

+</br>

+5. Provide a **name for the organization** along with the **initial domain name**. Then select **Create**. This will create your directory.

+6. Once this has completed, click the **here** link, to manage the directory.

+## Create a global administrator in Azure AD

+Now that you have an Azure AD tenant, you'll create a global administrator account. To create the global administrator account do the following.

+1. Under **Manage**, select **Users**.</br>

+</br>

+2. Select **All users** and then select **+ New user**.

+3. Provide a name and username for this user. This will be your Global Administrator for the tenant. You'll also want to change the **Directory role** to **Global administrator.** You can also show the temporary password. When you're done, select **Create**.</br>

+</br>

+4. Once this has completed, open a new web browser and sign-in to myapps.microsoft.com using the new global administrator account and the temporary password.

+5. Change the password for the global administrator to something that you'll remember.

+## Optional: Additional server and forest

+The following is an optional section that provides steps to creating an additional server and or forest. This can be used in some of the more advanced tutorials such as [Pilot for Azure AD Connect to cloud sync](tutorial-pilot-aadc-aadccp.md).

+If you only need an additional server, you can stop after the - **Create the virtual machine** step and join the server to the existing domain that was created above.

+### Create a virtual machine

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ # Filename: 1_CreateVM_CP.ps1

+ # Description: Creates a VM to be used in the tutorial.

+ #

+ # DISCLAIMER:

+ # Copyright (c) Microsoft Corporation. All rights reserved. #This script is made available to you without any express, implied or statutory warranty, not even the implied warranty of merchantability or fitness for a particular purpose, or the warranty of title or non-infringement. The entire risk of the use or the results from the use of this script remains with you.

+ #

+ #

+ #

+ #

+ #Declare variables

+ $VMName = 'CP1'

+ $Switch = 'External'

+ $InstallMedia = 'D:\ISO\en_windows_server_2016_updated_feb_2018_x64_dvd_11636692.iso'

+ $Path = 'D:\VM'

+ $VHDPath = 'D:\VM\CP1\CP1.vhdx'

+ $VHDSize = '64424509440'

+ #Create New Virtual Machine

+ New-VM -Name $VMName -MemoryStartupBytes 16GB -BootDevice VHD -Path $Path -NewVHDPath $VHDPath -NewVHDSizeBytes $VHDSize -Generation 2 -Switch $Switch

+ #Set the memory to be non-dynamic

+ Set-VMMemory $VMName -DynamicMemoryEnabled $false

+ #Add DVD Drive to Virtual Machine

+ Add-VMDvdDrive -VMName $VMName -ControllerNumber 0 -ControllerLocation 1 -Path $InstallMedia

+ #Mount Installation Media

+ $DVDDrive = Get-VMDvdDrive -VMName $VMName

+ #Configure Virtual Machine to Boot from DVD

+ Set-VMFirmware -VMName $VMName -FirstBootDevice $DVDDrive

+ ```

+### Complete the operating system deployment

+In order to finish building the virtual machine, you need to finish the operating system installation.

+1. Hyper-V Manager, double-click on the virtual machine

+2. Click on the Start button.

+3. You'll be prompted to ΓÇÿPress any key to boot from CD or DVDΓÇÖ. Go ahead and do so.

+4. On the Windows Server start up screen select your language and click **Next**.

+5. Click **Install Now**.

+6. Enter your license key and click **Next**.

+7. Check **I accept the license terms and click **Next**.

+8. Select **Custom: Install Windows Only (Advanced)**

+9. Click **Next**

+10. Once the installation has completed, restart the virtual machine, sign-in and run Windows updates to ensure the VM is the most up-to-date. Install the latest updates.

+### Install Active Directory prerequisites

+Now that you have a virtual machine up, you need to do a few things prior to installing Active Directory. That is, you need to rename the virtual machine, set a static IP address and DNS information, and install the Remote Server Administration tools. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ # Filename: 2_ADPrep_CP.ps1

+ # Description: Prepares your environment for Active Directory. This is part of

+ # the Azure AD Connect password hash sync tutorial.

+ #

+ # DISCLAIMER:

+ # Copyright (c) Microsoft Corporation. All rights reserved. This

+ # script is made available to you without any express, implied or

+ # statutory warranty, not even the implied warranty of

+ # merchantability or fitness for a particular purpose, or the

+ # warranty of title or non-infringement. The entire risk of the

+ # use or the results from the use of this script remains with you.

+ #

+ #

+ #

+ #

+ #Declare variables

+ $ipaddress = "10.0.1.118"

+ $ipprefix = "24"

+ $ipgw = "10.0.1.1"

+ $ipdns = "10.0.1.118"

+ $ipdns2 = "8.8.8.8"

+ $ipif = (Get-NetAdapter).ifIndex

+ $featureLogPath = "c:\poshlog\featurelog.txt"

+ $newname = "CP1"

+ $addsTools = "RSAT-AD-Tools"

+ #Set static IP address

+ New-NetIPAddress -IPAddress $ipaddress -PrefixLength $ipprefix -InterfaceIndex $ipif -DefaultGateway $ipgw

+ #Set the DNS servers

+ Set-DnsClientServerAddress -InterfaceIndex $ipif -ServerAddresses ($ipdns, $ipdns2)

+ #Rename the computer

+ Rename-Computer -NewName $newname -force

+ #Install features

+ New-Item $featureLogPath -ItemType file -Force

+ Add-WindowsFeature $addsTools

+ Get-WindowsFeature | Where installed >>$featureLogPath

+ #Restart the computer

+ Restart-Computer

+ ```

+### Create a Windows Server AD environment

+Now that you have the VM created and it has been renamed and has a static IP address, you can go ahead and install and configure Active Directory Domain Services. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ # Filename: 3_InstallAD_CP.ps1

+ # Description: Creates an on-premises AD environment. This is part of

+ # the Azure AD Connect password hash sync tutorial.

+ #

+ # DISCLAIMER:

+ # Copyright (c) Microsoft Corporation. All rights reserved. This

+ # script is made available to you without any express, implied or

+ # statutory warranty, not even the implied warranty of

+ # merchantability or fitness for a particular purpose, or the

+ # warranty of title or non-infringement. The entire risk of the

+ # use or the results from the use of this script remains with you.

+ #

+ #

+ #

+ #

+ #Declare variables

+ $DatabasePath = "c:\windows\NTDS"

+ $DomainMode = "WinThreshold"

+ $DomainName = "fabrikam.com"

+ $DomaninNetBIOSName = "FABRIKAM"

+ $ForestMode = "WinThreshold"

+ $LogPath = "c:\windows\NTDS"

+ $SysVolPath = "c:\windows\SYSVOL"

+ $featureLogPath = "c:\poshlog\featurelog.txt"

+ $Password = "Pass1w0rd"

+ $SecureString = ConvertTo-SecureString $Password -AsPlainText -Force

+ #Install AD DS, DNS and GPMC

+ start-job -Name addFeature -ScriptBlock {

+ Add-WindowsFeature -Name "ad-domain-services" -IncludeAllSubFeature -IncludeManagementTools

+ Add-WindowsFeature -Name "dns" -IncludeAllSubFeature -IncludeManagementTools

+ Add-WindowsFeature -Name "gpmc" -IncludeAllSubFeature -IncludeManagementTools }

+ Wait-Job -Name addFeature

+ Get-WindowsFeature | Where installed >>$featureLogPath

+ #Create New AD Forest

+ Install-ADDSForest -CreateDnsDelegation:$false -DatabasePath $DatabasePath -DomainMode $DomainMode -DomainName $DomainName -SafeModeAdministratorPassword $SecureString -DomainNetbiosName $DomainNetBIOSName -ForestMode $ForestMode -InstallDns:$true -LogPath $LogPath -NoRebootOnCompletion:$false -SysvolPath $SysVolPath -Force:$true

+ ```

+### Create a Windows Server AD user

+Now that you have our Active Directory environment, you need to a test account. This account will be created in our on-premises AD environment and then synchronized to Azure AD. Do the following:

+1. Open up the PowerShell ISE as Administrator.

+2. Run the following script.

+ ```powershell

+ # Filename: 4_CreateUser_CP.ps1

+ # Description: Creates a user in Active Directory. This is part of

+ # the Azure AD Connect password hash sync tutorial.

+ #

+ # DISCLAIMER:

+ # Copyright (c) Microsoft Corporation. All rights reserved. This

+ # script is made available to you without any express, implied or

+ # statutory warranty, not even the implied warranty of

+ # merchantability or fitness for a particular purpose, or the

+ # warranty of title or non-infringement. The entire risk of the

+ # use or the results from the use of this script remains with you.

+ #

+ #

+ #

+ #

+ #Declare variables

+ $Givenname = "Anna"

+ $Surname = "Ringdal"

+ $Displayname = "Anna Ringdal"

+ $Name = "aringdal"

+ $Password = "Pass1w0rd"

+ $Identity = "CN=aringdal,CN=Users,DC=fabrikam,DC=com"

+ $SecureString = ConvertTo-SecureString $Password -AsPlainText -Force

+ #Create the user

+ New-ADUser -Name $Name -GivenName $Givenname -Surname $Surname -DisplayName $Displayname -AccountPassword $SecureString

+ #Set the password to never expire

+ Set-ADUser -Identity $Identity -PasswordNeverExpires $true -ChangePasswordAtLogon $false -Enabled $true

+ ```

+## Conclusion

+Now you have an environment that can be used for existing tutorials and to test additional features cloud sync provides.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Tutorial - Integrate an existing forest and a new forest with a single Azure AD tenant using Azure AD Connect cloud sync.

+description: Learn how to add cloud sync to an existing hybrid identity environment.

+# Integrate an existing forest and a new forest with a single Azure AD tenant

+This tutorial walks you through adding cloud sync to an existing hybrid identity environment.

+

+You can use the environment you create in this tutorial for testing or for getting more familiar with how a hybrid identity works.

+In this scenario, there's an existing forest synced using Azure AD Connect sync to an Azure AD tenant. And you have a new forest that you want to sync to the same Azure AD tenant. You'll set up cloud sync for the new forest.

+## Prerequisites

+### In the Azure portal

+1. Create a cloud-only global administrator account on your Azure AD tenant. This way, you can manage the configuration of your tenant should your on-premises services fail or become unavailable. Learn about [adding a cloud-only global administrator account](../../fundamentals/add-users-azure-active-directory.md). Completing this step is critical to ensure that you don't get locked out of your tenant.

+2. Add one or more [custom domain names](../../fundamentals/add-custom-domain.md) to your Azure AD tenant. Your users can sign in with one of these domain names.

+### In your on-premises environment

+1. Identify a domain-joined host server running Windows Server 2012 R2 or greater with minimum of 4-GB RAM and .NET 4.7.1+ runtime

+2. If there's a firewall between your servers and Azure AD, configure the following items:

+ - Ensure that agents can make *outbound* requests to Azure AD over the following ports:

+ | Port number | How it's used |

+ | | |

+ | **80** | Downloads the certificate revocation lists (CRLs) while validating the TLS/SSL certificate |

+ | **443** | Handles all outbound communication with the service |

+ | **8080** (optional) | Agents report their status every 10 minutes over port 8080, if port 443 is unavailable. This status is displayed on the Azure portal. |

+

+ If your firewall enforces rules according to the originating users, open these ports for traffic from Windows services that run as a network service.

+ - If your firewall or proxy allows you to specify safe suffixes, then add connections to **\*.msappproxy.net** and **\*.servicebus.windows.net**. If not, allow access to the [Azure datacenter IP ranges](https://www.microsoft.com/download/details.aspx?id=41653), which are updated weekly.

+ - Your agents need access to **login.windows.net** and **login.microsoftonline.com** for initial registration. Open your firewall for those URLs as well.

+ - For certificate validation, unblock the following URLs: **mscrl.microsoft.com:80**, **crl.microsoft.com:80**, **ocsp.msocsp.com:80**, and **www\.microsoft.com:80**. Since these URLs are used for certificate validation with other Microsoft products, you may already have these URLs unblocked.

+## Install the Azure AD Connect provisioning agent

+If you're using the [Basic AD and Azure environment](tutorial-basic-ad-azure.md) tutorial, it would be DC1. To install the agent, follow these steps:

+## Verify agent installation

+## Configure Azure AD Connect cloud sync

+ Use the following steps to configure provisioning

+1. Sign in to the Azure portal.

+2. Select **Azure Active Directory**

+3. Select **Azure AD Connect**

+4. Select **Manage cloud sync**

+ 

+5. Select **New Configuration**

+ 

+7. On the configuration screen, enter a **Notification email**, move the selector to **Enable** and select **Save**.

+ 

+1. The configuration status should now be **Healthy**.

+ 

+## Verify users are created and synchronization is occurring

+You'll now verify that the users that you had in our on-premises directory have been synchronized and now exist in our Azure AD tenant. This process may take a few hours to complete. To verify users are synchronized, do the following:

+1. Browse to the [Azure portal](https://portal.azure.com) and sign in with an account that has an Azure subscription.

+2. On the left, select **Azure Active Directory**

+3. Under **Manage**, select **Users**.

+4. Verify that you see the new users in our tenant

+## Test signing in with one of our users

+1. Browse to [https://myapps.microsoft.com](https://myapps.microsoft.com)

+2. Sign in with a user account that was created in our new tenant. You'll need to sign in using the following format: (user@domain.onmicrosoft.com). Use the same password that the user uses to sign in on-premises.

+ 

+You have now successfully set up a hybrid identity environment that you can use to test and familiarize yourself with what Azure has to offer.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Tutorial - Migrate to Azure AD Connect cloud sync for an existing synced AD forest

+description: Learn how to pilot cloud sync for a test Active Directory forest that is already synced using Azure Active Directory (Azure AD) Connect sync.

+# Migrate to Azure AD Connect cloud sync for an existing synced AD forest

+This tutorial walks you through how you would migrate to cloud sync for a test Active Directory forest that is already synced using Azure Active Directory (Azure AD) Connect sync.

+> [!NOTE]

+> This article provides information for a basic migration and you should review the [Migrating to cloud sync](migrate-azure-ad-connect-to-cloud-sync.md) documentation before attempting to migrate your production environment.

+

+## Considerations

+Before you try this tutorial, consider the following items:

+ 1. Ensure that you're familiar with basics of cloud sync.

+ 2. Ensure that you're running Azure AD Connect sync version 1.4.32.0 or later and have configured the sync rules as documented.

+ 3. When piloting, you'll be removing a test OU or group from Azure AD Connect sync scope. Moving objects out of scope leads to deletion of those objects in Azure AD.

+ - User objects, the objects in Azure AD are soft-deleted and can be restored.

+ - Group objects, the objects in Azure AD are hard-deleted and can't be restored.

+

+ A new link type has been introduced in Azure AD Connect sync, which will prevent the deletion in a piloting scenario.

+ 4. Ensure that the objects in the pilot scope have ms-ds-consistencyGUID populated so cloud sync hard matches the objects.

+ > [!NOTE]

+ > Azure AD Connect sync does not populate *ms-ds-consistencyGUID* by default for group objects.

+ 5. This configuration is for advanced scenarios. Ensure that you follow the steps documented in this tutorial precisely.

+## Prerequisites

+The following are prerequisites required for completing this tutorial

+- A test environment with Azure AD Connect sync version 1.4.32.0 or later

+- An OU or group that is in scope of sync and can be used the pilot. We recommend starting with a small set of objects.

+- A server running Windows Server 2016 or later that will host the provisioning agent.

+- Source anchor for Azure AD Connect sync should be either *objectGuid* or *ms-ds-consistencyGUID*

+## Update Azure AD Connect

+As a minimum, you should have [Azure AD connect](https://www.microsoft.com/download/details.aspx?id=47594) 1.4.32.0. To update Azure AD Connect sync, complete the steps in [Azure AD Connect: Upgrade to the latest version](../connect/how-to-upgrade-previous-version.md).

+## Back up your Azure AD Connect configuration

+Before making any changes, you should back up your Azure AD Connect configuration. This way, you can roll back to your previous configuration. See [Import and export Azure AD Connect configuration settings](../connect/how-to-connect-import-export-config.md) for more information.

+## Stop the scheduler

+Azure AD Connect sync synchronizes changes occurring in your on-premises directory using a scheduler. In order to modify and add custom rules, you want to disable the scheduler so that synchronizations won't run while you're working making the changes. To stop the scheduler, use the following steps:

+1. On the server that is running Azure AD Connect sync open PowerShell with Administrative Privileges.

+2. Run `Stop-ADSyncSyncCycle`. Hit Enter.

+3. Run `Set-ADSyncScheduler -SyncCycleEnabled $false`.

+>[!NOTE]

+>If you are running your own custom scheduler for Azure AD Connect sync, then please disable the scheduler.

+## Create custom user inbound rule

+In the Azure AD Connect Synchronization Rules editor, you need to create an inbound sync rule that filters out users in the OU you identified previously. The inbound sync rule is a join rule with a target attribute of cloudNoFlow. This rule tells Azure AD Connect not to synchronize attributes for these users. For more information, see [Migrating to cloud sync](migrate-azure-ad-connect-to-cloud-sync.md) documentation before attempting to migrate your production environment.

+ 1. Launch the synchronization editor from the application menu in desktop as shown below:

+

+ 

+ 2. Select **Inbound** from the drop-down list for Direction and select **Add new rule**.

+ 

+ 3. On the **Description** page, enter the following and select **Next**:

+ - **Name:** Give the rule a meaningful name

+ - **Description:** Add a meaningful description

+ - **Connected System:** Choose the AD connector that you're writing the custom sync rule for

+ - **Connected System Object Type:** User

+ - **Metaverse Object Type:** Person

+ - **Link Type:** Join

+ - **Precedence:** Provide a value that is unique in the system

+ - **Tag:** Leave this empty

+ 

+ 4. On the **Scoping filter** page, enter the OU or security group that you want the pilot based off. To filter on OU, add the OU portion of the distinguished name. This rule will be applied to all users who are in that OU. So, if DN ends with "OU=CPUsers,DC=contoso,DC=com, you would add this filter. Then select **Next**.

+ |Rule|Attribute|Operator|Value|

+ |--|-|-|--|

+ |Scoping OU|DN|ENDSWITH|Distinguished name of the OU.|

+ |Scoping group||ISMEMBEROF|Distinguished name of the security group.|

+ 

+ 5. On the **Join** rules page, select **Next**.

+ 6. On the **Transformations** page, add a Constant transformation: flow True to cloudNoFlow attribute. Select **Add**.

+ 

+Same steps need to be followed for all object types (user, group and contact). Repeat steps per configured AD Connector / per AD forest.

+## Create custom user outbound rule

+You'll also need an outbound sync rule with a link type of JoinNoFlow and the scoping filter that has the cloudNoFlow attribute set to True. This rule tells Azure AD Connect not to synchronize attributes for these users. For more information, see [Migrating to cloud sync](migrate-azure-ad-connect-to-cloud-sync.md) documentation before attempting to migrate your production environment.

+ 1. Select **Outbound** from the drop-down list for Direction and select **Add rule**.

+ 

+ 2. On the **Description** page, enter the following and select **Next**:

+ - **Name:** Give the rule a meaningful name

+ - **Description:** Add a meaningful description

+ - **Connected System:** Choose the Azure AD connector that you're writing the custom sync rule for

+ - **Connected System Object Type:** User

+ - **Metaverse Object Type:** Person

+ - **Link Type:** JoinNoFlow

+ - **Precedence:** Provide a value that is unique in the system<br>

+ - **Tag:** Leave this empty

+ 

+ 3. On the **Scoping filter** page, choose **cloudNoFlow** equal **True**. Then select **Next**.

+ 

+ 4. On the **Join** rules page, select **Next**.

+ 5. On the **Transformations** page, select **Add**.

+Same steps need to be followed for all object types (user, group and contact).

+## Install the Azure AD Connect provisioning agent

+If you're using the [Basic AD and Azure environment](tutorial-basic-ad-azure.md) tutorial, it would be CP1. To install the agent, follow these steps:

+## Verify agent installation

+## Configure Azure AD Connect cloud sync

+Use the following steps to configure provisioning:

+ 1. In the Azure portal, select **Azure Active Directory**.

+ 2. On the left, select **Azure AD Connect**.

+ 3. On the left, select **Cloud sync**.

+

+ :::image type="content" source="media/how-to-on-demand-provision/new-ux-1.png" alt-text="Screenshot of new UX cloud sync screen." lightbox="media/how-to-on-demand-provision/new-ux-1.png":::

+

+ 4. Select **New configuration**.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-1.png" alt-text="Screenshot of adding a configuration." lightbox="media/how-to-configure/new-ux-configure-1.png":::

+ 5. On the configuration screen, select your domain and whether to enable password hash sync. Click **Create**.

+

+ :::image type="content" source="media/how-to-configure/new-ux-configure-2.png" alt-text="Screenshot of a new configuration." lightbox="media/how-to-configure/new-ux-configure-2.png":::

+ 6. The **Get started** screen will open.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-3.png" alt-text="Screenshot of the getting started screen." lightbox="media/how-to-configure/new-ux-configure-3.png":::

+ 7. On the **Get started** screen, click either **Add scoping filters** next to the **Add scoping filters** icon or on the click **Scoping filters** on the left under **Manage**.

+ :::image type="content" source="media/how-to-configure/new-ux-configure-5.png" alt-text="Screenshot of scoping filters." lightbox="media/how-to-configure/new-ux-configure-5.png":::

+

+ 8. Select the scoping filter. For this tutorial select:

+ - **Selected organizational units**: Scopes the configuration to apply to specific OUs.

+ 9. In the box, enter "OU=CPUsers,DC=contoso,DC=com".

+

+ :::image type="content" source="media/tutorial-migrate-aadc-aadccp/configure-1.png" alt-text="Screenshot of the scoping filter." lightbox="media/tutorial-migrate-aadc-aadccp/configure-1.png":::

+

+ 10. Click **Add**. Click **Save**.

+

+## Start the scheduler

+Azure AD Connect sync synchronizes changes occurring in your on-premises directory using a scheduler. Now that you've modified the rules, you can restart the scheduler. Use the following steps:

+1. On the server that is running Azure AD Connect sync open PowerShell with Administrative Privileges

+2. Run `Set-ADSyncScheduler -SyncCycleEnabled $true`.

+3. Run `Start-ADSyncSyncCycle`, then press <kbd>Enter</kbd>.

+> [!NOTE]

+> If you are running your own custom scheduler for Azure AD Connect sync, then please enable the scheduler.

+Once the scheduler is enabled, Azure AD Connect will stop exporting any changes on objects with `cloudNoFlow=true` in the metaverse, unless any reference attribute (such as `manager`) is being updated. In case there's any reference attribute update on the object, Azure AD Connect will ignore the `cloudNoFlow` signal and export all updates on the object.

+## Something went wrong

+In case the pilot doesn't work as expected, you can go back to the Azure AD Connect sync setup by following the steps below:

+1. Disable provisioning configuration in the Azure portal.

+2. Disable all the custom sync rules created for Cloud Provisioning using the Sync Rule Editor tool. Disabling should cause full sync on all the connectors.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud sync?](what-is-cloud-sync.md)

+ Title: Tutorial - Integrate a single forest with a single Azure AD tenant

+description: This topic describes the pre-requisites and the hardware requirements cloud sync.

+# Tutorial: Integrate a single forest with a single Azure AD tenant

+This tutorial walks you through creating a hybrid identity environment using Azure Active Directory (Azure AD) Connect cloud sync.

+

+You can use the environment you create in this tutorial for testing or for getting more familiar with cloud sync.

+## Prerequisites

+### In the Azure portal

+1. Create a cloud-only global administrator account on your Azure AD tenant. This way, you can manage the configuration of your tenant should your on-premises services fail or become unavailable. Learn about [adding a cloud-only global administrator account](../../fundamentals/add-users-azure-active-directory.md). Completing this step is critical to ensure that you don't get locked out of your tenant.

+2. Add one or more [custom domain names](../../fundamentals/add-custom-domain.md) to your Azure AD tenant. Your users can sign in with one of these domain names.

+### In your on-premises environment

+1. Identify a domain-joined host server running Windows Server 2016 or greater with minimum of 4-GB RAM and .NET 4.7.1+ runtime

+2. If there's a firewall between your servers and Azure AD, configure the following items:

+ - Ensure that agents can make *outbound* requests to Azure AD over the following ports:

+ | Port number | How it's used |

+ | | |

+ | **80** | Downloads the certificate revocation lists (CRLs) while validating the TLS/SSL certificate |

+ | **443** | Handles all outbound communication with the service |

+ | **8080** (optional) | Agents report their status every 10 minutes over port 8080, if port 443 is unavailable. This status is displayed on the Azure portal. |

+

+ If your firewall enforces rules according to the originating users, open these ports for traffic from Windows services that run as a network service.

+ - If your firewall or proxy allows you to specify safe suffixes, then add connections t to **\*.msappproxy.net** and **\*.servicebus.windows.net**. If not, allow access to the [Azure datacenter IP ranges](https://www.microsoft.com/download/details.aspx?id=41653), which are updated weekly.

+ - Your agents need access to **login.windows.net** and **login.microsoftonline.com** for initial registration. Open your firewall for those URLs as well.

+ - For certificate validation, unblock the following URLs: **mscrl.microsoft.com:80**, **crl.microsoft.com:80**, **ocsp.msocsp.com:80**, and **www\.microsoft.com:80**. Since these URLs are used for certificate validation with other Microsoft products, you may already have these URLs unblocked.

+## Install the Azure AD Connect provisioning agent

+If you're using the [Basic AD and Azure environment](tutorial-basic-ad-azure.md) tutorial, it would be DC1. To install the agent, follow these steps:

+## Verify agent installation

+## Configure Azure AD Connect cloud sync

+Use the following steps to configure and start the provisioning:

+1. Sign in to the Azure portal.

+1. Select **Azure Active Directory**

+1. Select **Azure AD Connect**

+1. Select **Manage cloud sync**

+ 

+1. Select **New Configuration**

+

+ [](media/tutorial-single-forest/configure-1.png#lightbox)

+1. On the configuration screen, enter a **Notification email**, move the selector to **Enable** and select **Save**.

+ [](media/how-to-configure/configure-2.png#lightbox)

+1. The configuration status should now be **Healthy**.

+ [](media/how-to-configure/manage-4.png#lightbox)

+## Verify users are created and synchronization is occurring

+You'll now verify that the users that you had in your on-premises directory have been synchronized and now exist in your Azure AD tenant. The sync operation may take a few hours to complete. To verify users are synchronized, follow these steps:

+1. Browse to the [Azure portal](https://portal.azure.com) and sign in with an account that has an Azure subscription.

+2. On the left, select **Azure Active Directory**

+3. Under **Manage**, select **Users**.

+4. Verify that the new users appear in your tenant

+## Test signing in with one of your users

+1. Browse to [https://myapps.microsoft.com](https://myapps.microsoft.com)

+1. Sign in with a user account that was created in your tenant. You'll need to sign in using the following format: (user@domain.onmicrosoft.com). Use the same password that the user uses to sign in on-premises.

+ 

+You've now successfully configured a hybrid identity environment using Azure AD Connect cloud sync.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [What is Azure AD Connect cloud provisioning?](what-is-cloud-sync.md)

+ Title: 'What is Azure AD Connect cloud sync?'

+description: Describes Azure AD Connect cloud sync.

+# What is Azure AD Connect cloud sync?

+Azure AD Connect cloud sync is a new offering from Microsoft designed to meet and accomplish your hybrid identity goals for synchronization of users, groups, and contacts to Azure AD. It accomplishes this by using the Azure AD cloud provisioning agent instead of the Azure AD Connect application. However, it can be used alongside Azure AD Connect sync and it provides the following benefits:

+

+- Support for synchronizing to an Azure AD tenant from a multi-forest disconnected Active Directory forest environment: The common scenarios include merger & acquisition (where the acquired company's AD forests are isolated from the parent company's AD forests), and companies that have historically had multiple AD forests.

+- Simplified installation with light-weight provisioning agents: The agents act as a bridge from AD to Azure AD, with all the sync configuration managed in the cloud.

+- Multiple provisioning agents can be used to simplify high availability deployments, particularly critical for organizations relying upon password hash synchronization from AD to Azure AD.

+- Support for large groups with up to 50,000 members. It's recommended to use only the OU scoping filter when synchronizing large groups.

+

+## How is Azure AD Connect cloud sync different from Azure AD Connect sync?

+With Azure AD Connect cloud sync, provisioning from AD to Azure AD is orchestrated in Microsoft Online Services. An organization only needs to deploy, in their on-premises or IaaS-hosted environment, a light-weight agent that acts as a bridge between Azure AD and AD. The provisioning configuration is stored in Azure AD and managed as part of the service.

+## Azure AD Connect cloud sync video

+The following short video provides an excellent overview of Azure AD Connect cloud sync:

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWJ8l5]

+## Comparison between Azure AD Connect and cloud sync

+The following table provides a comparison between Azure AD Connect and Azure AD Connect cloud sync:

+| Feature | Azure Active Directory Connect sync| Azure Active Directory Connect cloud sync |

+|: |::|::|

+|Connect to single on-premises AD forest|ΓùÅ |ΓùÅ |

+| Connect to multiple on-premises AD forests |ΓùÅ |ΓùÅ |

+| Connect to multiple disconnected on-premises AD forests | |ΓùÅ |

+| Lightweight agent installation model | |ΓùÅ |

+| Multiple active agents for high availability | |ΓùÅ |

+| Connect to LDAP directories|ΓùÅ| |

+| Support for user objects |ΓùÅ |ΓùÅ |

+| Support for group objects |ΓùÅ |ΓùÅ |

+| Support for contact objects |ΓùÅ |ΓùÅ |

+| Support for device objects |ΓùÅ | |

+| Allow basic customization for attribute flows |ΓùÅ |ΓùÅ |

+| Synchronize Exchange online attributes |ΓùÅ |ΓùÅ |

+| Synchronize extension attributes 1-15 |ΓùÅ |ΓùÅ |

+| Synchronize customer defined AD attributes (directory extensions) |ΓùÅ|ΓùÅ|

+| Support for Password Hash Sync |ΓùÅ|ΓùÅ|

+| Support for Pass-Through Authentication |ΓùÅ||

+| Support for federation |ΓùÅ|ΓùÅ|

+| Seamless Single Sign-on|ΓùÅ |ΓùÅ|

+| Supports installation on a Domain Controller |ΓùÅ |ΓùÅ |

+| Support for Windows Server 2016|ΓùÅ |ΓùÅ |

+| Filter on Domains/OUs/groups |ΓùÅ |ΓùÅ |

+| Filter on objects' attribute values |ΓùÅ | |

+| Allow minimal set of attributes to be synchronized (MinSync) |ΓùÅ |ΓùÅ |

+| Allow removing attributes from flowing from AD to Azure AD |ΓùÅ |ΓùÅ |

+| Allow advanced customization for attribute flows |ΓùÅ | |

+| Support for password writeback |ΓùÅ |ΓùÅ |

+| Support for device writeback|ΓùÅ |Customers should use [Cloud Kerberos trust](/windows/security/identity-protection/hello-for-business/hello-hybrid-cloud-kerberos-trust?tabs=intune) for this moving forward|

+| Support for group writeback|ΓùÅ | |

+| Support for merging user attributes from multiple domains|ΓùÅ | |

+| Azure AD Domain Services support|ΓùÅ | |

+| [Exchange hybrid writeback](../connect/reference-connect-sync-attributes-synchronized.md#exchange-hybrid-writeback) |ΓùÅ | |

+| Unlimited number of objects per AD domain |ΓùÅ | |

+| Support for up to 150,000 objects per AD domain |ΓùÅ |ΓùÅ |

+| Groups with up to 50,000 members |ΓùÅ |ΓùÅ |

+| Large groups with up to 250,000 members |ΓùÅ | |

+| Cross domain references|ΓùÅ |ΓùÅ |

+| On-demand provisioning| |ΓùÅ |

+| Support for US Government|ΓùÅ |ΓùÅ |

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [Install cloud sync](how-to-install.md)

+ Title: 'What is the provisioning agent?'

+description: This article describes the provisioning agent used by cloud sync and on-premsises app provisioning.

+documentationcenter: ''

+editor: ''

+ na

+# What is the Azure AD provisioning agent?

+The provisioning agent is the synchronization tool that is used to deliver several features for use with Azure AD and is managed from the cloud.

+The provisioning agent provides connectivity between Azure Active Directory (Azure AD) and your on-premises environment.

+ These features include:

+ - cloud sync

+ - on-premises app provisioning

+## How it works

+The provisioning agent uses SCIM ([System for Cross-domain Identity Management (SCIM) 2.0](https://techcommunity.microsoft.com/t5/identity-standards-blog/provisioning-with-scim-getting-started/ba-p/880010)). The SCIM specification provides a common user schema to help users move into, out of, and around apps. SCIM is becoming the de facto standard for provisioning and, when used in conjunction with federation standards like SAML or OpenID Connect, provides administrators an end-to-end standards-based solution for access management.

+## Next steps

+- [What is provisioning?](../what-is-provisioning.md)

+- [Install cloud sync](how-to-install.md)

+ Title: 'Common hybrid scenarios with Azure AD'

+description: This article describes the common scenarios for using Azure AD Connect cloud sync and Azure AD Connect.

+documentationcenter: ''

+editor: ''

+ na

+# Hybrid scenarios

+The following document describes the common and supported hybrid sync scenarios.

+## Supported sync scenarios

+The following table outlines the most common and supported sync scenarios.

+|Scenario|Supported with cloud sync|Supported with connect sync|Supported with MIM and the Graph Connector|Supported with ECMA Host connector|

+|--|--|--|--|--|

+|New Hybrid customers managing identities|ΓùÅ|ΓùÅ|ΓùÅ|N/A|

+|Mergers and acquisitions (disconnected forest)|ΓùÅ|N/A|ΓùÅ|N/A|

+|High availability - latency (I need high availability)|ΓùÅ|N/A|ΓùÅ|N/A|

+|Migration from connect sync to cloud sync|ΓùÅ|ΓùÅ|N/A|N/A|

+|Hybrid Azure AD Join|N/A|ΓùÅ|N/A|N/A|

+|Exchange hybrid|N/A|ΓùÅ|N/A|N/A|

+|User accounts in one forest / mailboxes in resource forest|N/A|ΓùÅ|N/A|N/A|

+|Sync large domains with more than 250K objects|N/A|ΓùÅ|ΓùÅ|N/A|

+|Filter directory objects based on attribute values|N/A|ΓùÅ|ΓùÅ|N/A|

+|Windows Hello for Business|N/A|ΓùÅ|N/A|N/A|

+|Synchronize from cloud to on-premises AD|N/A|N/A|ΓùÅ|N/A|

+|Synchronize from cloud to on-premises LDAP|N/A|N/A|ΓùÅ|ΓùÅ|

+|Synchronize from cloud to on-premises SQL|N/A|N/A|ΓùÅ|ΓùÅ|

+For additional information, see [Supported topologies for cloud sync](cloud-sync/plan-cloud-sync-topologies.md) and [Supported topologies for connect sync](connect/plan-connect-topologies.md)

+## Additional information

+- You can sync users & groups from the same domain using Connect Sync and Cloud Sync if:

+ - Scoping filters in each sync is mutually exclusive

+ - If inclusive, donΓÇÖt have the same attributes values clashing (Precedence isnΓÇÖt supported)

+- You can sync users & groups using Connect Sync while using Cloud SyncΓÇÖs net new capabilities (*called out in Roadmap)

+- You can sync objects from a single AD to multiple Azure ADs if writeback capabilities are enabled only in a single Azure AD tenant.

+## Cloud sync and connect sync in parallel

+You can run cloud sync and Azure AD Connect in the same forest. You can use cloud sync to manage your users and groups and use Azure AD Connect for devices, for example. You may decide to do allow cloud sync to handle 80% and use Azure AD Connect for some of your more obscure, 20% scenarios. The tutorial, [Migrate to Azure AD Connect cloud sync for an existing synced AD forest](cloud-sync/tutorial-pilot-aadc-aadccp.md) shows an example of how you would run each.

+## Common authentication methods and scenarios

+Hybrid identity scenarios use one of three authentication methods. The three methods are:

+- **[Password hash synchronization (PHS)](connect/whatis-phs.md)**

+- **[Pass-through authentication (PTA)](connect/how-to-connect-pta.md)**

+- **[Federation (AD FS)](connect/whatis-fed.md)**

+These authentication methods also provide [single-sign on](connect/how-to-connect-sso.md) capabilities. Single-sign on automatically signs your users in when they are on their corporate devices, connected to your corporate network.

+For additional information, see [Choose the right authentication method for your Azure Active Directory hybrid identity solution](connect/choose-ad-authn.md).

+|I need to:|PHS and SSO| PTA and SSO|Federation|

+|--|--|--|--|

+|Sync new user, contact, and group accounts created in my on-premises Active Directory to the cloud automatically.|ΓùÅ| ΓùÅ |ΓùÅ|

+|Set up my tenant for Microsoft 365 hybrid scenarios.|ΓùÅ| ΓùÅ |ΓùÅ|

+|Enable my users to sign in and access cloud services using their on-premises password.|ΓùÅ| ΓùÅ |ΓùÅ|

+|Implement single sign-on using corporate credentials.|ΓùÅ| ΓùÅ |ΓùÅ|

+|Ensure no password hashes are stored in the cloud.| |ΓùÅ|ΓùÅ|

+|Enable cloud-based multi-factor authentication solutions.|ΓùÅ|ΓùÅ|ΓùÅ|

+|Enable on-premises multi-factor authentication solutions.| | |ΓùÅ|

+|Support smartcard authentication for my users.| | |ΓùÅ|

+## Next steps

+- [Tools for synchronization](sync-tools.md)

+- [Choosing the right sync tool](https://setup.microsoft.com/azure/add-or-sync-users-to-azure-ad)

+- [Steps to start](get-started.md)

+- [Prerequisites](prerequisites.md)