What is the Microsoft Office 365 Federation Metadata Update Automation Installation Tool?
This tool automates an otherwise manual process, which if not performed, would prevent all users from signing into Office 365 when the token signing certificate expires (once per year). This tool is a PowerShell script that creates a scheduled task to tell Office 365 to trust the self-signed certificate.
Get the tool:
It turns out that it is still necessary to restart the internal ADFS service after the token signing certificate has been issued.
Who needs the tool?
All Office 365 customers that have implemented Single-Sign-On with ADFS 2.0 must update their token signing certificate every year otherwise users will be unable to sign in. They would all benefit from this tool, otherwise they have to predict when the cert expires, then follow a manual process to trust the new cert.
What if the tool is not installed? What is the manual process?
I welcome this tool. Last year, I blogged about the manual steps to predict when the token signing certificate must be installed.
Fixing the problem is not too difficult, however, preventing the problem from occurring is actually somewhat confusing. So I highly recommend all customers to use this tool!
If you do not want to run the tool, here is what you must do:
1. Find out when your existing token signing cert will expire.
2. Subtract 20 days from the expiration date.
3. From that date, ADFS will automatically issue a new certificate that will co-exist with the primary certificate for 5 days (this is the default period, but it can be configured to be a longer period). At the end of that 5 day period, the new token signing certificate is made primary, and this actually disrupts service until someone takes manual action to run a PowerShell command to force Office 365 to trust the new cert. This is necessary because it is a self-signed certificate and therefore, o365 needs to be informed by someone (or an automated task) that the cert has changed. This is exactly what the tool above helps automate, so that if someone does not predict the date correctly, it will avoid an outage.
For example, this is what you will see when you are in the 5 day period when the new cert has been automatically issued but it has not yet been made the primary cert. The old is ‘IsPrimary’ = True, and the new one is there but it is not yet the Primary.
Type the following:
Get-ADFSCertificate –CertificateType token-signing
What happens if I ignore the expiration date of the token signing cert?
You’ll find out – your users will call you when they are unable to sign into Outlook, or Outlook Web Access. They will get an error “There was a problem accessing the site. Try to browse the site again.”
What does the tool require?
- You must make sure that you have installed the latest version of the Microsoft Online Services Module for Windows PowerShell
- You need to have a functioning AD FS 2.0 Federation Service
- You need to have access to Global Administrator credentials for your Office 365 tenant
- You need to have at least one verified domain in the Office 365 tenant must be of type ‘Federated’
- This tool must be executed on a writable Federation Server
- The currently logged on user must be a member of the local Administrators group
- The Microsoft Online Services Module for Windows PowerShell must be installed. You can download the module from http://onlinehelp.microsoft.com/en-us/office365-enterprises/ff652560.aspx
Running the tool
After you download the tool (aka powershell script) onto your internal ADFS server, you need to right-click on it and unblock it. Otherwise you will get errors like “the script is not digitally signed. The script will not execute on the system.”
Also, if you get an error that “Failed MSOL credential validation.” it is because you are running the script in the regular Windows Powershell or ADFS PowerShell module. You need to make sure you run this in the window “Microsoft Online Services Module for Windows PowerShell” that looks like this on the desktop:
Then just change directory to the location of where you saved the script and run the script.
Verifying it worked
Launch Task Scheduler. You will see the new task has been scheduled to run at midnight every day.
Recommendation: Because the scheduled task will run under the account that you were logged in with, you will need to remember to update this scheduled task whenever you change your password, or run the tool with a service account with a non-expiring password (best bet!/recommended!). It would totally defeat the purpose of going to all this effort only to have the script not run when you are counting on it because the password was changed and the scheduled task failed.