How to Register a Dynamics Application with ADFS

During a recent project, we began developing an application that would use the WebAPI. The application is for a client that is using Dynamics 365 On-Premises. For this setup, we used ADFS 4.0 and Dynamics 365. There is a lot of documentation from Microsoft on this process, if you are familiar with CRM development there are usually some slight differences for doing things in a Dynamics Online versus On-Prem environment. However, sometimes the documentation for on-premises misses a step or two.

The majority of the steps to get an application registered with Active Directory can be found here on MSDN, we're just missing one small detail that can cause some non-descript ADFS errors like this:

In the article, it fails to mention the fact that we need to grant Application Permissions to the application within ADFS. Fortunately, this is a pretty easy thing to do. Just open a PowerShell prompt on your ADFS server and enter the following:

Grant-AdfsApplicationPermission -ClientRoleIdentifier "clientid" -ServerRoleIdentifier "Dynamics URL" -ScopeNames openid

After running the command, you should get a token the next time that you attempt it.

Once we started using the Web API with our API testing console, we examined the token and observed that the token was not issuing a refresh token to use. Microsoft recommends refreshing the token with every call, so this was a problem. Fortunately, this was a problem that a few minutes of research could solve; see the PowerShell below to allow the issuance of the refresh token.

Set-AdfsRelyingPartyTrust -TargetName "RelyingPartyFromADFS" -IssueOAuthRefreshTokensTo AllDevices

If you're still not receiving a refresh token as part of an authentication response after making this change, make sure that the SSOLifetime parameter is greater than the TokenLifetime by running the Get-ADFSProperties PowerShell. A refresh token will not be issued otherwise.

For more Dynamics 365 troubleshooting, how-tos, and tips – check out our blog!

Happy Dynamics 365'ing!