ADFS: Monitoring a Relying Party for Certificate Changes

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-oauth/

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 CONTOSOJohn’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:

Step : Present Credentials to the Identity Provider

1.1. When John from CONTOSO.COM attempts to use ClaimsWeb App for the first time (that is, when he first navigates to https://clamisweb.mistermik.com ), there’s no session established yet. In other words, from an identity’s point of view, the User is unauthenticated. The URL provides the application with a hint about the customer that is requesting access

1.2. The application redirects John’s browser to the Identity’s issuer (the federation provider/AD FS). That is because MISTERMIK.COM’S federation provider is the application’s trusted issuer. As part of the redirection URL, the application includes the whr parameter that provides a hint to the federation provider about the customer’s home realm. The value of the whr parameter is http://contoso/trust.

1.3. The MISTERMIK.COM ‘s federation provider uses the whr parameter to look up the customer’s Identity Provider and redirect John’s browser back to CONTOSO issuer.

Assuming that John uses a computer that is already a part of the domain and in the corporate network, he will already have valid network credentials that can be presented to CONTOSO.COM’s Identity provider.

1.4. CONTOSO.COM’s Identity provider uses the User’s credentials to authenticate him and then issue a security token with a set of CONTOSO.COM’s claims. These claims are for instance the Username, Group Membership and other attributes.

Step : Transmit the Identity Provider’s Security Token to the Federation Provider

2.1. At this point the Identity Provider’s Federation Service transforms the organization claims to a set of outgoing claims. The outgoing claims are sent to the Federation Service of the resource provider, MISTERMIK.COM.
The CONTOSO’S Identity Provider uses HTTP redirection to redirect the security token it has issued to MISTERMIK.COM’s federation provider.

2.2. MISTERMIK.COM’s federation provider receives this token and validates it.

Step : Map the Claims

3.1. MISTERMIK.COM’s federation provider applies token mapping rules to the CONTOSO’s Identity Provider security token. The claims are transformed into something that ClaimsWeb Application understands.

3.2. The federation provider uses HTTP redirection to submit the claims to the User’s browser (John).

Step : Transmit the Mapped Claims and Perform the Requested Action

4.1. The browser sends the federation provider’s security token, which contains the transformed claims, to the ClaimsWeb Application.

• 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
    

The Relying Party trust provides the configuration that is used to create claims. Once the claim is created, it can be presented to another Active Directory Federation Service or claim aware application.

Claim provider trust determines what happens to the claims when it arrives.

Let’s apply what we discussed here to our practical example:

Claims Provider Trusts and Relying Party Trusts

In order to accept incoming claims from a Claims Provider (IdP-STS), you must first establish trust by creating a Claims Provider Trust on your Relying Party (RP-STS). (Gatekeeper).
èMISTERMIK.COM (RP-STS) ——-Claims Proivider Trust—à CONTOSO.COM (IdP)

In order to send outgoing claims from your IdP-STS, you must first establish a trust by creating a Relying Party Trust on your IdP-STS. A Relying Party Trust can be another STS which is relying on claims from your STS.
èCONTOSO.COM (IdP) ————–Relying Party Trust—à MISTERMIK.COM (Resource Provider)

MISTERMIK.COM has a Relying Party Trust à ClaimsWeb Application, which close the circuit as Relying Party Trust can be a web application or service which is relying on claims from your STS.

Properties of a Trust Relationship

Monitoring – The Federation Metadata URL is used to obtain policy from the partner STS. This policy information is pulled on a regular interval which is called trust monitoring. Trust monitoring can be disabled and the pulling interval can be modified.

Identifiers – Display Name determines how the trust is viewed in the AD FS MMC and also how it appears on the home realm discovery page. The Claims provider/relying party identifier is a unique identifier in URI format. The default identifier for AD FS STS’s is http://{dns_name}/adfs/services/trust.

Certificates – The public key portion of the Claims Provider partner’s token-signing certificate is stored.

Encryption – The public key portion of the partner’s token-encryption certificate is stored.

Signature – This is the verification certificate for a Relying Party used to verify the digital signature for incoming requests from this Relying Party.

Offered Claims – The Claim Descriptions that are published by the Claims Provider partner STS are shown. If the Claim Type of the Claim Description matches the Claim Type of a Claim Description on your STS, then the display name is shown. Otherwise, you will see the Claim Type of the offered claims.

Now that we’ve reviewed the basics, discussed the moving parts and broke the flow in detail and understood their correlation, we’re ready to make the next step into certificates and why is so important these are up-to-date.

Certificates

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-certificates

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.

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.

This tab governs how AD FS manages the updating of this claims provider trust. You can see that the Monitor claims provider check box is checked. This indicates that AD FS will periodically check the Federation Metadata URL shown in the dialog and compare it with the current state of the claims provider trust.

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.

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:

1. Download the partner FederationMetadata.XML
2. Extrapolate the Signing and the Encryption certificates
3. Compare the Thumbprints between these certificates and what the Federation Service has
4. Create an event to inform the status of certificates: Error if different=certificates were updated
5. 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”

More Info: https://blogs.technet.microsoft.com/heyscriptingguy/2013/06/20/how-to-use-powershell-to-write-to-event-logs/

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.

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)

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