Merge branch 'master' of https://github.com/Microsoft/azure-docs-pr into lbmetadataupdate1

Author: KumudD

.openpublishing.redirection.json

@@ -34,6 +34,8 @@
       href: active-directory-b2c-tutorials-desktop-app-webapi.md
     - name: Single page
       href: active-directory-b2c-tutorials-spa-webapi.md
+  - name: Customize the UI
+    href: tutorial-customize-ui.md
 - name: Samples
   href: code-samples.md
 - name: Concepts
@@ -62,6 +64,8 @@
     href: active-directory-b2c-reference-tokens.md
   - name: User accounts
     href: user-overview.md
+  - name: User interface customization
+    href: customize-ui-overview.md
 - name: How-to guides
   items:
   - name: Access audit logs 
@@ -72,11 +76,6 @@
     href: active-directory-b2c-reference-language-customization.md
   - name: Customize password
     href: active-directory-b2c-reference-password-complexity.md
-  - name: Customize user interface
-    href: active-directory-b2c-reference-ui-customization.md
-    items:
-    - name: Helper tool for customization
-      href: active-directory-b2c-reference-ui-customization-helper-tool.md
   - name: Define custom attributes
     href: active-directory-b2c-reference-custom-attr.md
   - name: Disable email verification

articles/active-directory-b2c/TOC.yml

@@ -0,0 +1,119 @@
+---
+title: About user interface customization in Azure Active Directory B2C | Microsoft Docs
+description: Learn about how to customize the user interface for your applications that use Azure Active Directory B2C.
+services: active-directory-b2c
+author: davidmu1
+manager: mtillman
+
+ms.service: active-directory
+ms.workload: identity
+ms.topic: conceptual
+ms.date: 10/30/2018
+ms.author: davidmu
+ms.component: B2C
+---
+
+# About user interface customization in Azure Active Directory B2C
+
+The ability for you to brand and customize the user interface (UI) that Azure Active Directory (Azure AD) B2C serves to your applications is important for providing a seamless experience to your customer. These experiences include sign-up, sign-in, profile editing, and password resetting. This article provides information to help you customize the UI of your applications.
+
+Depending on your needs when it comes to these experiences, you customize the UI of your application in different ways. For example:
+
+- If you're using [built-in policies](active-directory-b2c-reference-policies.md) to provide sign-up or sign-in, password reset, or profile-editing experiences in your application, you use the [Azure portal to customize the UI](tutorial-customize-ui.md).
+- If you're providing sign-in only, its accompanying password reset page, and verification emails, you use the same customization steps that are used for an [Azure AD sign-in page](../active-directory/fundamentals/customize-branding.md).
+- If customers try to edit their profile before they sign in, they are redirected to a page that you customize using the same steps that are used for customizing the Azure AD sign-in page.
+- If you're using [custom policies](active-directory-b2c-overview-custom.md) to provide sign-up or sign-in, password reset, or profile-editing in your application, you use [policy files to customize the UI](active-directory-b2c-ui-customization-custom.md).
+- If you need to provide dynamic content based on a customer’s decision, you use [custom policies that can change page content](active-directory-b2c-ui-customization-custom-dynamic.md) depending on a parameter that's sent in a query string. For example, the background image on the Azure AD B2C sign-up or sign-in page changes, based on a parameter that you pass from your web or mobile application.
+
+Azure AD B2C runs code in your customer's browser and uses a modern approach called [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/). At run-time, content is loaded from a URL that you specify in a policy. You specify different URLs for different pages. After content is loaded from your URL, it's merged with an HTML fragment inserted from Azure AD B2C, and then displayed to your customer.
+
+Before you start, review the following guidance:
+
+- Azure AD B2C merges HTML content into your pages. Don't copy and try to change the default content that Azure AD B2C provides. It's best to build your HTML content from scratch and use the default content as reference.
+- For security reasons, you aren’t allowed to include JavaScript in your content.
+- Supported browser versions are: 
+    - Internet Explorer 11, 10 and Edge
+    - Limited support for Internet Explorer 9 and 8
+    - Google Chrome 42.0 and above
+    - Mozilla Firefox 38.0 and above
+- Make sure that you don't include form tags in your HTML because it interferes with the POST operations generated by the injected HTML from Azure AD B2C.
+
+## Where do I store UI content?
+
+You can host your UI content anywhere, such as on [Azure Blob storage](../storage/blobs/storage-blobs-introduction.md), web servers, CDNs, AWS S3, or file sharing systems. The important point is that you host the content on a publicly available HTTPS endpoint with CORS enabled. You must use an absolute URL when you specify it in your content.
+
+## How do I get started?
+
+You do the following to customize the UI:
+
+- Create well-formed HTML content with an empty `<div id="api"></div>` element located somewhere in the `<body>`. This element marks where the Azure AD B2C content is inserted. The following example shows a minimal page:
+
+    ```html
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>!Add your title here!</title>
+        <link rel="stylesheet" href="https://mystore1.blob.core.windows.net/b2c/style.css">
+      </head>
+      <body>
+        <h1>My B2C Application</h1>
+        <div id="api"></div>   <!-- Leave this element empty because Azure AD B2C will insert content here. -->
+      </body>
+    </html>
+    ```
+
+- Host your content on an HTTPS endpoint (with CORS allowed). Both GET and OPTIONS request methods must be enabled when configuring CORS.
+- Use CSS to style the UI elements that Azure AD B2C inserts into your page. The following example shows a simple CSS file that also includes settings for the sign-up injected HTML elements:
+
+    ```css 
+    h1 {
+      color: blue;
+      text-align: center;
+    }
+    .intro h2 {
+      text-align: center; 
+    }
+    .entry {
+      width: 400px ;
+      margin-left: auto ;
+      margin-right: auto ;
+    }
+    .divider h2 {
+      text-align: center; 
+    }
+    .create {
+      width: 400px ;
+      margin-left: auto ;
+      margin-right: auto ;
+    }
+    ```
+
+- Create or edit a policy to use the content that you created.
+
+The following table lists the HTML fragments that Azure AD B2C merges into the `<div id="api"></div>` element located in your content.
+
+| Inserted page | Description of HTML |
+| ------------- | ------------------- |
+| Identity provider selection | Contains a list of buttons for identity providers that the customer can choose from during sign-up or sign-in. These buttons include social identity providers such as Facebook, Google, or local accounts (based on email address or user name). |
+| Local account sign-up | Contains a form for local account sign-up based on an email address or a user name. The form can contain different input controls such as text input box, password entry box, radio button, single-select drop-down boxes, and multi-select check boxes. |
+| Social account sign-up | May appear when signing up using an existing account from a social identity provider such as Facebook or Google. It’s used when additional information must be collected from the customer using a sign-up form. |
+| Unified sign-up or sign-in | Handles both sign-up and sign-in of customers who can use social identity providers such as Facebook, Google, or local accounts. |
+| Multi-factor authentication | Customers can verify their phone numbers (using text or voice) during sign-up or sign-in. |
+| Error | Provides error information to the customer. |
+
+
+## How do I localize content?
+
+You localize your HTML content by enabling [language customization](active-directory-b2c-reference-language-customization.md) in your Azure AD B2C tenant. Enabling this feature allows Azure AD B2C to forward the Open ID Connect parameter `ui-locales` to your endpoint. Your content server can use this parameter to provide language-specific HTML pages.
+
+Content can be pulled from different places based on the locale that's used. In your CORS-enabled endpoint, you set up a folder structure to host content for specific languages. You'll call the right one if you use the wildcard value {Culture:RFC5646}. For example, your custom page URI might look like `https://contoso.blob.core.windows.net/{Culture:RFC5646}/myHTML/unified.html`. You can load the page in French by pulling content from `https://contoso.blob.core.windows.net/fr/myHTML/unified.html`
+
+## Examples
+
+For customization examples, download and review these [sample template files](https://github.com/azureadquickstarts/b2c-azureblobstorage-client/archive/master.zip).
+
+## Next steps
+
+- If you're using built-in policies, you can start customizing your UI with the tutorial: [Customize the user interface of your applications in Azure Active Directory B2C](tutorial-customize-ui.md).
+- If you're using custom policies, you can start customizing the UI with the article: [Customize the user interface of your application using a custom policy in Azure Active Directory B2C](active-directory-b2c-ui-customization-custom.md).
+

articles/active-directory-b2c/customize-ui-overview.md

@@ -0,0 +1,184 @@
+---
+title: Tutorial - Customize the user interface of your applications in Azure Active Directory B2C | Microsoft Docs
+description: Learn how to customize the user interface of your applications in Azure Active Directory B2C using the Azure portal.
+services: B2C
+author: davidmu1
+manager: mtillman
+
+ms.service: active-directory
+ms.workload: identity
+ms.topic: conceptual
+ms.date: 10/30/2018
+ms.author: davidmu
+ms.component: B2C
+---
+
+# Tutorial: Customize the user interface of your applications in Azure Active Directory B2C
+
+For more common user experiences, such as sign-up, sign-in, and profile editing, you can use [built-in policies](active-directory-b2c-reference-policies.md) in Azure Active Directory (Azure AD) B2C. The information in this tutorial helps you to learn how to [customize the user interface (UI)](customize-ui-overview.md) of these experiences using your own HTML and CSS files.
+
+In this article, you learn how to:
+
+> [!div class="checklist"]
+> * Create UI customization files
+> * Create a sign-up and sign-in policy that uses the files
+> * Test the customized UI
+
+If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+
+## Prerequisites
+
+If you haven't already created your own [Azure AD B2C Tenant](tutorial-create-tenant.md), create one now. You can use an existing tenant if you created one in a previous tutorial.
+
+## Create customization files
+
+You create an Azure storage account and container and then place basic HTML and CSS files in the container.
+
+### Create a storage account
+
+Although you can store your files in many ways, for this tutorial, you store them in [Azure Blob storage](../storage/blobs/storage-blobs-introduction.md).
+
+1. Make sure you're using the directory that contains your Azure subscription. Select the **Directory and subscription filter** in the top menu and choose the directory that contains your subscription. This directory is different than the one that contains your Azure B2C tenant.
+
+    ![Switch to subscription directory](./media/tutorial-customize-ui/switch-directories.png)
+
+2. Choose All services in the top-left corner of the Azure portal, search for and select **Storage accounts**. 
+3. Select **Add**.
+4. Under **Resource group**, select **Create new**, enter a name for the new resource group, and then click **OK**.
+5. Enter a name for the storage account. The name you choose must be unique across Azure, must be between 3 and 24 characters in length, and may contain numbers and lowercase letters only.
+6. Select the location of the storage account or accept the default location. 
+7. Accept all other default values, select **Review + create**, and then click **Create**.
+8. After the storage account is created, select **Go to resource**.
+
+### Create a container
+
+1. On the overview page of the storage account, select **Blobs**.
+2. Select **Container**, enter a name for the container, choose **Blob (anonymous read access for blobs only)**, and then click **OK**.
+
+### Enable CORS
+
+ Azure AD B2C code in a browser uses a modern and standard approach to load custom content from a URL that you specify in a policy. Cross-origin resource sharing (CORS) allows restricted resources on a web page to be requested from other domains.
+
+1. In the menu, select **CORS**.
+2. For **Allowed origins**, **Allowed headers**, and **Exposed headers**, enter `your-tenant-name.b2clogin.com`. Replace `your-tenant-name` with the name of your Azure AD B2C tenant. For example, `fabrikam.b2clogin.com`.
+3. For **Allowed verbs**, select both `GET` and `OPTIONS`.
+4. For **Max age**, enter 200.
+
+    ![Enable CORS](./media/tutorial-customize-ui/enable-cors.png)
+
+5. Click **Save**.
+
+### Create the customization files
+
+To customize the UI of the sign-up experience, you start by creating a simple HTML and CSS file. You can configure your HTML any way you want, but it must have a **div** element with an identifier of `api`. For example, `<div id="api"></div>`. Azure AD B2C injects elements into the `api` container when the page is displayed.
+
+1. In a local folder, create the following file and make sure that you change `your-storage-account` to the name of the storage account and `your-container` to the name of the container that you created. For example, `https://store1.blob.core.windows.net/b2c/style.css`.
+
+    ```html
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>My B2C Application</title>
+        <link rel="stylesheet" href="https://your-storage-account.blob.core.windows.net/your-container/style.css">
+      </head>
+      <body>  
+        <h1>My B2C Application</h1>
+        <div id="api"></div>
+      </body>
+    </html>
+    ```
+
+    The page can be designed any way that you want, but the **api** div element is required for any HTML customization file that you create. 
+
+3. Save the file as *custom-ui.html*.
+4. Create the following simple CSS that centers all elements on the sign-up or sign-in page including the elements that Azure AD B2C injects.
+
+    ```css
+    h1 {
+      color: blue;
+      text-align: center;
+    }
+    .intro h2 {
+      text-align: center; 
+    }
+    .entry {
+      width: 300px ;
+      margin-left: auto ;
+      margin-right: auto ;
+    }
+    .divider h2 {
+      text-align: center; 
+    }
+    .create {
+      width: 300px ;
+      margin-left: auto ;
+      margin-right: auto ;
+    }
+    ```
+
+5. Save the file as *style.css*.
+
+### Upload the customization files
+
+In this tutorial, you store the files that you created in the storage account so that Azure AD B2C can access them.
+
+1. Choose **All services** in the top-left corner of the Azure portal, search for and select **Storage accounts**.
+2. Select the storage account you created, select **Blobs**, and then select the container that you created.
+3. Select **Upload**, navigate to and select the *custom-ui.html* file, and then click **Upload**.
+
+    ![Upload customization files](./media/tutorial-customize-ui/upload-blob.png)
+
+4. Copy the URL for the file that you uploaded to use later in the tutorial.
+5. Repeat step 3 and 4 for the *style.css* file.
+
+## Create a sign-up and sign-in policy
+
+To complete the steps in this tutorial, you need to create a test application and a sign-up or sign-in policy in Azure AD B2C. You can apply the principles described in this tutorial to the other user experiences, such as profile editing.
+
+### Create an Azure AD B2C application
+
+Communication with Azure AD B2C occurs through an application that you create in your tenant. The following steps create an application that redirects the authorization token that is returned to [https://jwt.ms](https://jwt.ms).
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+2. Make sure you're using the directory that contains your Azure AD B2C tenant by clicking the **Directory and subscription filter** in the top menu and choosing the directory that contains your tenant.
+3. Choose **All services** in the top-left corner of the Azure portal, and then search for and select **Azure AD B2C**.
+4. Select **Applications**, and then select **Add**.
+5. Enter a name for the application, for example *testapp1*.
+6. For **Web App / Web API**, select `Yes`, and then enter `https://jwt.ms` for the **Reply URL**.
+7. Click **Create**.
+
+### Create the policy
+
+To test your customization files, you create a built-in sign-up or sign-in policy that uses the application that you previously created.
+
+1. In your Azure AD B2C tenant, select **Sign-up or sign-in policies**, and then click **Add**.
+2. Enter a name for the policy. For example, *signup_signin*. The prefix *B2C_1* is automatically added to the name when the policy is created.
+3. Select **Identity providers**, set **Email sign-up** for a local account, and then click **OK**.
+4. Select **Sign-up attributes**, choose the attributes that you want to collect from the customer during sign-up. For example, set **Country/Region**, **Display Name**, and **Postal Code**, and then click **OK**.
+5. Select **Application claims**, choose the claims that you want returned in the authorization tokens sent back to your application after a successful sign-up or sign-in experience. For example, select **Display Name**, **Identity Provider**, **Postal Code**, **User is new** and **User's Object ID**, and then click **OK**.
+6. Select **Page UI customization**, select **Unified sign-up or sign-in page**, and the click **Yes** for **Use custom page**.
+7. In **Custom page URI**, enter the URL for the *custom-ui.html* file that you recorded earlier, and then click **OK**.
+8. Click **Create**.
+
+## Test the policy
+
+1. In your Azure AD B2C tenant, select **Sign-up or sign-in policies**, and then select the policy that you created. For example, *B2C_1_signup_signin*.
+2. Make sure that the application that you created is selected in **Select application**, and then click **Run Now**.
+
+    ![Run the sign-up or sign-in policy](./media/tutorial-customize-ui/signup-signin.png)
+
+    You should see a page similar to the following example with the elements centered based on the CSS file that you created:
+
+    ![Policy results](./media/tutorial-customize-ui/run-now.png) 
+
+## Next steps
+
+In this article, you learned how to:
+
+> [!div class="checklist"]
+> * Create UI customization files
+> * Create a sign-up and sign-in policy that uses the files
+> * Test the customized UI
+
+> [!div class="nextstepaction"]
+> [Language customization in Azure Active Directory B2C](active-directory-b2c-reference-language-customization.md)