Configuring Windows Azure Pack to Trust your Token
The tokens been sent and once it hits either the tenant or admin site it’ll promptly be ignored and you’ll get an ugly error message saying “nope, not gonna happen, bub.”
We therefore need to configure Windows Azure Pack to trust our token. Looking at MSDNwe see some useful information telling us what we need to modify, but its missing some information so we’re going to expand on it a bit.
First things first: if your IdP publishes a Federation Metadata document then you can just configure everything via PowerShell:
You can replace the target “Admin” with “Tenant” if you want to configure the Tenant Portal. The only caveat with doing it this way is that the metadata document needs to be accessible from the server. I’ve submitted a feature request that they also support local file paths too; hopefully they listen! Since the parameter takes the full URL you can put the metadata document somewhere public if its not normally accessible. You will only need the metadata accessible while applying this configuration. If the cmdlet completed successfully then you should be able to log in from your own IdP. That’s all there is to it for you. I would recommend seriously considering going this route instead of configuring things manually. Otherwise, lets carry on. Since we can’t import our federation metadata (since we probably don’t have any), we need to configure things manually. To do that we need to modify settings in the database. Looking back to Part 2 we see all the configuration elements that enable our federated trust to the default IdPs. We’ll need to update a few settings across the Microsoft.MgmtSvc.Store andMicrosoft.MgmtSvc.PortalConfigStore databases.
Important: As per the MSDN documentation it says to modify the settings in the PortalConfigStore database. It’s incomplete as that’s only part of the process.
The PortalConfigStore database contains the settings used by the Tenant and Admin Portals to validate and request tokens. We need to modify these settings to use our custom IdP. To do so locate the Authentication.IdentityProvider setting in the [Config].[Settings]table. The namespace we need to choose is dependent on which site we want to configure. In our case we select the Admin namespace. As we saw last time it looks something like:
We need to substitute our STS information here. The Realm is whatever your STS issuer is, and the Endpoint is where ever your WS-Federation endpoint is located. The Certificate should be a base 64 encoded representation of your signing certificate (remember, just the public key).
In my experience I’ve had to do an IISRESET on the portals to get the settings refreshed. I might just be impatient though. (Update: as it turns out, the configuration is cached for a period of time)
Once those values are replaced you can try logging in. You should be redirected to your IdP and if you issue the token properly it’ll hit the portal and you should be logged in. Unfortunately this’ll actually fail with a non-useful error message.
Whoops
Who can guess why? So far I’ve stated that the MSDN documentation is missing some information. What have we missed? Hopefully if you’ve read the first two parts of this series you’re yelling at the screen telling me to get on with it already because you’ve caught on to what I’m saying.
We haven’t configured the API services to trust our STS! Oops.
With that being said, we now have proof that Windows Azure Pack flows the token to the services from the Portal and, more importantly, the services validate the token. Cool!
Anyway, now to configure the APIs. Warning: complicated.
In the Microsoft.MgmtSvc.Store database locate the Settings table and then locate theAuthentication.IdentityProvider.Secondary element in the AdminAPI namespace. We need to update it with the exact same values as we put in to the configuration element in the other database.
If you’re only wanting to configure the Tenant Portal you’d want to modify theAuthentication.IdentityProvider.Primary configuration element. Be careful with thePrimary/Secondary elements as they can get confusing.
If you’re configuring the Admin Portal you’ll need to update theAuthentication.IdentityProvider.Secondary configuration element in the TenantAPInamespace to use the configuration you specified for the Admin Portal as well. As I said previously, I think this is because the Admin Portal calls into the Tenant API. The Admin Portal would use an admin-trusted token – therefore the TenantAPI needs to trust the admin’s STS.
Now that you’ve completed configuration you can do an IISRESET and try logging in. If you configured everything properly you should now be able to log in from your own IdP.
Troubleshooting
For those few rock star Ops people who understand identity this guide was likely pretty easy to follow, understand, and implement. For everyone else though, this was probably a pain in the neck. Here are some troubleshooting tips.
Review the Event Logs
It’s surprising how many people forget that a lot of applications will write errors to the Windows Event Log. Windows Azure Pack has quite a number of logs that you can review for more information. If you’re trying to track down an issue in the portals look in theMgmtSvc-*Site where * is Tenant or Admin. Errors will get logged there. If you’re stuck mucking about the APIs look in the MgmtSvc-*API where * is Tenant, Admin, or TenantPublic.
Enable Development Mode
You can enable developer mode in sites by modifying a value in the web.config. Unprotect the web.config by calling:
And then locate the appSetting namedMicrosoft.Azure.Portal.Configuration.PortalConfiguration.DevelopmentMode and set the value to true. Be sure to undo and re-protect the configuration when you’re done. You should then get a neat error tracing window show up in the portals, and more diagnostic information will be logged to the event logs. Probably not wise to do this in a production environment.
Use the PowerShell CmdLets
There are a quite a number of PowerShell cmdlets available for you to learn about the configuration of Windows Azure Pack. If you open the Windows Azure Pack Administration PowerShell console you can see that there are two modules that get loaded that are full of cmdlets:
PS C:\Windows\system32> get-command -Module MgmtSvcConfig
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Add-MgmtSvcAdminUser MgmtSvcConfig
Cmdlet Add-MgmtSvcDatabaseUser MgmtSvcConfig
Cmdlet Add-MgmtSvcResourceProviderConfiguration MgmtSvcConfig
Cmdlet Get-MgmtSvcAdminUser MgmtSvcConfig
Cmdlet Get-MgmtSvcDatabaseSetting MgmtSvcConfig
Cmdlet Get-MgmtSvcDefaultDatabaseName MgmtSvcConfig
Cmdlet Get-MgmtSvcEndpoint MgmtSvcConfig
Cmdlet Get-MgmtSvcFeature MgmtSvcConfig
Cmdlet Get-MgmtSvcFqdn MgmtSvcConfig
Cmdlet Get-MgmtSvcNamespace MgmtSvcConfig
Cmdlet Get-MgmtSvcNotificationSubscriber MgmtSvcConfig
Cmdlet Get-MgmtSvcResourceProviderConfiguration MgmtSvcConfig
Cmdlet Get-MgmtSvcSchema MgmtSvcConfig
Cmdlet Get-MgmtSvcSetting MgmtSvcConfig
Cmdlet Initialize-MgmtSvcFeature MgmtSvcConfig
Cmdlet Initialize-MgmtSvcProduct MgmtSvcConfig
Cmdlet Install-MgmtSvcDatabase MgmtSvcConfig
Cmdlet New-MgmtSvcMachineKey MgmtSvcConfig
Cmdlet New-MgmtSvcPassword MgmtSvcConfig
Cmdlet New-MgmtSvcResourceProviderConfiguration MgmtSvcConfig
Cmdlet New-MgmtSvcSelfSignedCertificate MgmtSvcConfig
Cmdlet Protect-MgmtSvcConfiguration MgmtSvcConfig
Cmdlet Remove-MgmtSvcAdminUser MgmtSvcConfig
Cmdlet Remove-MgmtSvcDatabaseUser MgmtSvcConfig
Cmdlet Remove-MgmtSvcNotificationSubscriber MgmtSvcConfig
Cmdlet Remove-MgmtSvcResourceProviderConfiguration MgmtSvcConfig
Cmdlet Reset-MgmtSvcPassphrase MgmtSvcConfig
Cmdlet Set-MgmtSvcCeip MgmtSvcConfig
Cmdlet Set-MgmtSvcDatabaseSetting MgmtSvcConfig
Cmdlet Set-MgmtSvcDatabaseUser MgmtSvcConfig
Cmdlet Set-MgmtSvcFqdn MgmtSvcConfig
Cmdlet Set-MgmtSvcIdentityProviderSettings MgmtSvcConfig
Cmdlet Set-MgmtSvcNotificationSubscriber MgmtSvcConfig
Cmdlet Set-MgmtSvcPassphrase MgmtSvcConfig
Cmdlet Set-MgmtSvcRelyingPartySettings MgmtSvcConfig
Cmdlet Set-MgmtSvcSetting MgmtSvcConfig
Cmdlet Test-MgmtSvcDatabase MgmtSvcConfig
Cmdlet Test-MgmtSvcPassphrase MgmtSvcConfig
Cmdlet Test-MgmtSvcProtectedConfiguration MgmtSvcConfig
Cmdlet Uninstall-MgmtSvcDatabase MgmtSvcConfig
Cmdlet Unprotect-MgmtSvcConfiguration MgmtSvcConfig
Cmdlet Update-MgmtSvcV1Data MgmtSvcConfig
As well as the MgmtSvcConfig module which is moreso for daily administration.
Read the Windows Azure Pack Claims Whitepaper
See here: Claims-Based Identity in Windows Azure Pack (docx). It’s a great document that outlines many different claims-based scenarios in WAP.
Visit the Forums
When in doubt take a look at the forums and ask a question if you’re stuck.
Email Me
Lastly, you can contact me (steve@syfuhs.net) with any questions. I may not have answers but I might be able to find someone who can help.
Conclusion
In the first two parts of this series we looked at how authentication works, how it’s configured, and now in this installment we looked at how we can configure a third party IdP to log in to Windows Azure Pack. If you’re trying to configure Windows Azure Pack to use a custom IdP I imagine this part is the most complicated to figure out and hopefully it was documented well enough. I personally spent a fair amount of time fiddling with settings and most of the information I’ve gathered for this series has been the result of lots of trial and error. With any luck this series has proven useful to you and you have more luck with the configuration than I originally did.
Next time we’ll take a look at how we can consume the public APIs using a third party IdP for authentication.
In the future we might take a look at how we can authenticate requests to a service called from a Windows Azure Pack add-on, and how we can call into Windows Azure Pack APIs from an add-on.