CSS template reference guide

Configuring your company branding for the user sign-in process provides a seamless experience in your applications that use Microsoft Entra ID as the identity and access management service. Use this CSS reference guide if you're using the CSS template as part of the customize company branding process.

Deprecation of custom CSS layout and positioning properties

To align with the Microsoft Secure Future Initiative and its focus on identity security and phishing resistance, Microsoft Entra ID is retiring support for custom CSS layout and positioning properties in company branding. These properties control where elements appear on the sign-in page and how they're layered, sized, and displayed. For example, they can move, overlap, resize, or hide page content. Retiring them keeps sign-in page layouts consistent and predictable in Microsoft Entra ID.

This change is the first step toward retiring the custom CSS feature entirely. Microsoft plans to provide advance notice, recommended migration paths, and future advanced customization options before that retirement.

For more information, see the blog post Microsoft Entra ID enhances security of branded sign-ins.

Timeline

• After July 21, 2026: Tenants created before January 6, 2026, that don't already use custom CSS can't configure custom CSS.
• Later: The affected layout and positioning properties will be deprecated globally. After deprecation, these properties are blocked and no longer function.
• Eventually: Custom CSS will be fully retired. Microsoft will share more guidance, including recommended migration paths, before retirement.

Who's affected

This change affects organizations whose Microsoft Entra ID tenant uses any of the deprecated layout and positioning properties in their custom CSS. Microsoft Entra External ID tenants aren't affected. After July 21, 2026, tenants created before January 6, 2026, that don't already use custom CSS can't configure custom CSS.

Microsoft notifies affected customers directly in advance.

Deprecated properties

If your custom CSS uses any of the following properties, remove them from your configuration. These properties don't have a supported migration or replacement.

• position (including top, right, bottom, left, and z-index)
• margin (including margin-top, margin-bottom, margin-left, and margin-right)
• transform
• opacity
• overflow
• filter
• pointer-events
• clip-path
• mix-blend-mode
• translate
• -webkit-transform
• -moz-transform
• -ms-transform
• -o-transform
• scale
• rotate
• perspective
• display
• visibility
• inset
• zoom
• offset
• offset-path
• offset-distance
• margin-block
• margin-block-start
• margin-block-end
• margin-inline
• margin-inline-start
• margin-inline-end
• order
• grid-area
• grid-column
• grid-column-start
• grid-column-end
• grid-row
• grid-row-start
• grid-row-end
• isolation
• overflow-x
• overflow-y
• overflow-block
• overflow-inline
• content-visibility
• clip
• mask
• mask-image
• -webkit-mask
• -webkit-mask-image

Check and update your custom CSS

To inspect your current CSS file, on the Custom branding page in the Microsoft Entra admin center at https://entra.microsoft.com, select Edit. On the Layout tab, under Custom CSS, select Download. Review the downloaded file for the properties listed in Deprecated properties.

To check all company branding localizations, use Microsoft Graph to export your current company branding configuration, and then check it with the tenant branding inspector tool. You need a Global Administrator or Branding Administrator account.

1. Go to Microsoft Graph Explorer, and then sign in to your tenant.

2. If you don't already know your tenant ID, send a GET request to the following URL, and then copy the id value from the response:

   https://graph.microsoft.com/v1.0/organization
   

3. Send a GET request to the following URL to return all configured company branding localizations. Replace <tenant-id> with your tenant ID:

   https://graph.microsoft.com/v1.0/organization/<tenant-id>/branding/localizations
   

4. Copy the response, or export it to a JSON file.

5. Go to the tenant branding inspector tool.

6. Paste the copied response, or upload the exported JSON file, into the tool. The tool lists each locale and the deprecated properties that it uses.

To remove the deprecated properties, edit the downloaded CSS file, upload it to the Company Branding page in the Microsoft Entra admin center, and then save your changes. To validate the visual impact before you update production, apply the changes in a test tenant first.

HTML selectors

The following CSS styles become the default body and link styles for the whole page. Styles that you apply to other links or text override these selectors.

• body - Styles for the whole page
• Styles for links:
  • a, a:link - All links
  • a:hover - When the mouse is over the link
  • a:focus - When the link has focus
  • a:focus:hover - When the link has focus and the mouse is over the link
  • a:active - When the link is being clicked

Microsoft Entra CSS selectors

Use the following CSS selectors to configure the details of the sign-in experience.

• .ext-background-image - Container that includes the background image in the default lightbox template

• .ext-header - Header at the top of the container

• .ext-header-logo - Header logo at the top of the container

  

• .ext-middle - Style for the full-screen background that aligns the sign-in box vertically to the middle and horizontally to the center

• .ext-vertical-split-main-section - Style for the container of the partial-screen background in the vertical split template that contains both a sign-in box and a background (This style is also known as the Active Directory Federation Services (ADFS) template.)

• .ext-vertical-split-background-image-container - Sign-in box background in the vertical split/ADFS template

• .ext-sign-in-box - Sign-in box container

• .ext-title - Title text

  

• .ext-subtitle - Subtitle text

• Styles for links:

  • .ext-link - Internal navigation links

• Styles for primary buttons:

  • .ext-button.ext-primary - Primary button default style
  • .ext-button.ext-primary:hover - When the mouse is over the button
  • .ext-button.ext-primary:focus - When the button has focus
  • .ext-button.ext-primary:focus:hover - When the button has focus and the mouse is over the button
  • .ext-button.ext-primary:active - When the button is being clicked

  

• Styles for secondary buttons:

  • .ext-button.ext-secondary - Secondary buttons
  • .ext-button.ext-secondary:hover - When the mouse is over the button
  • .ext-button.ext-secondary:focus - When the button has focus
  • .ext-button.ext-secondary:focus:hover - When the button has focus and the mouse is over the button
  • .ext-button.ext-secondary:active - When the button is being clicked

  

• .ext-error - Error text

  

• Styles for text boxes:

  • .ext-input.ext-text-box - Text boxes
  • .ext-input.ext-text-box.ext-has-error - When there's a validation error associated with the text box
  • .ext-input.ext-text-box:hover - When the mouse is over the text box
  • .ext-input.ext-text-box:focus - When the text box has focus
  • .ext-input.ext-text-box:focus:hover - When the text box has focus and the mouse is over the text box

  

• .ext-boilerplate-text - Custom message text at the bottom of the sign-in box

• .ext-promoted-fed-cred-box - Sign-in options text box

  

• Styles for the footer:

  • .ext-footer - Footer area at the bottom of the page
  • .ext-footer-links - Links area in the footer at the bottom of the page
  • .ext-footer-item - Link items (such as "Terms of use" or "Privacy & cookies") in the footer at the bottom of the page
  • .ext-debug-item - Debug details ellipsis in the footer at the bottom of the page