OAuth is an open protocol that allows a client application to access data from a protected resource through token exchange. OAuth tokens are permissions granted to a particular client. In Dynamics 365, OAuth 2.0 authorization can be used to approve client access to your organization's protected resources.

To access Dynamics 365 resources, you need an appropriate account. The authorization server verifies the account credentials and issues access tokens granting a client application access to specific protected resources. These tokens are then transmitted to the resource server, which verifies them and approves access to the protected resource. The OAuth 2.0 token exchange process can be handled automatically by the dotConnect for Dynamics 365 components or configured manually by the developer.

To maintain continuous access, the authorization server also issues refresh tokens. Refresh tokens allow the client application to request new access tokens without requiring you to re-authenticate. When connecting to a Dynamics 365 server using the DynamicsConnection component, you need to specify a refresh token.

This article describes ways to obtain the OAuth 2.0 refresh token and set up a connection.

Connecting with default OAuth 2.0 credentials

When using OAuth 2.0 with default credentials, you can obtain tokens automatically through an interactive process or manually to have more control over the authentication flow.

Automatic token acquisition

The interactive method for obtaining a token is the simplest way to set up a connection. With this method, DynamicsConnection will prompt you to log in to the authorization server, request a token from this server, and then transmit the received token to the resource server to gain access to the data. You can specify the connection method in the Authentication Type connection parameter.

With the following code, all the actions described above will be performed during the connection.

var connection = new DynamicsConnection("Authentication Type=RefreshTokenInteractive");
connection.Open();

Note: When the Open method is executed, the Dynamics 365 authorization page will open in a default browser window. You will need to log in and complete all necessary steps to confirm authorization.

Manual token acquisition

You can use the following code to obtain a refresh token without connecting to the resource server.

var oAuthBuilder = new DynamicsConnectionStringBuilder();
await DynamicsOAuthAuthenticationProvider.Default.ApplyAsync(oAuthBuilder);
var refreshToken = oAuthBuilder.RefreshToken;

When the ApplyAsync method is executed, you will be prompted to log in to the authorization server, and then a refresh token will be requested from this server.

After the ApplyAsync method is executed, the parameters obtained as a result of authorization will be set in the oAuthBuilder object. For example, the oAuthBuilder.RefreshToken property will contain the token received from the authorization server.

You can save or pass this token to DynamicsConnection to connect to the resource server.

var connection = new DynamicsConnection("Authentication Type=RefreshToken;RefreshToken={refreshToken}");
connection.Open();

Connecting with your own OAuth 2.0 credentials

If you want to create an application with your own credentials, independent of Devart settings, you can set existing credentials using the ConnectionStringBuilder or the OAuthAuthenticationProviderOptionsBuilder classes.

Using ConnectionStringBuilder

Create a ConnectionStringBuilder to set up OAuth 2.0 authentication parameters and connect to the Dynamics 365 server.

// Create a ConnectionStringBuilder
var connectionBuilder = new DynamicsConnectionStringBuilder();

// Specify the interactive mode in the Authentication field
connectionBuilder.Authentication = AuthenticationType.RefreshTokenInteractive;

// Set the authorization parameters
connectionBuilder.Server = Server;
connectionBuilder.UserId = UserId;
connectionBuilder.ClientId = ClientId;
connectionBuilder.ClientSecret = ClientSecret;

// Pass the set parameters to the connection
var connection = new DynamicsConnection(connectionBuilder.ConnectionString);
connection.Open();

When the Open method is called, DynamicsConnection will request a token from the authorization server and then transmit the received token to the resource server to gain access to the data.

Note: When your application obtains a token from the authorization server, port CallbackPort=56728 will be opened for listening, which will be set in the default settings of OAuthAuthenticationProvider. Ensure that your firewall allows a connection to this port.

Using OAuthAuthenticationProviderOptionsBuilder

Create an OAuthAuthenticationProviderOptionsBuilder to initialize OAuth 2.0 authorization parameters and an OAuthAuthenticationProvider for managing OAuth 2.0 authentication with the Dynamics 365 server.

// Create OAuthAuthenticationProviderOptionsBuilder and initialize OAuth2 authorization parameters
var providerOptions = DynamicsOAuthAuthenticationProviderOptionsBuilder.Create()
    .WithClientId(ClientId)
    .WithClientSecret(ClientSecret)
    .WithHost(Server)
    .WithUserId(UserId)
    .WithRedirectUrls(new Dictionary<int, string> {
        { CallbackPort, RedirectUrl } // By default, CallbackPort equals 56728
    })
    .Build();

// Create OAuthAuthenticationProvider
var provider = new DynamicsOAuthAuthenticationProvider(providerOptions);

Next, you can pass this provider to DynamicsConnection and call the Open method to connect to the resource server. In this case, DynamicsConnection will request a token from the authorization server.

// Specify the interactive mode in the Authentication field
var connection = new DynamicsConnection("Authentication Type=RefreshTokenInteractive");

// Set the created OAuthAuthenticationProvider as the provider of the connection
connection.SetAuthenticationProvider(AuthenticationType.RefreshTokenInteractive, provider);
connection.Open();

Alternatively, you can manually obtain a token from the authorization server for further use.

// Create a ConnectionStringBuilder. This is necessary so that after executing the ApplyAsync method, you can get the current parameters
var oAuthBuilder = new DynamicsConnectionStringBuilder();

// Get a token from the OAuth authorization server
await provider.ApplyAsync(oAuthBuilder);

After the ApplyAsync method is executed, the obtained parameters will be set in oAuthBuilder. For example, the oAuthBuilder.RefreshToken property will contain the refresh token received from the authorization server.

You can pass these properties to DynamicsConnection to connect to the resource server as in the following example.

var connectionBuilder = new DynamicsConnectionStringBuilder();
connectionBuilder.Authentication = oAuthBuilder.AuthenticationType;
connectionBuilder.RefreshToken = oAuthBuilder.RefreshToken;
connectionBuilder.Server = oAuthBuilder.Server;
connectionBuilder.UserId = oAuthBuilder.UserId;
connectionBuilder.ClientId = oAuthBuilder.ClientId;
connectionBuilder.ClientSecret = oAuthBuilder.ClientSecret;

// Pass the set parameters to the connection
var connection = new DynamicsConnection(connectionBuilder.ConnectionString);
connection.Open();

In this case, when the Open method is called, the set RefreshToken will be passed to the resource server to gain access to the data.