Dynamics 365 (On-Premise)
This page explains how to integrate Unaric Sidebar with an on-premise instance of Microsoft Dynamics 365, using Active Directory Federation Services and OAuth2 authentication.
In this tutorial, you will set up an ADFS oAuth2 client id, grant the required permissions, and configure token settings to enable secure communication between the connector and your Dynamics environment.
These instructions apply specifically to internet-facing deployments (IFD), where both Dynamics 365 and Active Directory Federation Services (ADFS) are accessible externally. Your Dynamics and ADFS need to be publicly reachable, otherwise, the connector won’t work.
Prerequisites
Before you start, make sure you have:
- Administrator access to the ADFS server and to the Dynamics 365 server, and an elevated PowerShell session on each.
- The base URL of your Dynamics 365 on-premise instance.
- The base URL of your ADFS server.
Register an oAuth2 client in ADFS
1. Register new client application to use with Unaric Sidebar
You need to create separate clients for Unaric Sidebar add-on and Automatic sync, depends on what you are using.
Component | Redirect URI |
|---|---|
Unaric Sidebar add-in | https://outlook.ienterprises.com/outlook/mscrm/src/taskpane/app/oauth/token.html |
Automatic Sync | https://isync.ienterprises.com/oauth2client/mscrm.php |
- Choose a client ID. ADFS doesn't generate one for you. Microsoft recommends a globally unique identifier (GUID). In PowerShell 5.1 or later, you can create one with New-Guid.
- On the ADFS server, in an administrative PowerShell session, run:
Add-AdfsClient -ClientId "<ClientId>" -Name "<ClientName>" -RedirectUri "<RedirectUri>"- ClientId: the client ID you chose in step 1. You'll use this value again when you grant permissions and when you connect Unaric Sidebar.
- ClientName: a display name for the client in ADFS.
- RedirectUri: the redirect URI for the component you're registering, from the table above. It must match exactly, including any trailing slash.
- Record the client ID. The command doesn't display output unless you add -PassThru. To view registered clients later, run Get-AdfsClient.
For more information on this process, see Microsoft documentation, Add-AdfsClient.
2. Grant application permission to Dynamics 365
- On the ADFS server, in an admin PowerShell session, run:
Grant-AdfsApplicationPermission -ClientRoleIdentifier "clientid" -ServerRoleIdentifier "Dynamics URI" -ScopeNames openid, user_impersonation- ClientId: the same client ID you used when you registered the client.
- RelyingPartyIdentifier: an identifier of your Dynamics 365 IFD relying party trust, exactly as ADFS lists it, including the trailing slash; for example, https://auth.contoso.com:444/.
- Restart the ADFS service:
net stop adfssrv
net start adfssrv For more information on this process, see Microsoft documentation, Grant-AdfsApplicationPermission.
Set token lifetime
Refresh tokens let Unaric Sidebar renew access without asking users to sign in again. To issue refresh tokens and set token lifetimes, on the ADFS server, in an admin PowerShell session, run:
Set-AdfsRelyingPartyTrust -TargetName "<RelyingPartyTrustName>" -IssueOAuthRefreshTokensTo AllDevices
Set-AdfsRelyingPartyTrust -TargetName "<RelyingPartyTrustName>" -TokenLifetime 10
Set-AdfsProperties -SsoLifetime 20160- RelyingPartyTrustName: the display name of your Dynamics 365 relying party trust in ADFS. To use its identifier instead, replace -TargetName` with -TargetIdentifier.
For more information on this process, see Microsoft documentation, Set-AdfsRelyingPartyTrust and Set-AdfsProperties.