Set up an AD FS Federation Trust between two Organizations
In this post we will configure an AD FS trust with an partner organization, in order to allow users to access resources from the partner organization.
In an AD FS Partner Trust, you have two organization roles from which one is the Account Partner and the other is the Resource Partner.
About account partner organizations
An account partner is the organization in the federation trust relationship that physically stores user accounts in an AD FS–supported attribute store. The account partner is responsible for collecting and authenticating a user’s credentials, building up claims for that user, and packaging the claims into security tokens. These tokens can then be presented across a federation trust to enable access to Web-based resources that are located in the resource partner organization.
In other words, an account partner represents the organization for whose users the account-side federation server issues security tokens. The federation server in the account partner organization authenticates local users and creates security tokens that the resource partner uses in making authorization decisions.
With regard to attribute stores, the account partner in AD FS is conceptually equivalent to a single Active Directory forest whose accounts need access to resources that are physically located in another forest. Accounts in this forest can access resources in the resource forest only when an external trust or forest trust relationship exists between the two forests and the resources to which the users are trying to gain access have been set with the proper authorization permissions.
About resource partner organizations
The resource partner is the organization in an AD FS deployment where Web servers are located. The resource partner trusts the account partner to authenticate users. Therefore, to make authorization decisions, the resource partner consumes the claims that are packaged in security tokens that come from users in the account partner.
In other words, a resource partner represents the organization whose Web servers are protected by the resource-side federation server. The federation server at the resource partner uses the security tokens that are produced by the account partner to make authorization decisions for Web servers in the resource partner.
To function as an AD FS resource, Web servers in the resource partner organization must either have Windows Identity Foundation (WIF) installed or have the Active Directory Federation Services (AD FS) 1.x Claims-Aware Web Agent role services installed. Web servers that function as an AD FS resource can host either Web-browser-based or Web-service-based applications.
In my case I will use my lab environment braintesting.de as the account partner and my production environment as the resource partner.
Account Partner -> braintesting.de
Resource Partner -> <domain production env>.de
Finally users from braintesting.de should be able to access web applications in <domain production env>.de using their own braintesting.de accounts.
How to set up an AD FS environment you can read my following post.
First I will create a Relying Party Trusts on the Account Partner braintesting.de.
So click on Add Relying Party Trust …
Select Claims aware
Here select Import data about the relying party published online or on a local network and paste the Federation metadata address from the ressource partners AD FS server, my production server.
https://fs.<domain resource partner>.de/FederationMetadata/2007-06/FederationMetadata.xml
Enter the display name for this relying party.
Leave the default Permit everyone Access Control Policy.
Besides open directly the Federation Metadata site from the resource partners AD FS server, you can also check if it works directly on the relying party trust settings.
The relying party trust was successfully added.
Now we need to configure a claims issuance policy for the resource partner.
Therefore click on Edit Claim Issuance Policy and add a rule.
Under Claim rule template we use Send LDAP Attributes as Claims
For the mapping I will use the Active Directory attribute User-Principal-Name and map it into the outgoing claim type UPN.
So far we finished the configuration for the account partner braintesting.de.
Now secondly I will create a Claims Provider Trusts on the Resource Partner domain which is my productive environment with the web applications the lab environment wants to access.
On the resource partner AD FS server open AD FS -> Claims Provider Trusts and click on Add Claims Provider Trust … as follows.
Here the same as previously on the account partner. Select Import data about the relying party published online or on a local network and paste the Federation metadata address, but this time from the account partners AD FS server braintesting.de, my lab environment.
Type the display name for this claims provider
Click on Next
The claims provider trusts was successfully added.
Now we need to configure a claims issuance policy for the created claims provider trusts.
Therefore click on Edit Claim Rules … and we have to create two new Pass Through or Filter an Incoming Claim rule.
This time we use instead the Send LDAP Attributes as Claims template the Pass Through or Filter an Incoming Claim template.
The reason for is, that we configure here on the resource partner the claims we get from the account partner which are still claims and not LDAP attributes. The account partner (braintesting.de) received the LDAP attributes from his AD and send them outgoing to the resource partner (my production env with the web applications) as claims from the type Name and UPN, so the resource partner AD FS server only have to pass them through the web application.
So far we configured successfully the Federation Trust between my lab environment braintesting.de and my production environment.
To test if the trust is working we can use the ADFS Sign-In Page
AD FS Troubleshooting – Idp-Initiated Sign On
The AD FS sign-on page can be used to test whether or not authentication is working. This is done by navigating to the page and signing in. Also, we can use the sign-in page to verify that all SAML 2.0 relying parties are listed.
Therefore I opened the ADFS Sign-In Page from the resource partner (my production AD FS server) on a computer and with an account within the account partner environment braintesting.de.
After clicking on Sign in, I can choose between two different account providers, fs.braintesting.de which represents the previously created Claim Provider Trust on the resource partner, and the default Active Directory which represents the own Realm of the production environment and AD.
As I want to test access from the account partner (braintesting.de) to the resource partner (my production environment) I will have to select fs.braintesting.de.
Now I need to enter a username and password from the account partner which wants to access the production environment.
As you can see, the resource partner AD FS server (my production env), will redirect me to the account partner AD FS server (my lab env), to login with my credentials from the lab environment.
After providing my lab credentials, the account partner AD FS server (my lab env), will redirect me back to the resource partner AD FS server and provides here the claims for the ADFS Sign-In Page to log me in, which here will fail.
Therefore I checked the logs on both ADFS servers.
On the resource partner (my production env), I will find the following error message in the Event Viewer under the AD FS Admin logs.
Encountered error during federation passive request.
Microsoft.IdentityServer.Protocols.Saml.SamlException: MSIS7012: An error occurred while processing the request. Contact your administrator for details.
at Microsoft.IdentityServer.Web.Protocols.Saml.SamlProtocolHandler.GetSecurityTokenFromSignInResponse(ProtocolContext context)
at Microsoft.IdentityServer.Web.PassiveProtocolListener.ProcessProtocolRequest(ProtocolContext protocolContext, PassiveProtocolHandler protocolHandler)
at Microsoft.IdentityServer.Web.PassiveProtocolListener.OnGetContext(WrappedHttpListenerContext context)
On the account partner (my lab environment braintesting.de), I found also an error messages in the logs from AD FS.
Microsoft.IdentityServer.Service.SecurityTokenService.RevocationValidationException: MSIS3014: The encryption certificate of the relying party trust ‘https://fs.<domain prod env>.de/adfs/services/trust’ identified by thumbprint ‘D1244F8C114D1A1DD6B86EB05BF373DE27E1D994’ is not valid. It might indicate that the certificate has been revoked, has expired, or that the certificate chain is not trusted.
In my case the account partner (my lab AD FS server braintesting.de), didn’t trust the encryption certificate from the resource partner (my production AD FS server).
The encryption certificate on the resource partner (my production AD FS server), didn’t use the by default self-signed installed certificate and instead used one from the internal CA.
On his part the account partner AD FS server from the lab environment, haven’t installed the root certificate from this CA and so didn’t trust this encryption certificate and therefore the login will failed.
So after installing the root certificate on the account partner AD FS server, the login from the lab environment into the AD FS Logon Page from the resource partner AD FS server and my production environment, was successful.
As workaround instead installing the root certificate on the account partner AD FS server, you can disable the revocation check, which will also disable the chain validation for the encryption certificate. The same you can do with the token-signing certificate as follows.
On the account partner in my case as the resource partner is using an encryption certificate from the internal CA.
set-adfsrelyingpartytrust -targetname “relying party trust name” -encryptioncertificaterevocationcheck none
set-adfsrelyingpartytrust -targetname “relying party trust name” -signingcertificaterevocationcheck none
The same you can do on the resource partner with the following cmdlets
Set-AdfsClaimsProviderTrust -targetname “relying party trust name” -encryptioncertificaterevocationcheck none
Set-AdfsClaimsProviderTrust -targetname “relying party trust name” -signingcertificaterevocationcheck none
If you will using the by default installed self-signed certificates for encrytion/decrytion and token-signing, there will be no certificate chain validation and revocation status checking in AD FS, as there of course for self-signed certificates is no chain and available revocation list (CRL).
In contrast for every certificate using from an CA, certificate chain validation is done!
In a production scenario, in contrast to the test above with the ADFS Sign-In Page, the Sign-In process will looks like this simplified:
- first you browse to the web application (Service Provider SP).
- then as the web application is configured to be claims aware (WS-Trust, WS-Federation, SAML 2.0 WEB SSO, Open ID) and with the AD FS Authority URL, it will redirect you to the AD FS Server (Identity Provider IdP) with a generated request (SAML request or in case of the WS-* and OpenID protocols, conform parameters send in the URL to the specified protocols) .
- as we configured an AD FS Trust with an external partner organization, the AD FS server will show me two different account providers as described above. Here I have first to choose if I want to sign-in with an user from the partner organization or with an user from my own Active Directory.
If I will select the account provider from the partner organization, the AD FS server will redirect me to the partners AD FS server (account partner).
- now we have to authenticate to the AD FS Server (own AD FS server or partner AD FS server dependent on the previously choice)
- if the validation was successful, the AD FS server (Identity Provider IdP) issues a claims token (SAML assertion) to the client and redirects it back with the claims token to the web application (Service Provider SP). The web application then validates the token.
Don’t be confused that also WS-Federation issues SAML 1.1 token. The WS-Federation and SAML 2.0 protocol uses both the SAML format for their tokens.
In case you choose above the account provider from the partner organization, the AD FS server from the partner organization (account partner), will redirect the client with the claims token (SAML assertion) back to the AD FS server from the production environment.
Then the AD FS server from the production environment (resource partner) will validate the token and issues on his part also a token to the client that was configured for the partner trust with the Pass Through rules and the web application.
The client finally will get redirected to the web application (Service Provider SP) with an HTTP POST and the SAML response from the production ADFS server (resource partner) to authentication and authorize against the web application.
The claim token will be stored in a session cookie at the client, so this process doesn’t need to traverse each time the client wants to access the web application.
The following figure from wikipedia is regarding the SAML protocol flow but will not really be much different from the WS-Federation protocol flow.
user agent (usually a web browser)
Service Provider (our web application)
Identity Provider (AD FS Server)
In a partner trust scenario, the claims will looks like the following parts
You can see that we have here both issuers, the resource partner and the account partner.
The resource partner is listed as Issuer and the account partner as Original Issuer.
wa=wsignin1.0&wresult=<t:RequestSecurityTokenResponse xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust"><t:Lifetime> <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing"><wsa:Address>https://asp-auth.braincourt.net</wsa:Address></wsa:EndpointReference> <saml:Assertion MajorVersion="1" MinorVersion="1" AssertionID="_98d83453453535354345343d5911c92" Issuer="https://fs.braincourt.de/adfs/services/trust" IssueInstant="2021-05-07T14:46:54.699Z" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"> <saml:Audience>https://asp-auth.braincourt.net</saml:Audience> <saml:Attribute AttributeName="name" AttributeNamespace="http://schemas.xmlsoap.org/ws/2005/05/identity/claims" a:OriginalIssuer="http://fs.braintesting.de/adfs/services/trust" xmlns:a="http://schemas.xmlsoap.org/ws/2009/09/identity/claims"><saml:AttributeValue>John Doe</saml:AttributeValue></saml:Attribute><saml:Attribute AttributeName="upn" AttributeNamespace="http://schemas.xmlsoap.org/ws/2005/05/identity/claims" a:OriginalIssuer="http://fs.braintesting.de/adfs/services/trust" xmlns:a="http://schemas.xmlsoap.org/ws/2009/09/identity/claims"><saml:AttributeValue>firstname.lastname@example.org</saml:AttributeValue>
Configure Claims for your web application using by internal users and users from the partner trust configured above
If users from both environments wants to connect to your web application, you need to configure the Claim Issuance Policy as follows.
For the partner trust I configured above two Pass Through or Filter an Incoming Claim rules, therefore if a user from the partner trust will login to the web application, I need to create also two Pass Through or Filter an Incoming Claim rules for the web application (our relying party trusts on the resource partner) which includes the Name and UPN type.
For internal users from the resource partner site, I will configure a Send LDAP Attributes as Claims rule which will request from the AD the Display Name and User Principal Name attribute and send them outgoing to the web application also as Name and UPN type.
Generating a new self-signed certificate manually prior to the end of the grace period
# Check the current certificates
Get-ADFSCertificate –CertificateType token-signing
Get-ADFSCertificate –CertificateType Token-Decrypting
# To generate a new certificate, execute the following command to renew and update the certificates on the AD FS server:
Update-ADFSCertificate –CertificateType token-signing
Update-ADFSCertificate –CertificateType token-decrypting
# In order to to set the newly created self-signed certificates as primary, you need to disable AutoCertificateRollover temporarily and enable it again after changing to primary. If it is enabled, the option Set as Primary will be greyed out.
Set-AdfsProperties -AutoCertificateRollover $false
Set-AdfsProperties -AutoCertificateRollover $true
Update Federation Metadata (account partner & resource partner)
Claims Provider Trust
You can update the claims provider trust on the resource partner from the federation metadata of the account partner with the AD FS console or with a powershell cmdlet as follows.
Update-AdfsClaimsProviderTrust -TargetName “fs.braintesting.de”
By default Auto Update from the Federation Metadata is enabled and can changed with the Set-AdfsClaimsProviderTrust cmdlet.
Relying Party Trusts
The same is available for the relying party trust on the account partner to update the federation metadata from the resource partner.
Update-AdfsRelyingPartyTrust -TargetName “Partner Trust with Resource Partner braincourt.de”
By default Auto Update from the Federation Metadata is also enabled and can changed with the Set-AdfsRelyingPartyTrust cmdlet.
Configuring Partner Organizations
AD FS Overview