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 FreshBooks, OAuth 2.0 authorization can be used to approve client access to your organization's protected resources.

To access FreshBooks 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 FreshBooks 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 FreshBooks server using the FreshBooksConnection 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, FreshBooksConnection 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 FreshBooksConnection("Authentication Type=OAuthInteractive");
connection.Open();

Note: When the Open method is executed, the FreshBooks 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 FreshBooksConnectionStringBuilder();
await FreshBooksOAuthAuthenticationProvider.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 FreshBooksConnection to connect to the resource server.

var connection = new FreshBooksConnection("Authentication Type=OAuth;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 FreshBooks server.

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

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

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

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

When the Open method is called, FreshBooksConnection 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=55420 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 FreshBooks server.

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

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

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

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

// Set the created OAuthAuthenticationProvider as the provider of the connection
connection.SetAuthenticationProvider(AuthenticationType.OAuthInteractive, 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 FreshBooksConnectionStringBuilder();

// 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 FreshBooksConnection to connect to the resource server as in the following example.

var connectionBuilder = new FreshBooksConnectionStringBuilder();
connectionBuilder.Authentication = oAuthBuilder.AuthenticationType;
connectionBuilder.RefreshToken = oAuthBuilder.RefreshToken;
connectionBuilder.ClientId = oAuthBuilder.ClientId;
connectionBuilder.ClientSecret = oAuthBuilder.ClientSecret;

// Pass the set parameters to the connection
var connection = new FreshBooksConnection(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.