Creating a Custom OAuth Application

Microsoft Dynamics CRM supports authentication using Azure AD and Azure Service Principal, both of which are OAuth-based.

This topic describes how to:

• create and register custom OAuth application for Azure AD or Azure Service Principal
• provide Admin Consent to a custom OAuth application
• create a custom OAuth application for use with client credentials

Azure AD

In portal.azure.com:

1. Log in to https://portal.azure.com.
2. In the left-hand navigation pane, select Azure Active Directory, then applicationRegistrations.
3. Click New registration.
4. Enter a name for the application.
5. Select the desired tenant setup: single- or multi-tenant, and public or private use.
   • If you select the default option, "Accounts in this organizational directory only", you must set the AzureTenant connection property to the Id of the Azure AD Tenant when establishing a connection with the CData JDBC Driver for Microsoft Dynamics CRM. Otherwise, the authentication attempt fails with an error.
   • If your application is for private use only, specify Accounts in this organization directory only.
   • If you want to distribute your application, choose one of the multi-tenant options.

6. Set the redirect url to http://localhost:33333 (the driver's default) OR specify a different port and set CallbackURL to the exact reply URL you defined.
7. Click Register to register the new application. An application management screen displays.
   Note the value in Application (client) ID as the OAuthClientId and the Directory (tenant) ID as the AzureTenant.
8. Navigate to Certificates & Secrets and define the application authentication type. There are two types of authentication available: certificate (recommended) or client secret.
   • For certificate authentication: In Certificates & Secrets, select Upload certificate, then upload the certificate from your local machine.
   • For creating a new client secret: In Certificates & Secrets, select New Client Secret for the application and specify its duration. After the client secret is saved, Microsoft Dynamics CRM displays the key value. Copy this value, as it is displayed only once. This value becomes the OAuthClientSecret.

9. Select API Permissions > Add > Delegated permissions.
10. Select Required Permissions and then click Add. Under Select an API, select the Dynamics ERP -> Delegated Permissions for OAuthGrantType = CODE (default). If using OAuthGrantType = CLIENT, select from the Application Permissions.
11. Save your changes.
12. If you have specified the use of permissions that require admin consent (such as the Application Permissions), you can grant them from the current tenant on the API Permissions page.
13. Go to the Dynamics CRM instance and create an application user. We need to give this user a role to interact with entities in CRM. Go to https://your-instance.crm1.dynamics.com/, then navigate to Settings => Security => Users. Set the Application ID from the App Registration step.

Azure Service Principal

To use Azure Service Principal authentication, you must set up the ability to assign a role to the authentication application, then register an application with the Azure AD tenant to create a new Service Principal. That new Service Principal can then leverage the assigned role-based access control to access resources in your subscription.

In portal.azure.com:

1. Create a custom OAuth AD application, as described above.
2. Use the search bar to search for the Subscriptions service.
3. Open the Subscriptions page.
4. Select the subscription to which to assign the application.
5. Open the Access control (IAM).
6. Select Add > Add role assignment. Microsoft Dynamics CRM opens the Add role assignment page.
7. Assign your custom Azure AD application the role of Owner.

Admin Consent

Some custom applications require administrative permissions to operate within an Azure Active Directory tenant. Admin consent can be granted when creating a new custom OAuth application, by adding relevant permissions that are already marked with "Admin Consent Required". Admin consent is also required to use Client Credentials in the OAuth flow.

To grant admin consent:

1. Have an admin log in to portal.azure.com.
2. Navigate to App Registrations and find the custom OAuth application you created.
3. Under API Permissions, click Grant Consent.

This gives your application permissions on the tenant under which it was created.

Consent for Client Credentials

OAuth supports the use of client credentials to authenticate. In a client credentials OAuth flow, credentials are created for the authenticating application itself. The auth flow acts just like the usual auth flow except that there is no prompt for an associated user to provide credentials. All tasks accepted by the application are executed outside of the context of a default user.

Note: Since the embedded OAuth credentials authenticate on a per-user basis, you cannot use them in a client OAuth flow. You must always create a custom OAuth application to use client credentials.

In portal.azure.com:

1. Create a custom OAuth application, as described above.
2. Navigate to App Registrations.
3. Find the application you just created, and open API Permissions.
4. Select the Microsoft Graph permissions. There are two distinct sets of permissions: Delegated and Application.
5. Under Application Permissions, select the permissions you require for your integration.