Merge pull request #226865 from shlipsey3/company-branding-api-020923

company-branding-api

Author: v-regandowner

articles/active-directory/fundamentals/customize-branding.md

@@ -9,7 +9,7 @@ ms.service: active-directory
 ms.workload: identity
 ms.subservice: fundamentals
 ms.topic: how-to
-ms.date: 11/21/2022
+ms.date: 03/01/2023
 ms.author: sarahlipsey
 ms.reviewer: kexia
 ms.custom: "it-pro, seodec18, fasttrack-edit"
@@ -24,7 +24,7 @@ This article covers how to customize the company branding for sign-in experience
 
 An updated experience for adding company branding is available as an Azure AD preview feature. To opt in and explore the new experience, go to **Azure AD** > **Preview features** and enable the **Enhanced Company Branding** feature. Check out the updated documentation on [how to customize branding](how-to-customize-branding.md).
 
-## License requirements
+## Role and license requirements
 
 Adding custom branding requires one of the following licenses:
 
@@ -34,7 +34,9 @@ Adding custom branding requires one of the following licenses:
 
 Azure AD Premium editions are available for customers in China using the worldwide instance of Azure AD. Azure AD Premium editions aren't currently supported in the Azure service operated by 21Vianet in China. For more information about licensing and editions, see [Sign up for Azure AD Premium](active-directory-get-started-premium.md).
 
-## Customize the default sign-in experience
+The **Global Administrator** role is required to customize company branding.
+
+## Before you begin
 
 You can customize the sign-in experience when users sign in to your organization's tenant-specific apps, such as `https://outlook.com/woodgrove.com`, or when passing a domain variable, such as `https://passwordreset.microsoftonline.com/?whr=woodgrove.com`.
 
@@ -44,6 +46,10 @@ Custom branding appears after users sign in. Users that start the sign-in proces
 
 **Images have different image and file size requirements.** Take note of the requirements for each option. You may need to use a photo editor to create the right-sized images. The preferred image type for all images is PNG, but JPG is accepted. 
 
+**Use Microsoft Graph with Azure AD company branding.** Company branding can be viewed and managed using Microsoft Graph on the `/beta` endpoint and the `organizationalBranding` resource type. For more information, see the [organizational branding API documentation](/graph/api/resources/organizationalbranding?view=graph-rest-beta&preserve-view=true).
+
+## How to configure company branding
+
 1. Sign in to the [Azure portal](https://portal.azure.com/) using a Global administrator account for the directory.
 
 2. Go to **Azure Active Directory** > **Company branding** > **Configure**.
@@ -54,7 +60,7 @@ Custom branding appears after users sign in. Users that start the sign-in proces
 
     - **Language** The language for your first customized branding configuration is based on your default locale can't be changed. Once a default sign-in experience is created, you can add language-specific customized branding.
 
-    - **Sign-in page background image** Select a PNG or JPG image file to appear as the background for your sign-in pages. The image will be anchored to the center of the browser, and will scale to the size of the viewable space.
+    - **Sign-in page background image** Select a PNG or JPG image file to appear as the background for your sign-in pages. The image is anchored to the center of the browser, and scales to the size of the viewable space.
 
         We recommended using images without a strong subject focus. An opaque white box appears in the center of the screen, which could cover any part of the image depending on the dimensions of the viewable space.
 
@@ -79,17 +85,17 @@ Custom branding appears after users sign in. Users that start the sign-in proces
     > [!IMPORTANT]
     > Hyperlinks that are added to the sign-in page text render as text in native environments, such as desktop and mobile applications.
 
-- **Advanced settings**
+    - **Advanced settings**
 
     ![Configure company branding page, with advanced settings completed](media/customize-branding/legacy-customize-branding-configure-advanced.png)   
 
-    - **Sign-in page background color** Specify the hexadecimal color (#FFFFFF) that will appear in place of your background image in low-bandwidth connection situations. We recommend using the primary color of your banner logo or your organization color.
+    - **Sign-in page background color** Specify the hexadecimal color (#FFFFFF) that appears in place of your background image in low-bandwidth connection situations. We recommend using the primary color of your banner logo or your organization color.
 
-    - **Square logo image** Select a PNG or JPG image of your organization's logo to appear during the setup process for new Windows 10 Enterprise devices. This image is only used for Windows authentication and appears only on tenants that are using [Windows Autopilot](/windows/deployment/windows-autopilot/windows-10-autopilot) for deployment or for password entry pages in other Windows 10 experiences. In some cases, it may also appear in the consent dialog.
+    - **Square logo image** Select a PNG or JPG image of your organization's logo to appear during the setup process for new Windows 10 Enterprise devices. This image is only used for Windows authentication and only appears on tenants that are using [Windows Autopilot](/windows/deployment/windows-autopilot/windows-10-autopilot) for deployment or password entry pages in other Windows 10 experiences. In some cases, it may also appear in the consent dialog.
 
         We recommend using a transparent image since the background might not match your logo background. We also recommend not adding padding around the image or it might make your logo look small.
 
-    - **Square logo image, dark theme** Same as the square logo image above. This logo image takes the place of the square logo image when used with a dark background, such as with Windows 10 Azure AD joined screens during the out-of-box experience (OOBE). If your logo looks good on white, dark blue, and black backgrounds, you don't need to add this image. 
+    - **Square logo image, dark theme** Same as the square logo image. This logo image takes the place of the square logo image when used with a dark background, such as with Windows 10 Azure AD joined screens during the out-of-box experience (OOBE). If your logo looks good on white, dark blue, and black backgrounds, you don't need to add this image. 
 
     >[!IMPORTANT]
     > Transparent logos are supported with the square logo image. The color palette used in the transparent logo could conflict with backgrounds (such as, white, light grey, dark grey, and black backgrounds) used within Microsoft 365 apps and services that consume the square logo image. Solid color backgrounds may need to be used to ensure the square image logo is rendered correctly in all situations.
@@ -101,7 +107,7 @@ Custom branding appears after users sign in. Users that start the sign-in proces
     This process creates your first custom branding configuration, and it becomes the default for your tenant. The default custom branding configuration serves as a fallback option for all language-specific branding configurations. The configuration can't be removed after you create it.
 
     >[!IMPORTANT]
-    >To add more corporate branding configurations to your tenant, you must choose **New language** on the **Contoso - Company branding** page. This opens the **Configure company branding** page, where you can follow the same steps as above.
+    >To add more corporate branding configurations to your tenant, you must choose **New language** on the **Contoso - Company branding** page. This opens the **Configure company branding** page, where you can follow the previous steps.
 
 ## Customize the sign-in experience by browser language
 
@@ -111,13 +117,13 @@ To create an inclusive experience for all of your users, you can customize the s
 
 2. Select **Azure Active Directory** > **Company branding** > **+ New language**.
 
-The process for customizing the experience is the same as the [Default sign-in experience](#customize-the-default-sign-in-experience), except you select a **Language** from the dropdown list.
+The process for customizing the experience is the same as the main [configure company branding](#configure-your-company-branding) process, except you select a **Language** from the dropdown list.
 
 We recommend adding **Sign-in page text** in the selected language.
 
 ## Edit custom branding
 
-If custom branding has been added to your tenant, you can edit the details already provided. Refer to the details and descriptions of each setting in the [Add custom branding](#customize-the-default-sign-in-experience) section of this article.
+If custom branding has been added to your tenant, you can edit the details already provided. Refer to the details and descriptions of each setting in the [configure your company branding](#configure-your-company-branding) section of this article.
 
 1. Sign in to the [Azure portal](https://portal.azure.com/) using a Global Administrator account for the directory.
 
@@ -134,4 +140,4 @@ If custom branding has been added to your tenant, you can edit the details alrea
 ## Next steps
 
 - [Add your organization's privacy info on Azure AD](./active-directory-properties-area.md)
-- [Learn more about Conditional Access](../conditional-access/overview.md)
+- [Learn more about Conditional Access](../conditional-access/overview.md)

articles/active-directory/fundamentals/how-to-customize-branding.md

@@ -9,7 +9,7 @@ ms.service: active-directory
 ms.workload: identity
 ms.subservice: fundamentals
 ms.topic: how-to
-ms.date: 01/31/2023
+ms.date: 03/01/2023
 ms.author: sarahlipsey
 ms.reviewer: almars
 ms.custom: "it-pro, seodec18, fasttrack-edit"
@@ -20,17 +20,17 @@ ms.collection: M365-identity-device-management
 
 When users authenticate into your corporate intranet or web-based applications, Azure Active Directory (Azure AD) provides the identity and access management (IAM) service. You can add company branding that applies to all these sign-in experiences to create a consistent experience for your users.
 
-The default sign-in experience is the global look and feel that applies across all sign-ins to your tenant. Before you customize any settings, the default Microsoft branding will appear in your sign-in pages. You can customize this default experience with a custom background image or color, favicon, layout, header, and footer. You can also upload a custom CSS.
+The default sign-in experience is the global look and feel that applies across all sign-ins to your tenant. Before you customize any settings, the default Microsoft branding appears in your sign-in pages. You can customize this default experience with a custom background image or color, favicon, layout, header, and footer. You can also upload a custom CSS.
 
-The updated experience for adding company branding covered in this article is available as an Azure AD preview feature. To opt in and explore the new experience, go to **Azure AD** > **Preview features** and enable the **Enhanced Company Branding** feature. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
-
-Instructions for the legacy company branding customization process can be found in the [Customize branding](customize-branding.md) article.
+> [!NOTE]
+> Instructions for the legacy company branding customization process can be found in the **[Customize branding](customize-branding.md)** article.<br><br>The updated experience for adding company branding covered in this article is available as an Azure AD preview feature. To opt in and explore the new experience, go to **Azure AD** > **Preview features** and enable the **Enhanced Company Branding** feature. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+>
 
 ## User experience
 
 You can customize the sign-in pages when users access your organization's tenant-specific apps. For Microsoft and SaaS applications (multi-tenant apps) such as <https://myapps.microsoft.com>, or <https://outlook.com> the customized sign-in page appears only after the user types their **Email**, or **Phone**, and select **Next**. 
 
-Some of the Microsoft applications support the home realm discovery `whr` query string parameter, or a domain variable. With the home realm discovery and domain parameter, the customized sign-in page will appear immediately in the first step. 
+Some of the Microsoft applications support the home realm discovery `whr` query string parameter, or a domain variable. With the home realm discovery and domain parameter, the customized sign-in page appears immediately in the first step. 
 
 In the following examples replace the contoso.com with your own tenant name, or verified domain name:
 
@@ -39,7 +39,7 @@ In the following examples replace the contoso.com with your own tenant name, or
 - For my app portal `https://myapps.microsoft.com/?whr=contoso.com` 
 - Self-service password reset `https://passwordreset.microsoftonline.com/?whr=contoso.com`
 
-## License requirements
+## Role and license requirements
 
 Adding custom branding requires one of the following licenses:
 
@@ -51,16 +51,22 @@ For more information about licensing and editions, see the [Sign up for Azure AD
 
 Azure AD Premium editions are available for customers in China using the worldwide instance of Azure AD. Azure AD Premium editions aren't currently supported in the Azure service operated by 21Vianet in China
 
+The **Global Administrator** role is required to customize company branding.
+
 ## Before you begin
 
 **All branding elements are optional. Default settings will remain, if left unchanged.** For example, if you specify a banner logo but no background image, the sign-in page shows your logo with a default background image from the destination site such as Microsoft 365. Additionally, sign-in page branding doesn't carry over to personal Microsoft accounts. If your users or guests authenticate using a personal Microsoft account, the sign-in page won't reflect the branding of your organization.
 
 **Images have different image and file size requirements.** Take note of the image requirements for each option. You may need to use a photo editor to create the right size images. The preferred image type for all images is PNG, but JPG is accepted. 
 
+**Use Microsoft Graph with Azure AD company branding.** Company branding can be viewed and managed using Microsoft Graph on the `/beta` endpoint and the `organizationalBranding` resource type. For more information, see the [organizational branding API documentation](/graph/api/resources/organizationalbranding?view=graph-rest-beta&preserve-view=true).
+
+## How to navigate the company branding process
+
 1. Sign in to the [Azure portal](https://portal.azure.com/) using a Global Administrator account for the directory.
 
 2. Go to **Azure Active Directory** > **Company branding** > **Customize**.
-    - If you currently have a customized sign-in experience, you'll see an **Edit** button.
+    - If you currently have a customized sign-in experience, the **Edit** button is available.
 
     ![Custom branding landing page with 'Company branding' highlighted in the side menu and 'Configure' button highlighted in the center of the page](media/how-to-customize-branding/customize-branding-getting-started.png)
 
@@ -72,7 +78,7 @@ The sign-in experience process is grouped into sections. At the end of each sect
 
 - **Favicon**: Select a PNG or JPG of your logo that appears in the web browser tab.
 
-- **Background image**: Select a PNG or JPG to display as the main image on your sign-in page. This image will scale and crop according to the window size, but may be partially blocked by the sign-in prompt.
+- **Background image**: Select a PNG or JPG to display as the main image on your sign-in page. This image scales and crops according to the window size, but may be partially blocked by the sign-in prompt.
 
 - **Page background color**: If the background image isn't able to load because of a slower connection, your selected background color appears instead.
 
@@ -133,7 +139,7 @@ If you haven't enabled the footer, go to the **Layout** section and select **Sho
 
 - **Self-service password reset**:
     - Show self-service password reset (SSPR): Select the checkbox to turn on SSPR. 
-    - Common URL: Enter the destination URL for where your users will reset their passwords. This URL appears on the username and password collection screens.
+    - Common URL: Enter the destination URL for where your users reset their passwords. This URL appears on the username and password collection screens.
     - Username collection display text: Replace the default text with your own custom username collection text.
     - Password collection display text: Replace the default text with your own customer password collection text.
 

articles/active-directory/fundamentals/toc.yml

@@ -17,7 +17,7 @@ items:
     href: active-directory-how-subscriptions-associated-directory.md
   - name: Add your privacy info
     href: active-directory-properties-area.md
-  - name: Add company branding
+  - name: Add company branding (preview)
     href: how-to-customize-branding.md
 - name: Users, groups, and licenses
   expanded: false