This is just a quick post I wanted to share online as this is the second time I was asked/heard about this ADFS 2016 bug. A minor bug exist in ADFS 2016 after upgrading from ADFS 2012 R2, when you have added a custom ADFS illustration picture.
When willl I see this bug?
Often you will see this bug after trying to make changes to your ADFS web theme. I have seen this when customers was trying to add an updated javascript to the existing web theme or add the new “Azure AD Centered Login Page” web theme from Github. The issue occur when creating a backup/copy of the existing default web theme (through the New-AdfsWebTheme powershell cmdlet) .
New-AdfsWebTheme : MSISMP0002: The specified relative URI ‘/adfs/portal/illustration/illustration.png’ conflicts with one of the internally predefined relative URIs.
Reason for this issue
During the upgrade from ADFS 2012 R2 to ADFS 2016 (ADFS Farm Behavior Level Raise) , the files resources related the “Default” ADFS Web theme is rebuilt. But since Logo and illustration image on default web theme can be configured. The images (only if they are configured) are also copied/added in the default.
However, the current used logic may lead the “Default” web theme to an inconsistent state (…)
Normally, the “illustration” image should be represented by only one illustration item and one file resource item (in the ADFS database). In the investigated case, the “illustration” image (in the “Default” Web Theme) is represented by
- one illustration item :
- <d2p1:Value>/adfs/portal/illustration/illustration.jpg
- but by TWO file resource items :
- <d2p1:Key>/adfs/portal/illustration/illustration.png
- This is an orphan entry/Key (no image item is using this name). And It has been created when the “Default” ADFS Web theme is rebuilt with the default images …
- <d2p1:Key>/adfs/portal/illustration/illustration.jpg
- This entry/Key is related to the custom image. Ideally, when this entry was added the previous one should have been deleted for avoiding the inconsistency.
The bug seems to be related to the fact we are expecting to add a custom’s image with the same file extension as the default one (illustration.png) …
- This entry/Key is related to the custom image. Ideally, when this entry was added the previous one should have been deleted for avoiding the inconsistency.
- <d2p1:Key>/adfs/portal/illustration/illustration.png
Workaround/solution:
Ideally, an hotfix request should be raised to our product group. However, the following workaround fixes the issue. Here is a short version of the step by step ot the workaround.
- Step 1: Export the “Default” web theme
- export-adfswebtheme -Name default -DirectoryPath c:\tools\theme2
- Step 2: Remove/clean-up the illustration from the “Default” web theme (the illustration item and the file resource item related to illustration.jpg will be removed. The orphan entry will still be there )
- set-adfswebtheme -targetname default -illustration @{}
- Step 3: Restore the “default illustration” (by default, I mean the *.png one) to the “Default” web theme. The idea here is to reuse the orphan entry
- set-adfswebtheme -targetname default -illustration @{Path=”c:\tools\theme2\illustration\illustration.png“}
- Step 4: Here, either we can decide to create a new ADFS web Theme based on the “default” one (by using on New-AdfsWebTheme cmdlet) in order for customization purpse (this is the preferedd way) or Then we can also set/restore the illustration item (from the jpeg file) to the “default” web theme as follow. This will handle correctly the file resource entry and avoiding the identified conflict:
- set-adfswebtheme -targetname default -illustration @{Path=”c:\tools\theme2\illustration\illustration.jpg“}
Note: Credits for discovering and solving this issue goes to Claus Jespersen and the Azure Identity productgroup. Thanks!
/Peter