Dynamics 365 Identity Federation Using ADFS

One of the challenging requirements we face during the delivery of Dynamics 365 projects is to allow users from external domain to access CRM using their existing domain accounts without creating new accounts in the CRM domain. To achieve such requirements we have 2 options:

1. Establish domain trust between the CRM domain and the external domain, this option is an old style approach and not secure.
2. Utilize ADFS servers and WAP proxy servers to establish the user authentication trust in a secure and modern way which is what this series will be talking about.

Due to the complexity of such identity federation option, we will be talking about it in a series of articles, first article will be mainly about understanding the terminologies and building the foundation of how ADFS works as identity federation provider to authenticate internal & external users, that requires a good infrastructure Knowledge in addition to the Dynamics 365 architecture knowledge.

What is ADFS?

Active Directory Federation Service is currently a windows server component that Microsoft proposes for Single sign on scenarios. ADFS 3.0 is part of Windows Server 2012 and the latest version is ADFS 4.0 which is part of Windows Server 2016.

What are SAML tokens?

As per Microsoft docs:

Security Assertions Markup Language (SAML) tokens are XML representations of claims. SAML tokens carry statements that are sets of claims made by one entity about another entity. For example, in federated security scenarios, the statements are made by a security token service about a user in the system. The security token service signs the SAML token to indicate the veracity of the statements contained in the token. In addition, the SAML token is associated with cryptographic key material that the user of the SAML token proves knowledge of. This proof satisfies the relying party that the SAML token was, in fact, issued to that user.

Its important to note that SAML is a standard type of token and has more than one version, first version was SAML 1.0, then 1.1 which wasn’t very marture and now the latest version is SAML 2.0 which is widely adopted.

What are the main ADFS components?

1. Service:
   1. Endpoints: the most important end points are the following:
      1. ADFS Login page: https://server/adfs/ls/IdpInitiatedSignOn.aspx
      2. ADFS Federation metadata URL: https://server/FederationMetadata/2007-06/FederationMetadata.xml
         • The SAML token claims as well as the SAML encryption certificate are described in that downloadable XML file.
   2. Certificates: whenever a certificate gets expired, it must be renewed and the other identity providers using the federation metadata URL must update their reference.
      1. Service Communication Certificate: must be publicly signed certificate.
      2. Token Signing Certificate: usually self-signed. (can be multiple but only one is primary)
      3. Token Decrypting Certificate: usually self-signed. (can be multiple but only one is primary)
2. Authentication Policies: make sure to enable forms authentication
3. Trust Relationships:
   1. Claims Provider Trusts: this is having the list of trusted identity providers.
   2. Relying Party Trusts: this is having the list of trusted applications or other identity providers.

How the ADFS authentication process works?

ADFS authentication process is illustrated in the article’s main diagram in 11 steps that can be found below in more details:

1. The Client access Dynamics 365 Web app public URL.

2. Dynamics 365 redirects the client to the primary ADFS home page (ADFS hosted under same Dynamics 365 domain)

3. The user access the primary ADFS home page and selects one of the identity provider options as shown below, the blue icon represents the primary ADFS, other black icons are for other trusted identity providers.

4. The main ADFS redirects the client to the selected identity provider home page for authentication.

5. The client lands in the login page for the selected identity provider and enters username and password to be authenticated by the identity provider.

6. The ADFS authenticates the client with the domain controller, if the client is authenticated successfully, a SAML token is issued for the client to be presented to the primary ADFS.

7. Client is redirected back to the primary ADFS.

8. Client posts the SAML token generated from his identity provider to the primary ADFS.

9. Primary ADFS processes the client SAML token by applying the claim rules configured for this claims identity provider, issues a new SAML token, and redirects the client to Dynamics 365 Web App.

10. Client presents the SAML token generated from the primary ADFS to Dynamics 365 Web App.

11. Client is granted appropriate access to Dynamics 365 Web App.

In next article we will be talking more about the required configuration steps to achieve such identity federation requirement.