There’s now an API to add or update custom branding to Azure Active Directory sign-in pages

For a while now, organisations have been able to customise the Azure Active Directory sign-in pages, to make it clearer to users that they are in the right place. These setting also show up in a few other places, such as the Windows 10 out-of-box (OOBE) experiences and when Windows Autopilot is enabled for deployment.

Now, there’s a set of new API calls to enable developers to write applications which do this programmatically. According to documentation published recently, there are new API calls which enable you to:

• Create and set a new branding
• Read
• Update
• Delete

In addition, there are also a set of calls which allow specifying a particular locale.

The following properties can be set:

• backgroundColor – Color that will appear in place of the background image in low-bandwidth connections. The primary color of your banner logo or your organization color is recommended to be used here. Specify this in hexadecimal (for example, white is #FFFFFF).
• backgroundImage – Image that appears as the background of the sign in page. .png or .jpg not larger than 1920×1080 and smaller than 300kb. A smaller image will reduce bandwidth requirements and make page loads more performant.
• bannerLogo – A banner version of your company logo which appears appears on the sign-in page. .png or .jpg no larger than 36x245px. We recommend using a transparent image with no padding around the logo.
• id – This is an id, inherited from microsoft.graph.entity, is the locale specifying the ISO 639 standard for language, for example English is “en-us” or “en”. Read-only.
• signInPageText – Text that appears at the bottom of the sign-in box. You can use this to communicate additional information, such as the phone number to your help desk or a legal statement. This text must be Unicode and not exceed 1024 characters.
• squareLogo – Square version of your company logo. This appears in Windows 10 out-of-box (OOBE) experiences and when Windows Autopilot is enabled for deployment. .png or .jpg no larger than 240x240px and no more than 10kb in size. We recommend using a transparent image with no padding around the logo.
• usernameHintText – String that shows as the hint in the username textbox on the sign in screen. This text must be Unicode, without links or code, and can’t exceed 64 characters.

Right now, these API calls are only available in the /beta branch, meaning that whilst they are ideal for developers to work with in order to build out scripts and applications, they should be relied on in production. It’s also worth noting that the licensing requirements to use these APIs are the same as if you were changing branding via the Azure Portal: Azure Active Directory Premium 1, Premium 2, or Basic editions, or to have a Microsoft 365 license.

 

Ideas for use

There are some interesting opportunities which these APIs open up.

For a large enterprise, rolling out a consistent look and feel, but with localised wording in the appropriate language, is now something that would be possible without a lot of manual work. A simple application or script could iterate through prepared text and update it. You could even use Microsoft Cognitive services to perform the translation for you!

The API call to read branding properties has a fairly low permission scope, meaning that if a user has just signed into an application, the application likely has permission to read it. This could be an excellent way for an application to retrieve a suitable logo to show in an user interface in order to customise it.