First published on TechNet on Jan 29, 2018
Howdy folks!
Michele Ferrari here from the Premier Field Engineer-Identity Team in San Francisco, here today to talk about ADFS Monitoring settings for Claims Provider Trust and Relying Party Trust.
This is the question we're going to answer today as part of the Mix and Match series:
How can we Monitor when our partners' Identity Providers update the Signing and Encryption certificates?
Well, what I'm implementing it's something which is still not available today but, our PG is aware, and it will be included in vNext. Before going straight to the solution, I want to present a real scenario and recall some of the basic concepts in the Identity space.
The solution we discuss can be used to monitor either the Claims Provider Trust or the Relying Party Trust certificates => same knowledge can be applied to that as-well.
Relying Party signature certificate is rarely used indeed. It is meant when the SaaS application provider also wants to digitally sign the SAML Sign-In request, when the request is sent over to the ADFS server to ensure the SAML request doesn't get modified somehow. There isn't typically anything important in the SAML request but there are cases where the application owner or us want to enforce a certain authentication type. Signing the SAML request ensures no one modifies the request. It's also possible to encrypt the SAML request but this is definitely rare to see in the real life. If you want to understand more what a SAML Protocol Sign-In request looks like, read this post from Dave Gregory here=> https://blogs.technet.microsoft.com/askpfeplat/2014/11/02/adfs-deep-dive-comparing-ws-fed-saml-and-... Ready? Follow me… Let's start from a practical example: CONTOSO.COM wants to allow his employees to access a 3 rd party application called ClaimsWeb hosted by MISTERMIK.COM , providing the SingleSignOn experience. è John, an employee at CONTOSO.COM wants to access an expense note application (ClaimsWeb). Let's break this down and identify all the moving parts involved:
-
John , is an User member of CONTOSO.COM. It's called Subject .
-
CONTOSO.COM is the Identity Provider (abbreviated IP in WS-Federation, IdP in SAML) authenticates a client using, for example, Windows integrated authentication. It creates a SAML token based on the claims provided by the client and might add its own claims. è A Relying Party application (RP) receives the SAML token and uses the claims inside to decide whether to grant the client access to the requested resource.
-
MISTERMIK.COM is a software vendor offering SaaS solutions in the cloud.MISTERMIK.COM decides that its ClaimsWeb application should trust CONTOSO.COM because of CONTOSO.COM purchasing a license for the ClaimsWeb application. MISTERMIK.COM here plays the role of the Relying Party STS , è which does not authenticate the client, but relies on a SAML token provided by an IP-STS that It trusts (CONTOSO).
-
CLAIMSWEB.mistermik.com is the Relying Party Application . Synonyms for an RP include "claims aware application" and "claims-based application". è A relying party is a Federation Service or application that consumes claims to make authorization decisions: an application that trusts an Identity Provider is referred to as a relying party or RP.Claims provider trust: è it is a trust object that is created to maintain the relationship with another Federation Service that provides claims to this Federation Service. MISTERMIK'S ADFS has a claims provider trust with CONTOSO'S AD FS = CONTOSO'S ADFS provides CONTOSO\John's claims to MISTERMIK'S AD FS. Relying party trust: è it is a trust object that is created to maintain the relationship with a Federation Service or application that consumes claims from this Federation Service. CONTOSO'AD FS has MISTERMIK.COM's AD FS as Relying Party Trust. MISTERMIK.COM consumes claims coming from CONTOSO'S AD FS.
Now that we have covered the terminology with the entities that will play the role of the IdP or IP, and RP, we want to make it perfectly clear in our mind and go through the flow one more time.
Let's write something on the whiteboard and focus on steps:
- The application validates the security token.
- The Expense Note Application ClaimsWeb, an ADFS-enabled Web application also defined as Claims aware application, it consumes the organization claims and uses them to Authorize the user or to personalize the application for the user, for example showing the expense notes related to John and other John's financial data.
Ok folks , I know it's a lot to digest but, you will appreciate having this perfectly clear on your next Identity conversation. We have now to understand how the Identity Provider and the Resource Provider can trust each other. Claims Provider Trusts We can use the Claims Provider Trust to federate to ADFS implementation to other organization or 3rd party federated identity providers (Ping Federate, Siteminder, etc).
When you configure a claims provider trust or relying party trust in your organization with claim rules, the claim rule set(s) for that trust act as a gatekeeper for incoming claims by invoking the claims engine to apply the necessary logic in the claim rules to determine whether to issue any claims and which claims to issue.
We can't really talk about Trusts without introducing the Claim Pipeline: The Claim Pipeline represents the path that claims must follow before they can be issued.
-
Accepting incoming claims
- The acceptance rules are run
-
Authorizing the claims requester
- Access Control Policy for Authorization decision
-
Issuing outgoing claims
- Issue outgoing claims and package into a security token
Each federation server uses a token-signing certificate to digitally sign all security tokens that it produces. This helps prevent attackers from forging or modifying security tokens to gain unauthorized access to resources.
When we want to digitally sign tokens, we will always use the private portion of our token signing certificate. When a partner or application wants to validate the signature, they will have to use the public portion of our signing certificate to do so.
CONTOSO.COM, the IdP (Identity Provider) has an X.509 certificate. When John, a CONTOSO employee authenticates for accessing the ClaimsWeb App in MISTERMIK.COM .COM, the IdP uses the private key associated with the X.509 certificate to digitally sign the token. The Federation Service in MISTERMIK.COM verifies the digital signature using the public key confirming the token has been produced only by CONTOSO.COM's Identity Provider and that the content has not been altered from the moment it was signed. https://docs.microsoft.com/en-us/windows-server/mistermik.com /ad-fs/design/token-signing-certifica...
Then we have the Token Decryption Certificate . This certificate would be used to encrypt SAML tokens from the Identity Provider. Encryption of tokens is strongly recommended to increase security and protection against potential man-in-the-middle (MITM) attacks that might be tried against your AD FS deployment. Use of encryption might have a slight impact on throughout but in general, it should not be usually noticed and in many deployments the benefits for greater security exceed any cost in terms of server performance.
Encrypting claims means that only the relying party, in possession of the private key would be able to read the claims in the token. This requires availability of the token encrypting public key, and configuration of the encryption certificate on the Claims Provider Trust (same concept is applicable at the Relying Party Trust).
Recalling our practical example, when CONTOSO.COM, the IdP sends MISTERMIK.COM /RP a token, AD FS will use the private key of his token signing certificate and optionally, the public key of his partner's token encryption certificate.
| To generalize and reinforce the concept: If you're receiving tokens from a third party identity provider because you are a SaaS provider, they'll be sending you tokens signed with their token signing certificate private key and they'll encrypt the token with the public portion of your token encryption certificate. |
By default, these certificates are valid for one year from their creation and around the one-year mark, they will renew themselves automatically via the Auto Certificate Rollover feature in ADFS if you have this option enabled. We don't in our Lab and we want to monitor when a certificate is changed. 
ADFS starts the trust monitoring cycle every 24 hours (1440 minutes).
Get-ADFSProperties | select MonitoringInterval
PS C:\MF> Get-ADFSProperties | select MonitoringInterval
MonitoringInterval
------------------
1440
From the AD FS/Admin log we can see:
1. Log Name: AD FS/Admin Event ID: 336 The certificate management cycle was initiated.
2. Log Name: AD FS/Admin Event ID: 337 The certificate management cycle was completed.
| But those above are the only information you will get from ADFS when Signing or Encryption certificate are change from the partner. |
Federation Metadata
When creating a federation trust between Federation Services, we utilize the /FederationMetadata/2007-06/FederationMetadata.xml endpoint. This endpoint is enabled and enabled for proxy by default. The FederationMetadata.xml file is held in memory by the AD FS Windows service and is never written to disk, so if the AD FS Windows service is not running the FederationMetadata.xml data is not accessible.
Once the federation trust is created between partners, the Federation Service holds the Federation Metadata endpoint as a property of its partners, and uses the endpoint to periodically check for updates from the partner. For example, if an Identity Provider gets a new token-signing certificate, the public key portion of that certificate is published as part of its Federation Metadata. All Relying Parties who partner with this IdP will automatically be able to validate the digital signature on tokens issued by the IdP because the RP has refreshed the Federation Metadata via the endpoint.
The Federation Metadata.XML publishes information such as the public key portion of a token signing certificate and the public key of the Encryption Certificate. What we can do is creating a schedule process which:
- Download the partner FederationMetadata.XML
- Extrapolate the Signing and the Encryption certificates
- Compare the Thumbprints between these certificates and what the Federation Service has
- Create an event to inform the status of certificates: Error if different=certificates were updated
- From here there are then a number of secondary actions customer can take (emails, other tasks etc.).
Case1
Monitor the Relaying Party Trust certificates (From CONTOSO Vs SaaS provider offering the Application)
The script assumes the existence of an EventLog source: ADFSCert
You can create the source with the following line as an Administrator of the server:
New-EventLog –LogName Application –Source "ADFSCert"
From CONTOSO'S AD FS, the Identity Provider, I want to monitor the Signing and Encryption certificate with MISTERMIK'S SaaS Provider / Relying Party STS .
|
|
|
|
##DISCLAMER## #NO WARRANTY OF ANY KIND IS PROVIDED. THE ENTIRE RISK OF THE USE OR THE RESULTS FROM #THE USE OF THIS SCRIPT REMAINS WITH THE USER. #THIS SAMPLE CODE AND ANY RELATED INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY #OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED #WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE ## PROPERTIES $metadataurl = "https://adfs.identity.mistermik.com/FederationMetadata/2007-06/FederationMetadata.xml" $RPName = "adfs.identity.mistermik.com" try { [ xml ] $metadataDoc = ( Invoke-WebRequest $metadataUrl ) . Content } catch { Write-Error "There was an error downloading the metadata: $( $_ ) " return } ## LOAD FEDERATION METADATA $fedmd = Invoke-WebRequest -Uri $metadataurl $fedmdXml = New-Object Xml $fedmdXml . LoadXml($fedmd . Content) #$base64 = $fedmdXml.EntityDescriptor.RoleDescriptor.KeyDescriptor.KeyInfo.X509Data.X509Certificate ## SIGNING CERTIFICATE $Signing = ( $fedmdXml . EntityDescriptor . RoleDescriptor . KeyDescriptor | Where-Object {$_ . use -eq "signing" }) . KeyInfo . X509Data . X509Certificate Signing | Out-File -FilePath $RPName "_Signing.cer" -Append: $false $CertSign = Get-PfxCertificate -FilePath $RPName "_Signing.cer" $ThumbCertSign = $CertSign . Thumbprint #Remove-Item $RPName+"_Signing.cer" ## ENCRYPTION CERTIFICATE $Encrypt = ( $fedmdXml . EntityDescriptor . RoleDescriptor . KeyDescriptor | Where-Object {$_ . use -eq "encryption" }) . KeyInfo . X509Data . X509Certificate $Encrypt | Out-File -FilePath $RPName "_Encryption.cer" -Append: $false $CertEncr = Get-PfxCertificate -FilePath $RPName "_Encryption.cer" $ThumbCertEncr = $CertSign . Thumbprint #Remove-Item $RPName"_Encryption.cer" ## LOAD ADFS RP Cert Info $ADFS_RP_CertSign = ( Get-ADFSRelyingPartyTrust -Name $RPName ) . RequestSigningCertificate $ADFS_RP_ThumbCertSign = ( Get-ADFSRelyingPartyTrust -Name $RPName ) . RequestSigningCertificate . Thumbprint $ADFS_RP_CertEncr = ( Get-ADFSRelyingPartyTrust -Name $RPName ) . EncryptionCertificate $ADFS_RP_ThumbCertEncr = ( Get-ADFSRelyingPartyTrust -Name $RPName ) . EncryptionCertificate . Thumbprint $ResultSign = Compare-Object $CertSign $ADFS_RP_CertSign -property Thumbprint , Subject , Notafter -includeequal $strResultSign = $ResultSign | % { "`nThumbprint..: " + $_ . Thumbprint + "`nSubject..........: " + $_ . Subject + "`nNotAfter........: " + $_ . NotAfter + "`nSideIndicator.: " + $_ . SideIndicator} | Out-String $Monitor = Get-ADFSRelyingPartyTrust -Name $RPName | ? { $_ . Enabled -eq $true -And $_ . MetadataUrl -ne $null -And $_ . MonitoringEnabled -eq $true } | % { "`nName........................: " + $_ . Name + "`nLastMonitoredTime: " + $_ . LastMonitoredTime + "`nLastUpdateTime.....: " + $_ . LastUpdateTime} | out-string IF ( $ResultSign . SideIndicator -ne "==" ) { write-Host " $RPName Signing certificate was changed" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Error –EventID 1 –Message " $RPName Signing certificate - CHANGED $strResultSign ################################################## $Monitor " } ELSE { Write-Host " $RPName Signing certificate - OK" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Information –EventID 1 –Message " $RPName Signing certificate - OK $strResultSign ################################################## $Monitor " } $ResultEncr = Compare-Object $CertEncr $ADFS_RP_CertEncr -property Thumbprint , Subject , Notafter -includeequal $strResultEncr = $ResultEncr | % { "`nThumbprint..: " + $_ . Thumbprint + "`nSubject..........: " + $_ . Subject + "`nNotAfter........: " + $_ . NotAfter + "`nSideIndicator.: " + $_ . SideIndicator} | Out-String IF ( $ResultEncr . SideIndicator -ne "==" ) { write-Host " $RPName Encryption certificate was changed" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Error –EventID 1 –Message " $RPName Encrypting certificate - CHANGED $strResultEncr ################################################## $Monitor " } ELSE { Write-Host " $RPName Encryption certificate - OK" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Information –EventID 1 –Message " $RPName Encrypting certificate - OK $strResultEncr ################################################## $Monitor " }
|
Signing Certificates and Encryption Certificates were changed
|
Signing Certificate |
Encryption Certificate |
 |
 |
If all is good:
|
Signing Certificate |
Encryption Certificate |
 |
 |
Case2
Monitor the Claims Provider Trust certificates (From the SaaS provider offering the Application Vs my Customer IP/CONTOSO)
|
##DISCLAMER## #NO WARRANTY OF ANY KIND IS PROVIDED. THE ENTIRE RISK OF THE USE OR THE RESULTS FROM #THE USE OF THIS SCRIPT REMAINS WITH THE USER. #THIS SAMPLE CODE AND ANY RELATED INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY #OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED #WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE #Monitor the Claims Provider Trust certificates (From the SaaS provider offering the Application Vs CONTOSO IP) ## PROPERTIES $metadataurl = "https://adfs.oauth.mistermik.com/FederationMetadata/2007-06/FederationMetadata.xml" $CPT = "CONTOSO.COM" try { [ xml ] $metadataDoc = ( Invoke-WebRequest $metadataUrl ) . Content } catch { Write-Error "There was an error downloading the metadata: $( $_ ) " return } ## LOAD FEDERATION METADATA $fedmd = Invoke-WebRequest -Uri $metadataurl $fedmdXml = New-Object Xml $fedmdXml . LoadXml($fedmd . Content) #$base64 = $fedmdXml.EntityDescriptor.RoleDescriptor.KeyDescriptor.KeyInfo.X509Data.X509Certificate ## SIGNING CERTIFICATE $Signing = ( $fedmdXml . EntityDescriptor . RoleDescriptor . KeyDescriptor | Where-Object {$_ . use -eq "signing" }) . KeyInfo . X509Data . X509Certificate $Signing | Out-File -FilePath $RPName "_Signing.cer" -Append: $false $CertSign = Get-PfxCertificate -FilePath $RPName "_Signing.cer" $ThumbCertSign = $CertSign . Thumbprint #Remove-Item $RPName+"_Signing.cer" ## ENCRYPTION CERTIFICATE $Encrypt = ( $fedmdXml . EntityDescriptor . RoleDescriptor . KeyDescriptor | Where-Object {$_ . use -eq "encryption" }) . KeyInfo . X509Data . X509Certificate $Encrypt | Out-File -FilePath $RPName "_Encryption.cer" -Append: $false $CertEncr = Get-PfxCertificate -FilePath $RPName "_Encryption.cer" $ThumbCertEncr = $CertSign . Thumbprint #Remove-Item $RPName"_Encryption.cer" ## LOAD ADFS RP Cert Info $ADFS_CPT_CertSign = ( Get-AdfsClaimsProviderTrust -Name $CPT ) . TokenSigningCertificates $ADFS_CPT_ThumbCertSign = ( Get-AdfsClaimsProviderTrust -Name $CPT ) . TokenSigningCertificates . Thumbprint $ADFS_CPT_CertEncr = ( Get-AdfsClaimsProviderTrust -Name $CPT ) . EncryptionCertificate $ADFS_CPT_ThumbCertEncr = ( Get-AdfsClaimsProviderTrust -Name $CPT ) . EncryptionCertificate . Thumbprint $ResultSign = Compare-Object $CertSign $ADFS_CPT_CertSign -property Thumbprint , Subject , Notafter -includeequal $strResultSign = $ResultSign | % { "`nThumbprint..: " + $_ . Thumbprint + "`nSubject..........: " + $_ . Subject + "`nNotAfter........: " + $_ . NotAfter + "`nSideIndicator.: " + $_ . SideIndicator} | Out-String $Monitor = AdfsClaimsProviderTrust -Name $CPT | ? { $_ . Enabled -eq $true -And $_ . MetadataUrl -ne $null -And $_ . MonitoringEnabled -eq $true } | % { "`nName........................: " + $_ . Name + "`nLastMonitoredTime: " + $_ . LastMonitoredTime + "`nLastUpdateTime.....: " + $_ . LastUpdateTime} | out-string IF ( $ResultSign . SideIndicator -ne "==" ) { write-Host " $CPT Claims Provider Trust Signing certificate was changed" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Error –EventID 1 –Message " $CPT Claims Provider Trust Signing certificate - CHANGED $strResultSign ################################################## $Monitor " } ELSE { Write-Host " $CPT Claims Provider Trust Signing certificate - OK" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Information –EventID 1 –Message " $CPT Claims Provider Trust Signing certificate - OK $strResultSign ################################################## $Monitor " } $ResultEncr = Compare-Object $CertEncr $ADFS_CPT_CertEncr -property Thumbprint , Subject , NotAfter -includeequal $strResultEncr = $ResultEncr | % { "`nThumbprint..: " + $_ . Thumbprint + "`nSubject..........: " + $_ . Subject + "`nNotAfter........: " + $_ . NotAfter + "`nSideIndicator.: " + $_ . SideIndicator} | Out-String IF ( $ResultEncr . SideIndicator -ne "==" ) { write-Host " $CPT Claims Provider Trust Encryption certificate was changed" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Error –EventID 1 –Message " $CPT Claims Provider Trust Encrypting certificate - CHANGED $strResultEncr ################################################## $Monitor " } ELSE { Write-Host " $CPT Claims Provider Trust Encryption certificate - OK" Write-EventLog –LogName "Application" –Source "ADFSCert" –EntryType Information –EventID 1 –Message " $CPT Claims Provider Trust Encrypting certificate - OK $strResultEncr ################################################## $Monitor " } |
Signing Certificates and Encryption Certificates were changed
|
Signing Certificate |
Encryption Certificate |
 |
 |
If all is good:
|
Signing Certificate |
Encryption Certificate |
 |
 |
Signing Certificate was changed from the Partner Federation Service. I also write when the trust was last monitored and Updated. Be aware, that the 'LastMonitoredTime' is updated, whether or not the monitoring was successful. THAT'S IT!!!!
We introduced today a solution which included the establishment of a claims-based architecture with an issuer that acts as an identity provider (IdP/IP) on the customers' side and an issuer that acts as the federation provider (FP) on Mistermik.com side: a gateway between a resource and all of the issuers that provide claims about the resource's users.
As part of my Mix and Match series , we went through concepts and terminologies of the Identity metasystem, understood how all the moving parts operates across organizational boundaries.
We discussed the certificates involvement in AD FS and how I can use PowerShell to create a custom monitor workload and a proper logging which can trigger further automation.
I hope you have enjoyed and that this can help you if you land on this page.
Michele Ferrari ( MisterMik )
Premier Field Engineer