Connection Using OAuth

To obtain the OAuth client credentials, the OAuthClientId and OAuthClientSecret, follow the steps below:

1. If you have not already done so, create an Exact Online developer account.

2. Log into the App Center and click Manage Apps -> Add a New Application.

3. Enter the app name to be displayed to users when they are prompted to grant permissions to your app.

4. Set the Redirect URI to a page you would like the user to be returned to after they have granted your application permissions.

5. Click the Edit button for your app. The client credentials, the client Id and client secret, are displayed.

Set these OAuth credentials in the datasource definition, in addition to Division and Region.

Connection Using OAuth

To obtain the OAuth client credentials, the OAuthClientId and OAuthClientSecret, follow the steps below:

1. If you have not already done so, create an Exact Online developer account.

2. Log into the App Center and click Manage Apps -> Add a New Application.

3. Enter the app name to be displayed to users when they are prompted to grant permissions to your app.

4. Set the Redirect URI to a page you would like the user to be returned to after they have granted your application permissions.

5. Click the Edit button for your app. The client credentials, the client Id and client secret, are displayed.

Set these OAuth credentials in the datasource definition, in addition to Division and Region.

Connecting to QuickBooks

The provider makes requests to QuickBooks POS through the QuickBooks Gateway. The QuickBooks Gateway runs on the same machine as QuickBooks POS and accepts connections through a lightweight, embedded Web server. The server supports SSL/TLS, enabling users to connect securely from remote machines. The first time you connect, you will need to authorize the provider with QuickBooks POS. For more information, refer to our Using the QuickBooks Gateway section below.

To work with your data in practice mode, set QBPOSPractice. Additionally, set QBPOSVersion.

Connecting to a Local Company File

Follow the steps below to authorize with QuickBooks POS and connect to a company file when both QuickBooks POS and the provider are running on your local machine.

1. Open QuickBooks POS as an administrator and open the company file you want to connect to.

2. Connect to QuickBooks POS. A dialog will appear in QuickBooks POS prompting you to authorize the provider. After granting access to the provider, you can now execute commands to QuickBooks POS.

3. If you want to connect to the company file when QuickBooks POS is closed, set the CompanyFile connection option when you execute commands. QuickBooks POS will open automatically in the background with the file specified.

   Note that if QuickBooks POS is open through the application UI, only that CompanyFile can be used.

Connection Troubleshooting

If you receive a connection error (such as "Internal error 160002") you may need to switch QuickBooks POS to multiuser mode. This is done by selecting the "Switch Company File to Multi User Mode" option in the File Menu. You should then be able to connect to the company file.

If a CompanyFile is not specified in the connection string, QuickBooks POS may present an "Enter Company Name" window the first time you connect. In this window, you must specify the company file and the computer name where the company file is located.

QuickBooks Gateway

The QuickBooks Desktop Gateway can be used to read and write to QuickBooks POS in situations where direct COM access to QuickBooks POS is not available (e.g., ASP.NET, Java, or QuickBooks POS on a remote machine). Follow the procedure below to connect to QuickBooks POS for the first time through the Desktop Gateway:

1. If you have not already done so, download the QuickBooks Desktop Gateway from here and install it.

2. Open the company file you want to connect to in QuickBooks POS using an administrator account in single-user mode.

3. Open the QuickBooks Desktop Gateway from the system tray and add a user on the Users tab. Enter a User and Password and select the level of access in the Data Access menu.

   Note: The QuickBooks Desktop Gateway does not use the User and Password properties to access QuickBooks POS; the User and Password properties authenticate the user. Authentication to QuickBooks POS is handled by the ApplicationName property.

4. When you first connect, a dialog appears in QuickBooks POS prompting you to authorize the application. After authorizing, you can execute commands to QuickBooks POS. Specify the URL of the Desktop Gateway and the User and Password. By default, the Gateway connects to the currently open company file.

5. If you want to access QuickBooks POS when QuickBooks POS is not running, save the company file information for the user. The Desktop Gateway automatically opens QuickBooks POS in the background with the company file for that user.

NOTE: that if the QuickBooks POS UI is open, you can only connect to that company file. Additionally, the user permissions you specify for the Desktop Gateway must match the user permissions you used for QuickBooks POS. The Desktop Gateway installs as a service in the current user account.

How do I Connect to QuickBooks POS over SSL/TLS?

You can enable SSL/TLS on the Advanced tab.

You will also need to send your public key certificate to the provider. You can do so by setting the SSLServerCert property.

Authenticating to FreshBooks

FreshBooks uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

See below

Connecting to the Classic API

There are two methods you can use to connect to the FreshBooks Classic API, the authentication token specific to your login or OAuth 1.0. The authentication token method is deprecated and will not be supported by FreshBooks in the future.

Using the Authentication Token to Connect to FreshBooks

To connect to FreshBooks using an authentication token, specify the CompanyName and Token connection properties. The token can be found by logging in to FreshBooks and navigating to My Account > FreshBooks API.

Using OAuth to Connect to FreshBooks

OAuth requires the authenticating user to interact with FreshBooks using the browser. The provider facilitates this in various ways as described in the following sections.

Register Your Application

To obtain the OAuth client credentials:

1. Request Developer Access through FreshBooks, if you have not already done so.

2. Select My Account > FreshBooks API.

3. Select the Use OAuth option and enter the application details. The details are displayed to users when they log in to grant permissions to the application. The OAuth consumer secret is displayed.

Note: It may take some time for FreshBooks to approve your registration.

Authenticate to FreshBooks from a Desktop Application

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the name of the company you are connecting to. Note that you can also use the CompanyName.

• OAuthClientSecret: Set this to the consumer secret in your app settings.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the access token in the connection string.

When you connect, the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the following OAuth process:

1. Retrieves the OAuthAccessToken and OAuthAccessTokenSecret and authenticates requests.

2. Refreshes the OAuthAccessToken when it expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Authenticate to FreshBooks from a Web Application

To obtain the access token, set the following connection properties and follow the steps below:

• OAuthClientId: Set this to the name of the company you are connecting to. Note that you can also use the CompanyName property.

• OAuthClientSecret: Set this to the consumer secret in your app settings.

To connect to data, set the following connection properties:

• CompanyName

• OAuthClientSecret

• OAuthAccessToken

• OAuthAccessTokenSecret

Refresh the Token

To automatically refresh the access token when it expires, set InitiateOAuth to REFRESH and set OAuthRefreshToken.

Connect to the Alpha API

Use the OAuth 2.0 authentication standard to authenticate to the FreshBooks Alpha APIs.

OAuth requires the authenticating user to interact with FreshBooks using the browser. The provider facilitates this in various ways as described in the following sections.

Register Your Application

To obtain the OAuth client credentials:

1. Log into the FreshBooks developers site at https://my.freshbooks.com/#/developer and click Create an App.

2. Enter information to be displayed to your users when they are prompted to grant permissions to your app.

3. Specify a redirect URI.

   Set the redirect URI to https://localhost:33333/, or some other similar https url.

   If you are making a Web application, set the Callback URL to a page on your Web app you would like the user to be returned to after they have authorized your application.

Authenticate to FreshBooks

To obtain the access token, set the following connection properties:

• OAuthClientId: Set this to the name of the company you are connecting to. Note that you can also use the CompanyName property.

• OAuthClientSecret: Set this to the consumer secret in your app settings.

To connect to data, set the following connection properties:

• AccountId

• OAuthClientSecret

• OAuthAccessToken

• OAuthAccessTokenSecret

Refresh the Token

To automatically refresh the access token when it expires, set InitiateOAuth to REFRESH and set OAuthRefreshToken.

QuickBooks Online uses the OAuth authentication standard. You can use the Embedded Credentials (see below) to connect without setting any connection properties. When you connect, the provider opens the OAuth endpoint in your default browser. Simply log in and grant permissions to the application. The provider then completes the OAuth process.

Alternatively, you can create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

To obtain the access token, set the following connection properties:

• CompanyId: The unique identifier of a given company in QuickBooks Online.

• OAuthClientId: The consumer key in your app settings.

• OAuthClientSecret: The consumer secret in your app settings.

• CallbackURL: The Launch URL in your app settings.

Authenticate using the Embedded OAuth 2.0 Credentials

You can connect without setting any connection properties for your user credentials. After setting InitiateOAuth to GETANDREFRESH, you are ready to connect.

When you connect, the provider then completes the OAuth process.

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

The provider makes requests to QuickBooks through the Remote Connector. The Remote Connector runs on the same machine as QuickBooks and accepts connections through a lightweight, embedded Web server. The server supports SSL/TLS, enabling users to connect securely from remote machines. The first time you connect, you will need to authorize the provider with QuickBooks.

The Remote Connector can be used to read and write to QuickBooks in situations where direct COM access to QuickBooks is not available (e.g., ASP.NET, Java, or QuickBooks on a remote machine). Follow the procedure below to connect to QuickBooks for the first time through the Remote Connector:

1. If you have not already done so, download the Remote Connector from remoteconnector.com and install the Remote Connector on the machine where QuickBooks is installed.

2. Open the company file you want to connect to in QuickBooks using an administrator account in single-user mode.

3. Open the Remote Connector from the system tray and add a user on the Users tab. Enter a User and Password and select the level of access in the Data Access menu.

   Note: The Remote Connector does not use the User and Password properties to access QuickBooks; the User and Password properties authenticate the user to the Remote Connector. Authentication to QuickBooks is handled based on the ApplicationName property.

4. When you first connect, a dialog will appear in QuickBooks prompting you to authorize the application. After authorizing the application, you can then execute commands to QuickBooks. Specify the URL of the Remote Connector and the User and Password. By default, the Remote Connector connects to the currently open company file.

5. If you want to access QuickBooks when QuickBooks is not running, save the company file information for the user. The Remote Connector will then automatically open QuickBooks in the background with the company file for that user.

Note that if the QuickBooks UI is open, you can only connect to that company file. Additionally, note that the user permissions you run the Remote Connector under must match the user permissions you run QuickBooks under. The Remote Connector installation process installs the Remote Connector as a service under the current user account.

How do I Connect to QuickBooks over SSL/TLS?

You can enable SSL/TLS on the Advanced tab.

You will also need to send your public key certificate to the provider. You can do so by setting the SSLServerCert property.

Connecting to a Local Company File

Follow the steps below to authorize with QuickBooks and connect to a company file when both QuickBooks and the provider are running on your local machine.

1. Open QuickBooks as an administrator and open the company file you want to connect to.

2. Connect to QuickBooks. A dialog will appear in QuickBooks prompting you to authorize the provider. After granting access to the provider, you can now execute commands to QuickBooks.

3. If you want to connect to the company file when QuickBooks is closed, set the CompanyFile connection option when you execute commands. QuickBooks will open automatically in the background with the file specified.

   Note that if QuickBooks is open through the application UI, only that CompanyFile can be used.

The provider supports the following Xero APIs:

• Accounting API: Set the Schema connection property to ACCOUNTING

• Australian Payroll API: Set the Schema connection property to PAYROLLAUS

• Files API: Set the Schema connection property to FILES

• Fixed Assets API: Set the Schema connection property to ASSETS

• Projects API: Set the Schema connection property to PROJECTS

Authenticating to Xero

By default the provider authenticates to Xero using OAUTH2

OAUTH2 Xero App Authentication

You will need to create an OAuth application and set InitiateOAuth to GETANDREFRESH to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

Follow the steps below to register a public application and obtain the OAuthClientId and OAuthClientSecret.

1. Log in to the Xero developer portal.

2. Click My Apps -> Add Application. Choose the Auth Code application type.

3. Enter a name for your application and the URL of your company. This information is displayed to users when they connect.

4. Set the Redirect URI to the full redirect or callback URL, where the user returns with the token that verifies that they have granted your app access.

When connecting using OAUTH2, Xero grants the provider access to all of the organizations that the user has authorized. By default the provider will connect using the first available organization. Since this default changes as you authorize new organizations, it is recommended that you set the Tenant connection property to ensure future connections always use the same organization.

The Tenant property can be set to either the name or ID of a Xero organization.

Xero API Limits

The Xero API has usage limitations that may be encountered while using the Provider for Xero.

Daily Limit

There is a daily limit of 5000 API calls against a single Xero organization in a rolling 24-hour period.

Requests per minute

In addition to the daily limit, a single access token can only be used up to 60 times in a rolling 60-second period.

Encountering a Rate Limit

If you encounter a rate limit, the Xero API will return an HTTP 503 (Service Unavailable) error, with the following message: "oauth_problem=rate limit exceeded".

Note: If you encounter a rate limit, do not continue to make requests, as this may continue to add to your limitation. If necessary, you may need to queue requests.

Keeping track of requests

When working with the provider, some operations may result in multiple requests to the API. For example, updating an existing record will result in two requests: one to get the current record, and one to submit changes.

To connect to Alfresco, the following connection properties must be supplied: User, Password, and InstanceURL. User and Password should correspond to the login credentials that you use to access Alfresco in a web browser. InstanceURL corresponds to the Alfresco instance you will be querying. For instance, if you expect your queries to hit https://search-demo.dev.alfresco.me/alfresco/api/-default-/public/search/versions/1/sql, you should supply search-demo.dev.alfresco.me for InstanceURL.

The first time you connect, you will need to authorize the provider with Reckon. The provider makes requests to Reckon through the Remote Connector. The Remote Connector runs on the same machine as Reckon and accepts connections through a lightweight, embedded Web server. The server supports SSL/TLS, enabling users to connect securely from remote machines.

Follow the steps below to authorize with Reckon and connect to a company file when both Reckon and the provider are running on your local machine.

1. Open Reckon as an administrator and open the company file you want to connect to.

2. Connect to Reckon. A dialog will appear in Reckon prompting you to authorize the provider. After granting access to the provider, you can now execute commands to Reckon.

3. If you want to connect to the company file when Reckon is closed, set the CompanyFile connection option when you execute commands. Reckon will open automatically in the background with the file specified.

   Note that if Reckon is open through the application UI, only that CompanyFile can be used.

Using the Remote Connector

The Remote Connector can be used to read and write to Reckon in situations where direct COM access to Reckon is not available (e.g., ASP.NET, Java, or Reckon on a remote machine). Follow the procedure below to connect to Reckon for the first time through the Remote Connector:

1. If you have not already done so, download the Remote Connector from remoteconnector.com and install the Remote Connector on the machine where Reckon is installed.

2. Open the company file you want to connect to in Reckon using an administrator account in single-user mode.

3. Open the Remote Connector from the system tray and add a user on the Users tab. Enter a User and Password and select the level of access in the Data Access menu.

   Note: The Remote Connector does not use the User and Password properties to access Reckon; the User and Password properties authenticate the user to the Remote Connector. Authentication to Reckon is handled based on the ApplicationName property.

4. When you first connect, a dialog will appear in Reckon prompting you to authorize the application. After authorizing the application, you can then execute commands to Reckon. Specify the URL of the Remote Connector and the User and Password. By default, the Remote Connector connects to the currently open company file.

5. If you want to access Reckon when Reckon is not running, save the company file information for the user. The Remote Connector will then automatically open Reckon in the background with the company file for that user.

Note that if the Reckon UI is open, you can only connect to that company file. Additionally, note that the user permissions you run the Remote Connector under must match the user permissions you run Reckon under. The Remote Connector installation process installs the Remote Connector as a service under the current user account.

How do I Connect to Reckon over SSL/TLS?

You can enable SSL/TLS on the Advanced tab.

You will also need to send your public key certificate to the provider. You can do so by setting the SSLServerCert property.

Connecting to Sage Intacct

To connect to Web Services, you will first need to enable the Web Services subscription. Navigate to Company > Admin Tab > Subscriptions and enable Web Services.

Intacct also recommends creating a Web Services-only user, which can be done by navigating to Company > Admin Tab, and clicking on the + sign beside Web Services users.

You can establish a connection to Sage Intacct with your own credentials.

Authenticating to Sage Intacct

To authenticate, set CompanyID and set User and Password to the credentials you use to log on to Sage Intacct. In addition, you will need to either set your own SenderID and SenderPassword.

Connect using Custom Credentials

You can use your own Web Services credentials to write data to Intacct. Set the following to connect to data:

• SenderID: Set this to the Web Services Sender ID assigned to you by Sage Intacct.

• SenderPassword: Set this to your registered Web Services password.

Okta

Set the AuthScheme to Okta. The following connection properties are used to connect to Okta:

• User: Set this to the Okta user.

• Password: Set this to Okta password for the user.

• SSOLoginURL: Set this to the login url used by the SSO provider.

The following SSOProperties are needed to authenticate to Okta:

• IntacctUserID: Set this value to the Intacct User ID that is mapped to the Okta user you set in the User connection property.

• APIToken (optional): Set this to the API Token that the customer created from the Okta org. It should be used when authenticating a user via a trusted application or proxy that overrides Okta client request context.

The following is an example connection string: AuthScheme=Okta; SSOLoginURL='https://example.okta.com/home/appType/0bg4ivz6cJRZgCz5d6/46'; User=oktaUserName; Password=oktaPassword; SSOProperties='IntacctUserID=intacct_user';

Connecting to Splunk APIs

You must specify the URL to a valid Splunk server. By default the provider makes requests on port 8089.

By default, the provider attempts to negotiate TLS/SSL with the server.

Authenticating to Splunk

Login with Splunk credentials is the only available authentication method for connecting to Splunk.

Authenticating with Splunk credentials

To authenticate with Splunk credentials, set the AuthScheme to Basic and set the User and Password to your login credentials.

Salesforce Einstein Analytics uses the OAuth 2 authentication standard. You will need to obtain the OAuthClientId and OAuthClientSecret by registering an app with Salesforce Einstein Analytics.

OAuth requires the authenticating user to interact with Salesforce Einstein Analytics using the browser. The provider facilitates this in various ways as described in the following sections.

Create a Connected App

You can follow the procedure below to obtain the OAuth client credentials, the consumer key and consumer secret:

1. If your organization uses the Salesforce Lightning Experience UI, from Setup enter App in the Quick Find box, select App Manager (not Manage Connected Apps), and click New Connected App.

   If your organization uses the Salesforce Classic UI, from Setup enter Apps in the Quick Find box and then select Apps, under Build or Create. Under Connected Apps, click New.

2. Enter a name to be displayed to users when they log in to grant permissions to your app, along with a contact email address.

3. Click Enable OAuth Settings and enter a value in the Callback URL box.

   If you are making a desktop application, set the Callback URL to http://localhost:33333 or a different port number of your choice.

   If you are making a Web application, set the Callback URL to a page on your Web app you would like the user to be returned to after they have authorized your application.

4. Select the following OAuth scopes:

   Access and manage your wave data (wave_api)

   Access and manage your data (api)

   Perform requests on your behalf at any time (refresh_token, offline_token)

5. Once you have created the app, click your app name to open a page with information about your app. The OAuth client credentials, the consumer key and consumer secret, are displayed.

Authenticate to Salesforce Einstein Analytics

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the consumer key in your app settings.

• OAuthClientSecret: Set this to the consumer secret in your app settings.

• CallbackURL: Set this to the callback URL in your app settings.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Gets the callback URL and sets the access token to authenticate requests.

2. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

3. Exchanges the returned refresh token for a new, valid access token.

Authenticating to Sage Business Cloud Accounting

Sage Business Cloud Accounting uses the OAuth standard to authenticate users.

OAuth requires the authenticating user to interact with Sage Business Cloud Accounting using the browser. The provider facilitates this in various ways as described below.

Note: The driver makes use of the Sage Business Cloud Accounting API (v3.1) to connect. The supported countries for this API version are:

• Canada

• Germany

• Spain

• France

• United Kingdom

• Ireland

• United States

OAuth

You can connect without setting any connection properties for your user credentials. Set InitiateOAuth to GETANDREFRESH to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

To obtain the OAuth client credentials, follow the steps below:

1. Log into Sage accounting Developer Account.

2. Create a new app. Set the CallbackUrl to http://localhost:3333, or some other similar http url.

3. The OAuthClientId is the Client Id displayed. The OAuthClientSecret is the Client Secret.

Authenticating to DataRobot API

Various login credentials must be supplied to connect to the standard API and Prediction API of DataRobot.

Authenticating with a Login and API Key

Set the User and Password to your login credentials, and specify PredictionInstance. Additionally, set the APIKey connection property to your API Token, if you have obtained one already. If you are using a Cloud Prediction instance for DataRobot, you will need to supply DataRobotKey as well. To obtain the APIKey, follow the steps below:

1. Login to the DataRobot UI, and click the person icon in the top right corner of the UI.

2. From the drop down menu, select "Profile".

3. Profile information will appear, including your "API Token".

To obtain the DataRobotKey, do the following:

1. Login to the DataRobot UI, and click "Deployments" in the top-most toolbar.

2. Open a deployment.

3. In the deployment's menu, select the "Integrations" tab.

4. Your DataRobotKey is the second entry in the headers JSON object.

Authenticating to Quickbase

User Authentication

Set the AuthScheme to Basic to authenticate with this method.

To authenthenticate with user credentials, specify the following connection properties:

1. Set the Quickbase User and Password.

2. If your application requires an ApplicationToken, you must provide it otherwise an error will be thrown. You can find the ApplicationToken under MyAppName > Settings > App properties > Advanced settings > Security options > Require Application Tokens > Manage Application Token.

User Token

Set the AuthScheme to Token to authenticate with this method.

To authenthenticate with a user token, specify the following connection properties:

1. Set UserToken and you are ready to connect. You can find the UserToken under Quick Base > My Preferences > My User Information > Manage User Tokens.

Connecting to Kintone

In addition to the authentication values, set the following parameters to connect to and retrieve data from Kintone:

• Url: The URL of your account.

• GuestSpaceId: Optional. Set this when using a guest space.

Authenticating to Kintone

Kintone supports the following authentication methods.

Password Authentication

You must set the following to authenticate to Kintone:

• User: The username of your account.

• Password: The password of your account.

• AuthScheme: Set AuthScheme to Password.

API Token

You must set the following to authenticate to Kintone:

• APIToken: The API Token.

  To generate an API token access the specific app and click on the cog wheel. Proceed to App Settings tab > API Token. Click on the Generate button, an API token will be generated.

• AppId: The Application Ids.

  The AppId is the number of that specific app in the sequence under Apps in Kintone UI dashboard.

• AuthScheme: Set AuthScheme to APIToken.

Additional Security

In addition to the mentioned authentication schemese, Kintone offers additional security in the form of both an additional Basic Auth header, and an SSL Certificate.

Using Client SSL

In addition to your authentication information, Kintone may be configured to require an SSL certificate to accept requests. To do so, set the following:

• SSLClientCert: The file containing the certificate of the SSL Cert. Or alternatively, the name of the certificate store for the client certificate.

• SSLClientCertType: The type of certificate.

• SSLClientCertSubject: (Optional) If searching for a certificate in the certificate store, the store is searched for subjects containing the value of the property.

• SSLClientCertPassword: If the certificate store is of a type that requires a password, this property is used to specify that password to open the certificate store.

Basic

Kintone environments using basic authentication will need to pass additional basic credentials. To do so, specify the following:

• BasicAuthUser: The basic login name.

• BasicAuthPassword: The basic password.

Establishing a Connection

Authenticate via OAuth Authentication

Use the OAuth authentication standard to connect to Google Analytics. You can authenticate with a user account or with a service account. A service account is required to grant organization-wide access scopes to the provider. The provider facilitates these authentication flows as described below.

Create an OAuth App for User Account Authentication

Instead of connecting with the provider's embedded credentials, you can register an app to obtain the OAuthClientId and OAuthClientSecret.

Follow the procedure below to register an app and obtain the OAuthClientId and OAuthClientSecret.

1. Log into the Google API Console and open a project. Select the API Manager from the main menu.

2. In the user consent flow, click Credentials -> Create Credentials -> OAuth Client Id. Click Other. After creating the app, the OAuthClientId and OAuthClientSecret are displayed.

3. Click Library -> Analytics API -> Enable API.

After setting the following, you are ready to connect:

• OAuthClientId: Set this to the client Id assigned when you registered your app.

• OAuthClientSecret: Set this to the client secret assigned when you registered your app.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• Profile: Set this to the Google Analytics profile or view you want to connect to. This value can be retrieved from the Profiles table. If this is not specified, the first Profile returned will be used.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Refreshes the access token when it expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Create an OAuth App for Service Account Authentication

Follow the steps below to create an OAuth application and generate a private key. You will then authorize the service account.

1. Log into the Google API Console and open a project. Select the API Manager from the main menu.

2. Click Create Credentials -> Service Account Key.

3. In the Service Account menu, select New Service Account or select an existing service account.

4. If you are creating a new service account, additionally select one or more roles. You can assign primitive roles at the project level in the IAM and Admin section; other roles enable you to further customize access to Google APIs.

5. In the Key Type section, select the P12 key type.

6. Create the app to download the key pair. The private key's password is displayed: Set this in OAuthJWTCertPassword.

7. In the service accounts section, click Manage Service Accounts and set OAuthJWTIssuer to the email address displayed in the service account Id field.

8. Click Library -> Analytics API -> Enable API.

Service accounts have silent authentication, without user authentication in the browser. You can also use a service account to delegate enterprise-wide access scopes to the provider.

You can then connect to Google Analytics data that the service account has permission to access.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH.

• OAuthJWTCertType: Set this to "PFXFile".

• OAuthJWTCert: Set this to the path to the .p12 file you generated.

• OAuthJWTCertPassword: Set this to the password of the .pem file.

• OAuthJWTCertSubject: Set this to "*" to pick the first certificate in the certificate store.

• OAuthJWTSubject (optional): Set this to the email address of the user for whom the application is requesting delegate access. Note that delegate access must be granted by an administrator.

• Profile: Set this to the Google Analytics profile or view you want to connect to. This value can be retrieved from the Profiles table. If this is not specified, the first Profile returned will be used.

When you connect the provider completes the OAuth flow for a service account.

1. Creates and signs the JWT with the claim set required by the provider.

2. Exchanges the JWT for the access token.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

4. Submits the JWT for a new access token when the token expires.

The Provider for SAS Data Sets allows connecting to local and remote SAS resources. Set the URI property to the SAS resource location, in addition to any other properties necessary to connect to your data source.

Connecting to Local Files

Set the ConnectionType to Local. Local files support SELECT\INSERT\DELETE.

Set the URI to a folder containing SAS files: C:\folder1.

Connecting to Cloud-Hosted SAS Data Sets Files

While the provider is capable of pulling data from SAS Data Sets files hosted on a variety of cloud data stores, INSERT, UPDATE, and DELETE are not supported outside of local files in this provider.

If you need INSERT/UPDATE/DELETE cloud files, you can use the corresponding connector for that cloud host (supported via stored procedures), make changes with the local file's corresponding provider, then upload the file using the cloud source's stored procedures.

As an example, if you wanted to update a file stored on SharePoint, you could use the appRules SharePoint DownloadDocument activity to download the SAS Data Sets file, update the local SAS Data Sets file with the appRules SAS Data Sets connector, then use the SharePoint UploadDocument activity to upload the changed file to SharePoint.

A unique prefix at the beginning of the URI connection property is used to identify the cloud data store being targed by the provider and the remainder of the path is a relative path to the desired folder (one table per file) or single file (a single table).

Amazon S3

Set the following to identify your SAS Data Sets resources stored on Amazon S3:

• ConnectionType: Set the ConnectionType to Amazon S3.

• URI: Set this to the bucket and folder: s3://bucket1/folder1.

Azure Blob Storage

Set the following to identify your SAS Data Sets resources stored on Azure Blob Storage:

• ConnectionType: Set this to Azure Blob Storage.

• URI: Set this to the name of your container and the name of the blob. For example: azureblob://mycontainer/myblob.

Azure Data Lake Storage

Set the following to identify your SAS Data Sets resources stored on Azure Data Lake Storage:

• ConnectionType: Set this to Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2, or Azure Data Lake Storage Gen2 SSL.

• URI: Set this to the name of the file system and the name of the folder which contains your SAS Data Sets files. For example:

  • Gen 1: adl://myfilesystem/folder1

  • Gen 2: abfs://myfilesystem/folder1

  • Gen 2 SSL: abfss://myfilesystem/folder1

Azure File Storage

Set the following properties to connect:

• ConnectionType: Set this to Azure Files.

• URI: Set this the name of your azure file share and the name of the resource. For example: azurefile://fileShare/remotePath.

• AzureStorageAccount (Required): Set this to the account associated with the Azure file.

You can authenticate either an Azure access key or an Azure shared access signature. Set one of the following:

• AzureAccessKey: Set this to the access key associated with the Azure file.

• AzureSharedAccessSignature: Set this to the shared access signature associated with the Azure file.

Box

Set the following to identify your SAS Data Sets resources stored on Box:

• ConnectionType: Set this to Box.

• URI: Set this the name of the file system and the name of the folder which contains your SAS Data Sets files. For example: box://folder1.

Dropbox

Set the following to identify your SAS Data Sets resources stored on Dropbox:

• ConnectionType: Set this to Dropbox.

• URI: Set this to the path to a folder containing SAS files. For example: dropbox://folder1.

FTP

The provider supports both plaintext and SSL/TLS connections to FTP servers.

Set the following connection properties to connect:

• ConnectionType: Set this to either FTP or FTPS.

• URI: Set this to the address of the server followed by the path to the folder to be used as the root folder. For example: ftp://localhost:990/folder1 or ftps://localhost:990/folder1.

• User: Set this to your username on the FTP(S) server you want to connect to.

• Password: Set this to your password on the FTP(S) server you want to connect to.

Google Cloud Storage

Set the following to identify your SAS Data Sets resources stored on Google Cloud Storage:

• ConnectionType: Set this to Google Cloud Storage.

• URI: Set this to the path to the name of the file system and the name of the folder which contains your SAS Data Sets files. For example: gs://bucket/remotePath.

Google Drive

Set the following to identify your SAS Data Sets resources stored on Google Drive:

• ConnectionType: Set this to Google Drive.

• URI: Set to the path to the name of the file system and the name of the folder which contains your SAS Data Sets files. For example: gdrive://folder1.

HDFS

Set the following to identify your SAS Data Sets resources stored on HDFS:

• ConnectionType: Set this to HDFS or HDFS Secure.

• URI: Set this to the path to a folder containing SAS files. For example:

  • HDFS: webhdfs://host:port/remotePath

  • HDFS Secure: webhdfss://host:port/remotePath

There are two authentication methods available for connecting to HDFS data source, Anonymous Authentication and Negotiate (Kerberos) Authentication.

Anonymous Authentication

In some situations, you can connect to HDFS without any authentication connection properties. To do so, set the AuthScheme property to None (default).

Authenticate using Kerberos

When authentication credentials are required, you can use Kerberos for authentication.

HTTP Streams

Set the following to identify your SAS Data Sets resources stored on HTTP streams:

• ConnectionType: Set this to HTTP or HTTPS.

• URI: Set this to the URI of your HTTP(S) stream. For example:

  • HTTP: http://remoteStream

  • HTTPS: https://remoteStream

IBM Cloud Object Storage

Set the following to identify your SAS Data Sets resources stored on IBM Cloud Object Storage:

• ConnectionType: Set this to IBM Object Storage Source.

• URI: Set this to the bucket and folder. For example: ibmobjectstorage://bucket1/remotePath.

OneDrive

Set the following to identify your SAS Data Sets resources stored on OneDrive:

• ConnectionType: Set this to OneDrive.

• URI: Set this to the path to a folder containing SAS files. For example: onedrive://remotePath.

Oracle Cloud Storage

Set the following properties to authenticate with HMAC:

• ConnectionType: Set the ConnectionType to Oracle Cloud Storage.

• URI: Set this to the bucket and folder: os://bucket/remotePath.

• AccessKey: Set this to an Oracle Cloud Access Key.

• SecretKey: Set this to an Oracle Cloud Secret Key.

• OracleNamespace: Set this to an Oracle cloud namespace.

• Region (optional): Set this to the hosting region for your S3-like Web Services.

SFTP

Set the following to identify your SAS Data Sets resources stored on SFTP:

• ConnectionType: Set this to SFTP.

• URI: Set this to the address of the server followed by the path to the folder to be used as the root folder. For example: sftp://server:port/remotePath.

SharePoint Online

Set the following to identify your SAS Data Sets resources stored on SharePoint Online:

• ConnectionType: Set this to SharePoint REST or SharePoint SOAP.

• URI: Set this to a document library containing SAS files. For example:

  • SharePoint Online REST: sprest://remotePath

  • SharePoint Online SOAP: sp://remotePath

Securing SAS Data Sets Connections

By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.

Authenticate via OAuth Authentication

Use the OAuth authentication standard to connect to YouTube Analytics. You can authenticate with a user account or with a service account. A service account is required to grant organization-wide access scopes to the provider. The provider facilitates these authentication flows as described below.

Authenticate with a User Account

Create an OAuth App for User Account Authentication

1. Log into the Google API Console and open a project. Select the API Manager from the main menu.

2. In the user consent flow, click Credentials -> Create Credentials -> OAuth Client Id. Click Other. After creating the app, the OAuthClientId and OAuthClientSecret are displayed.

3. Click Library -> YouTube Analytics API -> Enable API.

Authenticate with a Service Account

Service accounts have silent authentication, without user authentication in the browser. You can also use a service account to delegate enterprise-wide access scopes to the provider.

Create an OAuth App for Service Account Authentication

Follow the steps below to create an OAuth application and generate a private key. You will then authorize the service account.

1. Log into the Google API Console and open a project. Select the API Manager from the main menu.

2. Click Create Credentials -> Service Account Key.

3. In the Service Account menu, select New Service Account or select an existing service account.

4. If you are creating a new service account, additionally select one or more roles. You can assign primitive roles at the project level in the IAM and Admin section; other roles enable you to further customize access to Google APIs.

5. In the Key Type section, select the P12 key type.

6. Create the app to download the key pair. The private key's password is displayed: Set this in OAuthJWTCertPassword.

7. In the service accounts section, click Manage Service Accounts and set OAuthJWTIssuer to the email address displayed in the service account Id field.

8. Click Library -> YouTube Analytics API -> Enable API

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set to GETANDREFRESH.

• OAuthClientId: Set to the Client Id in your app settings.

• OAuthClientSecret: Set to the Client Secret in your app settings.

• OAuthJWTCertType: Set to "PEMKEY_FILE".

• OAuthJWTCert: Set to the path to the .pem file you generated.

• OAuthJWTCertPassword: Set to the password of the .pem file.

• OAuthJWTCertSubject: Set to "*" to pick the first certificate in the certificate store.

• OAuthJWTSubject: Set to the email address of the user for whom the application is requesting delegate access. Note that delegate access must be granted by an administrator.

• ChannelId: Set to the Id of a YouTube channel. If not specified, data is returned for the authenticated user's channel.

• ContentOwnerId: Set if you want to generate content owner reports.

When you connect the provider completes the OAuth flow for a service account.

1. Creates and signs the JWT with the claim set required by the provider.

2. Exchanges the JWT for the access token.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

4. Submits the JWT for a new access token when the token expires.

Connecting to Apache Hive

Specify the following to establish a connection with Apache Hive:

• Server: Set this to the host name or IP address of the server hosting HiveServer2.

• Port: Set this to the port for the connection to the HiveServer2 instance.

Authenticating to Apache Hive

To authenticate to Apache Hive, set the following:

• TransportMode: The transport mode to use to communicate with the Hive server. Accepted entries are BINARY and HTTP. BINARY is selected by default.

• AuthScheme: The authentication scheme used. Accepted entries are PLAIN, LDAP, NOSASL, and KERBEROS. PLAIN is selected by default.

Securing Apache Hive Connections

To enable TLS/SSL in the provider, set UseSSL to True.

To connect, set the following connection properties.

Set Url to the machine name or IP address of the server and the port the server is running on, for example, https://server:port. The User and Password are required to authenticate to the HPCC system specified in Url. Note that LDAP authentication is not currently supported.

Set Version to the WsSQL Web server version. Note that if you have not already done so, you will need to install the WsSQL service on the HPCC server. The connector uses the WsSQL Web service to interact with the underlying HPCC system.

Set Cluster to the target cluster.

Connecting to Sage 50 UK

The provider connects to Sage 50 UK data through the SData REST API included in the Sage 50 UK installation. SData allows access to local company datasets as well as datasets on network drives.

After Configuring the Sage SData Service, connect with the below steps, the URL property should be set to the address of the company dataset desired. To obtain the address, do the following:

1. If you have not already done so, open the Sage 50 UK software.

2. Select Tools > Internet Options .

3. Select the Sdatasettings tab.

4. Click Details next to the Sage 50 software application you want to connect to. A window opens containing a list of company names along with the addresses to their corresponding datasets.

5. Set the URL property to the value in the address field next to the company desired.

Authenticating to Sage 50 UK

The User and Password properties must be set to valid Sage 50 UK user credentials. These values are the same values used to log in to the Sage 50 UK software. To authenticate with HTTP digest to the SData service, set AuthScheme to Digest. Otherwise, Basic AuthScheme will be used.

Note: If the dataset you want to connect to is not displayed, the permissions on the Sage 50 UK folder location may not be correct. If you are connecting to a dataset on a networked drive, ensure:

• You are using UNC paths to the folder on the machine you are using as your SData provider.

• You set the SData service login rights to a user who has full rights over the network share or map drive.

Starting the SData Service

The Provider for Sage 50 UK connects to Sage 50 UK via the Sage SData service (which is Sage's Web toolkit for connecting to Sage instances) that is built into the Sage 50 UK software. SData allows for remote access to Sage software applications. By default, Sage UK 2015 instances will have SData turned on and ready for use.

You can follow the steps below to verify that the SData service is started.

1. If you have not already done so, open Sage 50.

2. Navigate to Tools > Internet Options. The Internet Options window is displayed.

3. Select the Sdatasettings tab. A list is displayed of Sage software applications that are currently available.

4. To turn the SData service on for the application, select the On option.

5. If the SData Service Status does not read "SData is currently running", click the Advanced button.

6. In the dialog that is displayed, specify the Port Number desired when making the connection and click the Restart button.

7. If the Windows Firewall button is enabled, click this button to unblock the port. If you have any additional firewalls on the machine, ensure that they are configured to allow connections to be made on the specified port number.

Once you apply any changes, you can then establish a connection to your Sage 50 UK software.

Enabling HTTPS Support

The Sage SData service provides secure and encrypted connections via HTTPS. Data confidentiality and the authenticity of the server are provided by digital certificates. If you do not have a certificate, use IIS to generate a self-signed certificate.

You can follow the steps below to configure the SData service to use a certificate; the provider will validate this certificate against the system trust store by default. If you generated a self-signed certificate, you can add the certificate to this certificate store or set SSLServerCert.

Fulfilling the Certificate Requirements

The certificate has the following requirements:

• The certificate must have a full valid trust chain.

• The common name (CN) for the certificate must match the machine/domain name where the SData service is running. To ensure that the CN is correct, generate the self-signed certificate on the machine where Sage 50 SData is running.

• The certificate must be added to the personal My certificate store for the Local Machine account.

Configuring the SData Service for TLS/SSL

You can then configure the SData service to use the certificate:

1. Navigate to C:\Program Files (x86)\Common Files\Sage SData and open Sage.SData.Service.Config.UI.exe.

2. Click the Advanced button. The SData Configuration window is displayed.

3. Select the Enable HTTPS Access option and select the port desired.

4. If you have any firewalls on your machine, make sure the ports specified are not blocked.

5. Click the button next to the Certificate box.

6. In the resulting dialog, select the certificate.

   If you select a certificate and do not see the certificate name populated in the Certificate textbox, this is most likely due to missing extended properties within the certificate. The extended properties include thumbprint, thumbprint algorithm, key usage, and enhanced key usage.

   Use IIS to avoid this issue: IIS automatically populates these fields when generating a self-signed certificate.

7. Click OK to restart the server.

8. Verify that the Enable HTTPS option is selected in the SData configuration window.

Troubleshooting

If the SData configuration window is closed and reopened but the Enable HTTPS option is not enabled, this is most likely caused by the Sage.SData.Service.exe.config file not being updated properly. Follow the steps below to use the alternate configuration file below.

You will need the certificate thumbprint. Note that the thumbprint data includes spaces. The thumbprint data can be obtained using Windows services. You can also access the thumbprint in the SData configuration window:

1. If you have not already done so, open the Sage.SData.Service.Config.UI.exe application and open the advanced settings.

2. Click the button next to the Certificate box.

3. In the Windows security dialog, click "Click here to view certificate properties". The Certificate Details window is displayed.

4. On the Details tab, copy the value in the Thumbprint field.

Use this value in the CertificateLookupValue setting in the configuration file. For example:

Connecting to Azure Analysis Services

To connect, set the Url property to a valid Azure Analysis Services server, for instance, asazure://southcentralus.asazure.windows.net/server, in addition to authenticating.

Optionally, set Database to distinguish which Azure database on the server to connect to.

Authenticating to Azure Analysis Services

Azure AD

Azure AD is a connection type that leverages OAuth to authenticate. OAuth requires the authenticating user to interact with Azure Analysis Services using an internet browser. The provider facilitates this in several ways as described below. Set your AuthScheme to AzureAD. All AzureAD flows assume that you have done so.

Azure Service Principal

Azure Service Principal is a connection type that goes through OAuth. Set your AuthScheme to AzureServicePrincipal. The authentication as an Azure Service Principal is handled via the OAuth Client Credentials flow, and it does not involve direct user authentication. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.

Note: You must create a custom application prior to assigning a role. See Creating a Custom AzureAD App below for more information.

When authenticating using an Azure Service Principal, you must register an application with an Azure AD tenant. Follow the steps below to create a new service principal that can be used with the role-based access control.

Assign a role to the application

To access resources in your subscription, you must assign a role to the application.

1. Open the Subscriptions page by searching and selecting the Subscriptions service from the search bar.

2. Select the particular subscription to assign the application to.

3. Open the Access control (IAM) and select Add > Add role assignment to open the Add role assignment page.

4. Select Owner as the role to assign to your created Azure AD app.

Complete the Authentication

You are ready to connect after setting one of the below connection properties groups, depending on the configured app authentication (client secret or certificate).

In both methods

Before choosing client secret or certicate authentication, follow these steps then continue to the relevant section below:

1. AuthScheme: Set this to the AzureServicePrincipal in your app settings.

2. InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

3. AzureTenant: Set this to the tenant you wish to connect to.

4. OAuthClientId: Set this to the client Id in your app settings.

Authenticating using a Client Secret

Continue with the following:

1. OAuthClientId: Set this to the client Id in your app settings.

2. OAuthClientSecret: Set this to the client secret in your app settings.

Authenticating using a Certificate

Continue with the following:

1. OAuthJWTCert: Set this to the JWT Certificate store.

2. OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

Azure Password

To connect using your Azure credentials directly, specify the following connection properties:

• AuthScheme: Set this to AzurePassword.

• User: Set this to your user account you use to connect to Azure.

• Password: Set this to the password you use to connect to Azure.

• AzureTenant: Set this to the Directory (tenant) ID, found on the Overview page of the OAuth app used to authenticate to Azure Analysis Services on Azure.

MSI

If you are running Azure Analysis Services on an Azure VM, you can leverage Managed Service Identity (MSI) credentials to connect:

• AuthScheme: Set this to AzureMSI.

The MSI credentials are automatically obtained for authentication.

Create a Custom AzureAD App

Follow the steps below to obtain the AzureAD values for your application, the OAuthClientId and OAuthClientSecret.

2. In the left-hand navigation pane, select Azure Active Directory, then applicationRegistrations, and click New registration.

3. Enter an application name and select the desired tenant setup. When creating a custom AzureAD application in Azure Active Directory, you can define whether the application is single- or multi-tenant. 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 ADO.NET Provider for Azure Analysis Services. Otherwise, the authentication attempt fails with an error. If your application is for private use only, "Accounts in this organization directory only" should be sufficient. Otherwise, if you want to distribute your application, choose one of the multi-tenant options.

4. Set the redirect url to http://localhost:33333, the provider's default. Or, specify a different port and set CallbackURL to the exact reply URL you defined.

5. Click Register to register the new application. This opens an application management screen. Note the value in Application (client) ID as the OAuthClientId and the Directory (tenant) ID as the AzureTenant.

6. Navigate to the "Certificates & Secrets" and define the application authentication type. There are two types of authentication available: using a client secret or a certificate. The recommended authentication method is using a certificate.

   • Option 1: Upload a certificate: In "Certificates & Secrets", select Upload certificate and the certificate to upload from your local machine.

   • Option 2: Create a new application secret: In "Certificates & Secrets", select New Client Secret for the application and specify its duration. After saving the client secret, the key value is displayed. Copy this value as it is displayed only once. You will need it as the OAuthClientSecret.

7. Select API Permissions > Add.

8. Save your changes.

9. If you have selected to use permissions that require admin consent, you can grant them from the current tenant on the API Permissions page.

Custom AzureAD Service Principal Applications

When authenticating using an Azure Service Principal, you must create both a custom AzureAD application and a service principal that can access the necessary resources. Follow the steps below to create a custom AzureAD application and obtain the connection properties for Azure Service Principal authentication.

Create a Custom AzureAD App with an Azure Service Principal

Follow the steps below to obtain the AzureAD values for your application.

2. In the left-hand navigation pane, select Azure Active Directory then App Registrations and click New registration.

3. Enter an app name and select Any Azure AD Directory - Multi Tenant. Then set the redirect url to http://localhost:33333, the provider's default.

4. After creating the application, copy the Application (client) Id value displayed in the "Overview" section. This value is used as the OAuthClientId

5. Define the app authentication type by going to the "Certificates & Secrets" section. There are two types of authentication available: using a client secret and using a certificate. The recommended authentication method is via a certificate.

   • Option 1 - Upload a certificate: In "Certificates & Secrets", select Upload certificate and the certificate to upload from your local machine.

   • Option 2 - Create a new application secret: In "Certificates & Secrets", select New Client Secret for the application and specify its duration. After saving the client secret, the key value is displayed. Copy this value as it is displayed only once. You will use it as the OAuthClientSecret.

6. On the Authentication tab, make sure to select Access tokens (used for implicit flows).

The connector for Apache HBase connects to Apache HBase via the HBase REST (Stargate) server.

Set the Port and Server properties to connect to Apache HBase.

The Server property will typically be the host name or IP address of the server hosting Apache HBase. If there are multiple nodes, you will use the host name or IP address of the machine running the REST (Stargate) server.

1.1 Starting the Server

Different Hadoop distributions contain different interfaces and means of starting and stopping the HBase REST server, along with different default port settings.

In most distributions, the HBase REST server can be started in the foreground by running the following command: "hbase rest start -p <port>". Please consult your Hadoop distribution's documentation for further information regarding the HBase REST server.

1.2 Authenticating to Apache HBase

The connector for Apache HBase supports authentication over Basic and Negotiate.

1.2.1 No Authentication

By default, no authentication (or anonymous auth) is used. Set AuthScheme to None to explicitly enforce no authentication.

1.2.2 Authenticating with Basic

Basic authentication may be used by setting AuthScheme to Basic. In addition, set the following:

• User: The Apache HBase user;

• Password: The Apache HBase password;

1.2.3 Authenticating with Kerberos

To authenticate with Kerberos, set AuthScheme to NEGOTIATE and set the User and Password.

To authenticate to Apache HBase using Kerberos, set the following properties:

• AuthScheme: Set this to KERBEROS

• KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.

• KerberosSPN: Set this to the service and host of the Apache HBase Kerberos Principal. This will be the value prior to the '@' symbol (for instance, hbase/MyHost) of the hbase.regionserver.kerberos.principal of the hbase-site.xml file (for instance, hbase/MyHost@EXAMPLE.COM).

1.2.3.1 Retrieve the Kerberos Ticket

You can use one of the following options to retrieve the required Kerberos ticket.

1.2.3.2 MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you won't need to set the User or Password connection properties with this option.

1. Ensure that you have an environment variable created called KRB5CCNAME.

2. Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file will be created when generating your ticket with MIT Kerberos Ticket Manager.

3. To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information will appear in Kerberos Ticket Manager and will now be stored in the credential cache file.

4. Now that the credential cache file has been created, the provider will use the cache file to obtain the kerberos ticket to connect to Apache HBase.

As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the provider will use the specified cache file to obtain the kerberos ticket to connect to Apache HBase.

1.2.3.3 Keytab File

If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do this, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

1.2.3.4 User and Password

If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a User and Password combination. To do this, set the User and Password properties to the user/password combo that you use to authenticate with Apache HBase.

1.2.3.5 Cross-Realm Authentication

More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g. where one realm/KDC is used for user authentication and another realm/KDC used for obtaining the service ticket).

In such an environment, the KerberosRealm and KerberosKDC properties can be set to the values required for user authentication. The KerberosServiceRealm and KerberosServiceKDC properties can be set to the values required to obtain the service ticket.

The following are the connection properties for Apache HBase. Not all properties are required. Enter only property values pertaining to your installation. Several properties will be automatically initialized with the appRules defaults.

Connecting to Adobe Analytics

In order to connect to Adobe Analytics, the GlobalCompanyId and RSID need to be identified. By default, the provider attempts to automatically identify your company and report suite. Alternatively, you can identify the company and report suite explicitly:

Global Company Id

GlobalCompanyId is an optional connection property. If left empty, the provider tries to automatically detect the Global Company ID. To find the Global Company ID:

1. Find it in the request URL for the users/me endpoint on the .

2. Expand the users endpoint and then click the GET users/me button.

3. Click the Try it out > Execute buttons.

4. Set the GlobalCompanyId connection property to the Global Company ID shown in the Request URL immediately preceding the users/me endpoint.

Report Suite Id

RSID is an optional connection property. If not set, the driver tries to automatically detect it. To get a full list of your report suites along with their identifiers next to the name, navigate to Admin > Report Suites.

Authenticating to Adobe Analytics

Adobe Analytics uses the OAuth authentication standard. You can authenticate with OAuth integration or Service Account integration.

User Accounts (OAuth)

AuthScheme must be set to OAuth in all user account flows.

You must create a custom OAuth app to connect to the Adobe Analytics.

Create an App for OAuth Integration

Follow the steps below to create a custom app and obtain the connection properties in a specific OAuth authentication flow.

• Click the Create new project button.

• Select the Add API option.

• Select Adobe Analytics, click Next, and then select OAuth and then click Next again.

• Select the Web option and fill out the redirect URIs. For a desktop application, you can use a localhost URL such as https://localhost:33333. For a web application, supply the URL of the page to redirect to on your website.

• Click Save configured API.

Your client is now created. Notice your client has an Client ID (API Key) and a Client Secret. These will be needed to get your auth code and to generate access tokens.

Create an App for Service Account Integration

Follow the steps below to create a custom app and obtain the connection properties in a specific Service Account authentication flow.

• Click the Create new project button.

• Select the Add API option.

• Select Adobe Analytics, click Next, and then select Service Account (JWT) and then click Next again.

• Choose either to Generate a key pair or Upload your public key. If you choose to Generate a key pair, save the config.zip file locally as this contains the certificate you'll need to complete the connection. Click Next after the key is created or uploaded.

• Creating Your Own Public Key Certificate

  • MacOS and Linux Open a terminal and execute the following command: openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt

  • Windows Download an OpenSSL client such as OpenSSL Light to generate public certificates. The following steps will be for OpenSSL Light Open a command line window and execute the following commands: 1) cd "C:\Program Files\OpenSSL-Win64\bin" 2) .\openssl.exe req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt

• Select one or more product profiles (in product profiles you can set permissions of the app.) and then click Save configured API.

Your client is now created. Notice your client has Client ID (API Key), Client Secret, Organization ID and Technical account ID. These will be needed to get JWT token and to generate access tokens.

Get and Refresh the OAuth Access Token

After setting the following, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• OAuthClientId (custom applications only): Set this to the client Id assigned when you registered your app.

• OAuthClientSecret (custom applications only): Set this to the client secret assigned when you registered your app.

• CallbackURL (custom application only): Set this to the redirect URI defined when you registered your app. For example: https://localhost:3333

When you connect, the provider opens Adobe Analytics's OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. The provider obtains an access token from Adobe Analytics and uses it to request data.

2. The OAuth values are saved in the path specified in OAuthSettingsLocation, to be persisted across connections.

The provider refreshes the access token automatically when it expires.

Service Account (JWT OAuth)

Set the AuthScheme to OAuthJWT to authenticate with this method.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set to GETANDREFRESH.

• OAuthClientId: Set to the client Id in your app settings.

• OAuthClientSecret: Set to the client secret in your app settings.

• OAuthJWTCertType: Set to "PUBLIC_KEY_FILE".

• OAuthJWTCert: Set to the path to the .key file you generated.

• OAuthJWTCertPassword: Set to the password of the .key file.

• OAuthJWTSubject: The subject, your Technical Account ID from the Adobe I/O Console integration, in the format: id@techacct.adobe.com.

• OAuthJWTIssuer: The issuer, your Organization ID from the Adobe I/O Console integration, in the format org_ident@AdobeOrg. Identifies your organization that has been configured for access to the Adobe I/O API.

When you connect the provider completes the OAuth flow for a service account.

1. Creates and signs the JWT with the claim set required by the provider.

2. Exchanges the JWT for the access token.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

4. Submits the JWT for a new access token when the token expires.

Connecting to Veeva Vault

In order to connect to your Veeva Vault account, you will first need to specify the Url connection property to the host you see in the address bar after logging in to your account, ex. https://myvault.veevavault.com.

OpenID Connect with Azure AD

OpenID Connect with Azure AD is a connection type that goes through OAuth. Set the AuthScheme to AzureADOpenID and the OpenIDConnectProfileID connection property to the Id of your Open ID Connect profile, which can be found by navigating to Admin > Settings > OAuth 2.0 / OpenID Connect Profiles and expanding the details of your OpenID Connect Profile.

Authenticating to Veeva Vault

There are two authentication methods available for connecting to your Veeva Vault data source, Basic and OAuth 2.0 / OpenID Connect with the Azure AD Authentication Provider.

User Credentials

Set the AuthScheme to Basic and set the User and Password to your user login credentials.

OpenID with AzureAD

OpenID Connect with Azure AD is a connection type that goes through OAuth. Set the AuthScheme to AzureADOpenID. The following sections assume that you have done so.

Follow the steps below to authenticate with the credentials for a custom OAuth app. See . Get an OAuth Access Token

You are ready to connect after setting one of the below connection properties groups depending on the authentication type.

1. Authenticating using a Client Secret

   • OAuthClientId: Set this to the Client Id in your app settings.

   • OAuthClientSecret: Set this to the Client Secret in your app settings.

   • CallbackURL: Set this to the Redirect URL in your app settings.

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken. .

   • Optionally, depending on the required claims to complete the authentication with the Veeva Vault data source, you may need to set additional scopes via the Scope property. For example, to get the user name and email claims from the UserInfo endpoint, you will need to set the scope value to: 'openid profile email offline_access'.

2. Authenticating using a Certificate

   • OAuthClientId: Set this to the Client Id in your app settings.

   • OAuthJWTCert: Set this to the JWT Certificate store.

   • OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

   • CallbackURL: Set this to the Redirect URL in your app settings.

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken. .

   • Optionally, depending on the required claims to complete the authentication with the Veeva Vault data source, you may need to set additional scopes via the Scope property. For example, to get the user name and email claims from the UserInfo endpoint, you will need to set the scope value to: 'openid profile email offline_access'.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Create an App for OAuth Integration

Follow the steps below to create a custom app and obtain the connection properties in a specific OAuth authentication flow.

• Navigate to the following URL: .

• Click the Create new project button.

• Select the Add API option.

• Select Adobe Analytics, click Next, and then select OAuth and then click Next again.

• Select the Web option and fill out the redirect URIs. For a desktop application, you can use a localhost URL such as https://localhost:33333. For a web application, supply the URL of the page to redirect to on your website.

• Click Save configured API.

Your client is now created. Notice your client has an Client ID (API Key) and a Client Secret. These will be needed to get your auth code and to generate access tokens.

Create an App for Service Account Integration

Follow the steps below to create a custom app and obtain the connection properties in a specific Service Account authentication flow.

• Navigate to the following URL: .

• Click the Create new project button.

• Select the Add API option.

• Select Adobe Analytics, click Next, and then select Service Account (JWT) and then click Next again.

• Choose either to Generate a key pair or Upload your public key. If you choose to Generate a key pair, save the config.zip file locally as this contains the certificate you'll need to complete the connection. Click Next after the key is created or uploaded.

• Creating Your Own Public Key Certificate

  • Download an OpenSSL client such as OpenSSL Light to generate public certificates. The following steps will be for OpenSSL Light Open a command line window and execute the following commands: 1) cd "C:\Program Files\OpenSSL-Win64\bin" 2) .\openssl.exe req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt

• Select one or more product profiles (in product profiles you can set permissions of the app.) and then click Save configured API.

Your client is now created. Notice your client has Client ID (API Key), Client Secret, Organization ID and Technical account ID. These will be needed to get JWT token and to generate access tokens.

Connecting to HDFS

In order to connect, set the following connection properties:

• Host: Set this value to the host of your HDFS installation.

• Port: Set this value to the port of your HDFS installation. Default port: 50070

• UseSSL: (Optional) Set this value to 'True', to negotiate TLS/SSL connections to the HDFS server. Default: 'False'.

Authenticating to HDFS

There are two authentication methods available for connecting to the HDFS data source, Anonymous Authentication and Negotiate (Kerberos) Authentication.

Anonymous Authentication

In some situations, HDFS may be connected to without any authentication connection properties. To do so, set the AuthScheme to None (default).

Kerberos

When authentication credentials are required, you can use .

Connecting to Azure

Set Account to the storage account name and set the AccessKey of the storage account to connect. Follow the steps below to obtain these values:

If using Storage as the Backend (default):

1. Log into the Azure portal and select Storage Accounts in the services menu on the left.

2. If you currently do not have any storage accounts, create one by clicking the Add button.

3. Click the link for the storage account you want to use and select Access Keys under Settings. The Access Keys window contains the storage account name and key (you can use either key1 or key2 to connect) that you will need to use in the provider. These properties map to the Account and AccessKey provider connection properties respectively.

If using CosmosDB as the Backend:

1. Log into the Azure portal and select Cosmos DB in the services menu on the left.

2. Click the link for the Cosmos DB account you want to use and select Connection String under Settings. The Connection String window contains the Cosmos DB account name and primary key that you will need to use in the provider. These properties map to the Account and AccessKey provider connection properties respectively.

Connecting to Greenplum

To connect to Greenplum, set the Server, Port (the default port is 5432), and Database connection properties and set the User and Password you want to use to authenticate to the server. If the Database property is not specified, the provider connects to the user's default database (it is the same name as the user).

Authenticating to Greenplum

The CData ADO.NET Provider for Greenplum supports the md5, password, Kerberos and SASL (particulary, SCRAM-SHA-256) authentication methods.

The specific authentication method is setup in the pg_hba.conf file on the Greenplum Server. You can find instructions about authentication setup on the Greenplum Server here. The md5, password and SASL authentication methods do not require additional setup by the CData ADO.NET Provider for Greenplum.

Kerberos

The Greenplum Server initiates authentication with the Kerberos Server when the driver for Greenplum attempts a connection. You need to setup Kerberos on the Greenplum Server to activate this authentication method. After you have Kerberos authentication setup on the Greenplum Server, see Using Kerberos for details on how to authenticate with Kerberos

Before You Connect

Before you can connect to IBM Cloud Object Storage, you need to register a IBM Cloud Object Storage instance, then find and note your IBM Cloud Object Storage API Key and CRN.

Register a New Instance of Cloud Object Storage

If you do not already have Cloud Object Storage in your IBM Cloud account, you can follow the procedure below to install an instance of SQL Query in your account:

1. Log in to your IBM Cloud account.

2. Navigate to the Cloud Object Storage page, choose a name for your instance and click Create. You will be redirected to the instance of Cloud Object Storage you just created.

API Key

You can obtain your ApiKey as follows:

1. Log in to your IBM Cloud account.

2. Navigate to the Platform API Keys page.

3. On the middle-right corner, click Create an IBM Cloud API Key to create a new API Key.

4. In the pop-up window, specify the API Key name and click Create. Note the API Key as you can never access it again from the dashboard.

Cloud Object Storage CRN

By default, the provider will attempt to automatically determine a Cloud Object Storage CRN. However, if you have multiple accounts, you will need to specify the CloudObjectStorageCRN explicitly. You can obtain this value in one of two ways:

• Query the Services view. This will list your IBM Cloud Object Storage instances along with the CRN for each.

• Locate the CRN directly in IBM Cloud. To do so, navigate to your IBM Cloud Dashboard. In the Resource List, under Storage, select your Cloud Object Storage resource to get its CRN.

Connecting to IBM Cloud Object Storage

You can now set the following to connect to data:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• ApiKey: Set this to your API key which was noted during setup.

• CloudObjectStorageCRN (Optional): Set this to your noted cloud object storage CRN. While the provider attempts to retrieve this automatically, specifying this explicitly is recommended if you have more than one Cloud Object Storage account.

When you connect, the provider completes the OAuth process.

1. Extracts the access token and authenticates requests.

2. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Connecting to Spark SQL

Specify the following to establish a connection with Spark SQL:

• Server: Set this to the host name or IP address of the server hosting SparkSQL.

• Port: Set this to the port for the connection to the SparkSQL instance.

• TransportMode: The transport mode to use to communicate with the SparkSQL server. Accepted entries are BINARY and HTTP. BINARY is selected by default.

Securing Spark SQL Connections

To enable TLS/SSL in the provider, set UseSSL to True.

Authenticating to Spark SQL

The service may be authenticated to using the PLAIN, LDAP, NOSASL, KERBEROS auth schemes.

PLAIN

To authenticate with PLAIN, set the following connection properties:

• AuthScheme: Set this to PLAIN.

• User: Set this to user to login as.

• Password: Set this to the password of the user.

To authenticate, set User and Password.

LDAP

To authenticate with LDAP, set the following connection properties:

• AuthScheme: Set this to LDAP.

• User: Set this to user to login as.

• Password: Set this to the password of the user.

To authenticate, set User, Password, and AuthScheme.

NOSASL

When using NOSASL, no authentication is performed. Set the following connection properties:

• AuthScheme: Set this to NOSASL.

Kerberos

Please see Apache HDFS connector for details on how to authenticate with Kerberos.

Connecting to Databricks

To connect to a Databricks cluster, set the properties as described below. Note: The needed values can be found in your Databricks instance by navigating to 'Clusters', selecting the desired cluster, and selecting the JDBC/ODBC tab under 'Advanced Options'.

• Server: Set to the Server Hostname of your Databricks cluster.

• Port: 443

• TransportMode: HTTP

• HTTPPath: Set to the HTTP Path of your Databricks cluster.

• UseSSL: True

• AuthScheme: PLAIN

• User: Set this to user to login as

• Password: Set to your personal access token (value can be obtained by navigating to the User Settings page of your Databricks instance and selecting the Access Tokens tab).

GoogleContacts uses the OAuth authentication standard. You can use OAuth to authorize the provider to access Google APIs on behalf of individual users or on behalf of users in a domain.

Using a User Account to Authenticate to GoogleContacts

The user account flow requires the authenticating user to interact with GoogleContacts via the browser.

Using a Service Account to Connect to GoogleContacts

Service accounts have silent authentication, without user authentication in the browser. You can also use a service account to delegate enterprise-wide access scopes to the provider.

You need to create an OAuth application in this flow. You can then connect to GoogleContacts data that the service account has permission to access.

To obtain an OAuthAccessToken, you need to register an app and set the following connection properties.

• OAuthClientId: Set this to the client Id in your app settings.

• OAuthClientSecret: Set this to the client secret in your app settings.

Using a Service Account to Connect to Domain-Wide Data

You can use a service account in this OAuth flow to access Google APIs on behalf of users in a domain. A domain administrator must delegate domain-wide access to the service account.

To complete the service account flow, you need to generate a private key in the Google APIs Console. In the service account flow, the provider obtains an OAuthAccessToken to authenticate that it has the same scope of access to Google APIs as the service account. The provider exchanges a JSON Web token (JWT) to obtain the access token. The private key is required to sign the JWT.

Generate a Private Key

If you are connecting from a service account, follow the steps below:

1. Log into the Google API Console and open a project. Select the API Manager from the main menu.

2. Click Credentials -> Create Credentials -> Service Account Key.

3. In the Service Account menu, select New Service Account or select an existing service account.

4. If you are creating a new service account, additionally select one or more roles. You can assign primitive roles at the project level in the IAM and Admin section; other roles enable you to further customize access to Google APIs.

5. In the Key Type section, select the P12 key type.

6. Download the key pair. The private key's password is displayed: Set this in OAuthJWTCertPassword.

7. In the Service Account Keys section on the Credentials page, click Manage Service Accounts and set OAuthJWTIssuer to the email address displayed in service account Id.

8. In the API Manager, click Library and enable the Drive, Calendar, and Contacts APIs. To enable an API, click the API and then click Enable API.

Authenticate with a Service Account

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

• OAuthJWTCertType: Set this to "PFXFILE".

• OAuthJWTCertPassword: Set this to the password of the .p12 file.

• OAuthJWTCertSubject: Set this to "*" to pick the first certificate in the certificate store.

• OAuthJWTIssuer: Set this to the email address of the service account.

• OAuthJWTCert: Set this to the path to the .p12 file.

• OAuthJWTSubject: Set this to the email address of the user for whom the application is requesting delegate access.

When you connect the provider completes the OAuth flow for a service account:

1. Creates and signs the JWT with the claim set required by the provider.

2. Exchanges the JWT for the access token.

3. Submits the JWT for a new access token when the token expires.

Authenticating to Google Drive

The provider supports using user accounts, service accounts and GCP instance accounts for authentication.

The following sections discuss the available authentication schemes for Google Drive:

• User Accounts (OAuth)

• Service Account (OAuthJWT)

• GCP Instance Account

User Accounts (OAuth)

AuthScheme must be set to OAuth in all user account flows.

Enable the Google Drive API

Follow these steps to enable the Google Drive API:

1. Navigate to the Google Cloud Console.

2. Select Library from the left-hand navigation menu. This opens the Library page.

3. In the search field, enter "Google Drive API" and select Google Drive API from the search results.

4. On the Google Drive API page, click ENABLE.

Create an OAuth Application for User Accounts (OAuth)

When using AuthScheme=OAuth, and you're using a web application, you must create an OAuth Client ID Application. For desktop and headless flows, creating a custom OAuth application is optional.

Follow these steps to create a custom OAuth application:

1. Navigate to the Google Cloud Console.

2. If you have not done so, follow the steps in the console to create an OAuth consent screen.

3. Select Credentials from the left-hand navigation menu.

4. On the Credentials page, select Create Credentials > OAuth Client ID.

5. In the Application Type menu, select Web application.

6. Specify a name for your OAuth custom web application.

7. Under Authorized redirect URIs, click ADD URI and enter a redirect URI. Press Enter.

8. Click CREATE, which returns you to the Credentials page.

9. A window opens that displays your client Id and client secret. Although the client secret is accessible from from the Google Cloud Console, we recommend you write down the client secret. You need both the client secret and client Id to specify the OAuthClientId and OAuthClientSecret connection properties.

Service Accounts (OAuthJWT)

To authenticate using a service account, you must create a new service account and have a copy of the accounts certificate.

Create an OAuth Application for Service Accounts (OAuthJWT)

When using AuthScheme=OAuthJWT, you must create a Service Account Application. Follow these steps:

1. Navigate to the Google Cloud Console.

2. If you have not done so, follow the steps in the console to create an OAuth consent screen.

3. Select Credentials from the left-hand navigation menu.

4. On the Credentials page, select Create Credentials > Service account.

5. On the Create service account page, enter the Service account name, the Service account ID, and, optionally, a description.

6. Click DONE. This returns you to the Credentials page.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH, which instructs the provider to automatically attempt to get and refresh the OAuth access token.

• OAuthClientId: (custom applications only) Set this to the Client Id in your custom OAuth application settings.

• OAuthClientSecret: (custom applications only) Set this to the Client Secret in the custom OAuth application settings.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process as follows:

• Extracts the access token from the callback URL.

• Obtains a new access token when the old one expires.

• Saves OAuth values in OAuthSettingsLocation that persist across connections.

For a JSON file, set these properties:

• AuthScheme: Set this to OAuthJWT.

• InitiateOAuth: Set this to GETANDREFRESH.

• OAuthJWTCertType: Set this to GOOGLEJSON.

• OAuthJWTCert: Set this to the path to the .json file provided by Google.

• OAuthJWTSubject: (optional) Only set this value if the service account is part of a GSuite domain and you want to enable delegation. The value of this property should be the email address of the user whose data you want to access.

For a PFX file, set these properties instead:

• AuthScheme: Set this to OAuthJWT.

• InitiateOAuth: Set this to GETANDREFRESH.

• OAuthJWTCertType: Set this to PFXFILE.

• OAuthJWTCert: Set this to the path to the .pfx file provided by Google.

• OAuthJWTCertPassword: (optional) Set this to the .pfx file password. In most cases you must provide this since Google encrypts PFX certificates.

• OAuthJWTCertSubject: (optional) Set this only if you are using a OAuthJWTCertType which stores multiple certificates. Should not be set for PFX certificates generated by Google.

• OAuthJWTIssuer: Set this to the email address of the service account. This address will usually include the domain iam.gserviceaccount.com.

• OAuthJWTSubject: (optional) Only set this value if the service account is part of a GSuite domain and you want to enable delegation. The value of this property should be the email address of the user whose data you want to access.

GCP Instance Accounts

When running on a GCP virtual machine, the provider can authenticate using a service account tied to the virtual machine. To use this mode, set AuthScheme to GCPInstanceAccount.

Connecting to Asana

You can optionally set the following to refine the data returned from Asana.

• WorkspaceId: Set this to the globally unique identifier (gid) associated with your Asana Workspace to only return projects from the specified Workspace. To get your Workspace Id, navigate to https://app.asana.com/api/1.0/workspaces while logged into Asana. This displays a JSON object containing your Workspace name and Id.

• ProjectId: Set this to the globally unique identifier (gid) associated with your Asana Project to only return data mapped under the specified Project. Project Ids can be found in the URL of your project's Overview page. This will be the numbers directly after /0/.

Authenticating to Asana

Asana uses the OAuth authentication standard.

User Accounts (OAuth)

To obtain an OAuthClientId, OAuthClientSecret, and CallbackURL, you first need to create an app linked to your Asana account.

To create an app linked to your Asana account:

1. Log in to your Asana account.

2. Navigate to My profile Settings > Apps > Manage Developer Apps or https://app.asana.com/0/developer-console.

3. Under My apps, select New app. Specify the app name, then select Create app.

4. Once your app created, set Redirect URL to http://localhost:33333 (or a different available port of your choice), then select add.

Once you are done with creating a new app, it will be displayed on your screen. From there, you can click View Client ID to reveal your newly created app's OAuthClientId and OAuthClientSecret.AuthScheme must be set to OAuth in all user account flows.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• OAuthClientId (custom applications only): Set this to the client Id assigned when you registered your app.

• OAuthClientSecret (custom applications only): Set this to the client secret assigned when you registered your app.

• CallbackURL (custom application only): Set this to the redirect URI defined when you registered your app. For example: https://localhost:3333

When you connect, the provider opens Asana's OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. The provider obtains an access token from Asana and uses it to request data.

2. The OAuth values are saved in the path specified in OAuthSettingsLocation, to be persisted across connections.

The provider refreshes the access token automatically when it expires.

Use the OAuth authentication standard to connect to Google Calendar. You can authenticate with a user account or with a service account. A service account is required to grant organization-wide access scopes to the provider. The provider facilitates these authentication flows as described below.

Authenticate with a User Account

1. Log into the Google API Console.

2. Click Create Project or select an existing project.

3. In the API Manager, click Credentials -> Create Credentials -> OAuth Client Id -> Web Application. In the Authorized Redirect URIs box, enter the URL you want to be used as a trusted redirect URL, where the user will return with the token that verifies that they have granted your app access.

4. Click Create. The OAuthClientId and OAuthClientSecret are displayed.

5. Click Library -> Google Calendar API -> Enable API.

Authenticate with a Service Account

Service accounts have silent authentication, without user authentication in the browser. You can also use a service account to delegate enterprise-wide access scopes to the provider.

You need to create an OAuth application in this flow.

1. Log into the Google API Console and open a project. Select the API Manager from the main menu.

2. Click Create Credentials -> Service Account Key.

3. In the Service Account menu, select New Service Account or select an existing service account.

4. If you are creating a new service account, additionally select one or more roles. You can assign primitive roles at the project level in the IAM and Admin section; other roles enable you to further customize access to Google APIs.

5. In the Key Type section, select the P12 key type.

6. Create the app to download the key pair. The private key's password is displayed: Set this in OAuthJWTCertPassword.

7. In the service accounts section, click Manage Service Accounts and set OAuthJWTIssuer to the email address displayed in the service account Id field.

8. Click Library -> Google Calendar API -> Enable API.

You can then connect to Google Calendar data that the service account has permission to access.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH.

• OAuthJWTCertType: Set this to "PFXFILE".

• OAuthJWTCert: Set this to the path to the .p12 file you generated.

• OAuthJWTCertPassword: Set this to the password of the .p12 file.

• OAuthJWTCertSubject: Set this to "*" to pick the first certificate in the certificate store.

• OAuthJWTIssuer: In the service accounts section, click Manage Service Accounts and set this field to the email address displayed in the service account Id field.

• OAuthJWTSubject: Set this to your enterprise Id if your subject type is set to "enterprise" or your app user Id if your subject type is set to "user".

When you connect the provider completes the OAuth flow for a service account.

1. Creates and signs the JWT with the claim set required by the provider.

2. Exchanges the JWT for the access token.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

4. Submits the JWT for a new access token when the token expires.

Connecting to Wasabi

To connect to Wasabi set AccessKey and SecretKey in the connection string.

Set the following to refine data access:

• Set this Region to the region where your Wasabi data is hosted.

Obtaining the Access Key

1. Sign in to the Wasabi console.

2. To create or manage the access keys for a user, select the Access Keys tab.

3. Click Create New Access Key and use the credentials that will be displayed to authenticate to Wasabi services.

Connecting to Airtable

The provider requests tables and views from Airtable. Authenticate, specify a base, and specify a list of tables to connect.

• ApiKey: Log into Airtable and navigate to the Account icon in the top-right corner. Then, select Account from the dropdown menu. From the Account page, navigate to the API section. Then, click Generate API key. Set the ApiKey to the generated key.

• BaseId: From the same API section, identify your BaseId. To locate this value, navigate to https://airtable.com/api and select a base. In the introduction section of the Airtable documentation for the selected base, note the value specified in "The ID of this base is Id."

• TableNames: A comma-separated list of table names for the selected base in the format TableA,TableB..etc.. Supply the table names exactly as they are displayed in the Airtable UI.

• ViewNames (optional): A comma-separated list of views in the format TableA.ViewA,TableA.ViewB,..etc. These are the same names of the views as found in the UI.

Note: Do not use the '.' character in column names. It is used for building column names based on paths and may risk breaking INSERT/UPDATE statements. If you already have column names that contain the '.' character, set PathDelimiter to a character that is not used in column names.

Establishing a Connection

Available Schemas

There are two services available for connecting to Exchange. These are EWS (Exchange Web Services) and the Microsoft Graph. Exchange Web Services is available for both Exchange OnPremise and Online, but is no longer receiving updates. Microsoft recommends switching to using the Microsoft Graph for Exchange Online users. Both are available with our tool.

To switch between the two, use the Schema connection property to set either EWS or MSGraph. If you wish to use EWS with Exchange Online, set Schema to EWS and the Platform to Exchange_Online.

Connecting to Exchange using Exchange OnPremise

When using an OnPremise edition of Exchange, OnPremise Set User, Password, and AuthScheme; by default, the provider performs Basic authentication, but Windows (NTLM), Kerberos, and delegated authentication are also supported.

Authenticating with Kerberos

Authenticating with Kerberos

To authenticate to Exchange using Kerberos, set the following properties:

• AuthScheme: Set this to NEGOTIATE

• KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.

• KerberosSPN: Set this to the service and host of the Exchange Kerberos Principal. This will be the value prior to the '@' symbol (for instance, ) of the (for instance, ).

Retrieve the Kerberos Ticket

You can use one of the following options to retrieve the required Kerberos ticket.

MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you won't need to set the User or Password connection properties with this option.

1. Ensure that you have an environment variable created called KRB5CCNAME.

2. Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file will be created when generating your ticket with MIT Kerberos Ticket Manager.

3. To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information will appear in Kerberos Ticket Manager and will now be stored in the credential cache file.

4. Now that the credential cache file has been created, the provider will use the cache file to obtain the kerberos ticket to connect to Exchange.

As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the provider will use the specified cache file to obtain the kerberos ticket to connect to Exchange.

Keytab File

If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do this, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

User and Password

If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a User and Password combination. To do this, set the User and Password properties to the user/password combo that you use to authenticate with Exchange.

Cross-Realm Authentication

More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g. where one realm/KDC is used for user authentication and another realm/KDC used for obtaining the service ticket).

In such an environment, the KerberosRealm and KerberosKDC properties can be set to the values required for user authentication. The KerberosServiceRealm and KerberosServiceKDC properties can be set to the values required to obtain the service ticket.

In addition to the authentication values, set the Server property to the address of the Exchange server you are connecting to and set Platform to the Exchange version. Finally, set Schema to EWS.

Connecting to Exchange using Exchange Online

When connecting to Exchange Online, authentication will be done via OAuth. If you are connecting to Exchange Online platform through EWS, set the AuthScheme property to OAuth. Otherwise if you will be using Microsoft Graph to connect to Exchange Online, resources will be pulled from a different service so the Schema should be set to MSGraph. When Schema is set to MSGraph, the Platform value will be ignored.

Follow the steps below to obtain the OAuth values for your app, the OAuthClientId and OAuthClientSecret.

1. Log in to https://portal.azure.com.

2. In the left-hand navigation pane, select Azure Active Directory then App Registrations and click the Add button.

3. Enter an app name and set the radio button for "Any Azure AD Directory - Multi Tenant". Then set the redirect url to something such as http://localhost:33333, the provider's default. Or, set a different port of your choice and set CallbackURL to the exact reply URL you defined.

4. After creating the app, go to the Certificates & Secrets section, create a Client Secret for the app and select a duration.

5. After you save the key, a value for the key is displayed once. Set OAuthClientSecret to the key value. Set OAuthClientId to the Application Id.

6. Select API Permissions and then click Add. If you plan for your app to connect without a user context, select the Application Permissions (OAuthGrantType = CLIENT). Otherwise, when selecting permissions, use the Delegated permissions.

7. If you are connecting to Exchange through EWS schema, select Exchange API and add EWS.AccessAsUser.All permission. If you are connecting to Exchange through MSGraph schema, select Microsoft Graph API and add the following permissions: Calendars.ReadWrite.Shared, Contacts.ReadWrite, Group.Read.All, Group.ReadWrite.All, User.ReadWrite.All, and Mail.ReadWrite.Shared.

8. Save your changes.

9. If you have selected to use permissions that require admin consent (such as the Application Permissions), you may grant them from the current tenant on the API Permissions page. Otherwise, follow the Admin consent steps below

10. Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case.

    When creating a new OAuth app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked stating "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

    The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, there will be a button for Grant Consent. You can consent here for your app to have permissions on the tenant it was created under.

Authenticating to Microsoft Teams

Microsoft Teams uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

Azure AD

Azure AD is a connection type that leverages OAuth to authenticate. OAuth requires the authenticating user to interact with Microsoft Teams using an internet browser. The provider facilitates this in several ways as described below. Set your AuthScheme to AzureAD. All AzureAD flows assume that you have done so.

See Creating a Custom AzureAD App for information about creating custom applications and reasons for doing so.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• OAuthClientId: (custom applications only) Set this to the client Id in your application settings.

• OAuthClientSecret: (custom applications only) Set this to the client secret in your application settings.

• CallbackURL: Set this to the Redirect URL in your application settings.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation that persist across connections.

Admin Consent

Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case.

Admin Consent Permissions

When creating a new AzureAD app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked as "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, click Grant Consent for your app to have permissions on the tenant under which it was created.

After the administrator has approved the OAuth Application, you can continue to authenticate.

Client Credentials

Client credentials refers to a flow in OAuth where there is no direct user authentication taking place. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context. This makes the authentication flow a bit different from standard.

Client OAuth Flow

All permissions related to the client oauth flow require admin consent. You must create your own OAuth app in order to use client credentials. See Creating a Custom AzureAD App for more details.

In your App Registration in portal.azure.com, navigate to API Permissions and select the Microsoft Graph permissions. There are two distinct sets of permissions - Delegated and Application permissions. The permissions used during client credential authentication are under Application Permissions. Select the permissions you require for your integration.

You are ready to connect after setting one of the connection properties groups depending on the authentication type.

1. Authenticating using a Client Secret

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

   • AzureTenant: Set this to the tenant you wish to connect to.

   • OAuthGrantType: Set this to CLIENT.

   • OAuthClientId: Set this to the client Id in your app settings.

   • OAuthClientSecret: Set this to the client secret in your app settings.

2. Authenticating using a Certificate

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

   • AzureTenant: Set this to the tenant you wish to connect to.

   • OAuthGrantType: Set this to CLIENT.

   • OAuthClientId: Set this to the client Id in your app settings.

   • OAuthJWTCert: Set this to the JWT Certificate store.

   • OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

Authentication with client credentials takes place automatically like any other connection, except there is no window opened prompting the user. Because there is no user context, there is no need for a browser popup. Connections will take place and be handled internally.

Azure Service Principal

Azure Service Principal is a connection type that goes through OAuth. Set your AuthScheme to AzureServicePrincipal. The authentication as an Azure Service Principal is handled via the OAuth Client Credentials flow, and it does not involve direct user authentication. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.

Note: You must create a custom application prior to assigning a role. See Creating a Custom AzureAD App for more information.

When authenticating using an Azure Service Principal, you must register an application with an Azure AD tenant. Follow the steps below to create a new service principal that can be used with the role-based access control.

Assign a role to the application

To access resources in your subscription, you must assign a role to the application.

1. Open the Subscriptions page by searching and selecting the Subscriptions service from the search bar.

2. Select the particular subscription to assign the application to.

3. Open the Access control (IAM) and select Add > Add role assignment to open the Add role assignment page.

4. Select Owner as the role to assign to your created Azure AD app.

Complete the Authentication

You are ready to connect after setting one of the below connection properties groups, depending on the configured app authentication (client secret or certificate).

In both methods

Before choosing client secret or certicate authentication, follow these steps then continue to the relevant section below:

1. AuthScheme: Set this to the AzureServicePrincipal in your app settings.

2. InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

3. AzureTenant: Set this to the tenant you wish to connect to.

4. OAuthClientId: Set this to the client Id in your app settings.

Authenticating using a Client Secret

Continue with the following:

1. OAuthClientId: Set this to the client Id in your app settings.

2. OAuthClientSecret: Set this to the client secret in your app settings.

Authenticating using a Certificate

Continue with the following:

1. OAuthJWTCert: Set this to the JWT Certificate store.

2. OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

MSI

If you are running Microsoft Teams on an Azure VM, you can leverage Managed Service Identity (MSI) credentials to connect:

• AuthScheme: Set this to AzureMSI.

The MSI credentials are automatically obtained for authentication.

Slack uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

Create an app to obtain the OAuth client credentials, the OAuthClientId and OAuthClientSecret. To create your app, go to https://api.slack.com/apps. Specify an app name and the app's workspace. You can see the Client Id and Client Secret listed in the App Credentials section under Basic information.

Set a Callback URL

After creating your application, define your app's CallbackURL:

1. In your app settings, go to OAuth & Permissions

2. In the Redirect URLs section click Add a New Redirect URL.

3. Set the callback URL to http://127.0.0.1:33333, or another port of your choice. Ensure that you save the URL.

Configure Permission Scopes

Follow the instructions below to configure the API permissions your app requests. In order to use all possible features, the necessary scopes are: channels:read, groups:read, im:read, mpim:read, channels:write, groups:write, im:write, mpim:write, channels:history, groups:history, im:history, mpim:history, search:read, chat:write:user, chat:write:bot, files:read, files:write:user, pins:read, pins:write, usergroups:read, usergroups:write, reminders:read, reminders:write, users:read, users.profile:write.

1. In your app settings, go to the Scopes section, under OAuth & Permissions.

2. In the Select Permission Scopes subsection, click the menu to add permissions by scope or API method.

Distribute Your App

To allow users in other workspaces to install your app, follow the instructions below:

1. In your app settings, click Manage Distribution under the Settings section.

2. Complete the procedures to set a callback URL and configure permissions.

3. Click Activate Public Distribution.

Set the following connection properties to connect:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the access token in the connection string.

• OAuthClientId: Set this to the Client Id in your app settings.

• OAuthClientSecret: Set this to the Client Secret in your app settings.

• CallbackURL: Set this to the Redirect URL in your app settings.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Refreshes the access token when it expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

See Excel Services

Authenticating to Microsoft OneNote

Microsoft OneNote uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

Azure AD

Azure AD is a connection type that leverages OAuth to authenticate. OAuth requires the authenticating user to interact with Microsoft Teams using an internet browser. The provider facilitates this in several ways as described below. Set your AuthScheme to AzureAD. All AzureAD flows assume that you have done so.

See Creating a Custom AzureAD App for information about creating custom applications and reasons for doing so.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• OAuthClientId: (custom applications only) Set this to the client Id in your application settings.

• OAuthClientSecret: (custom applications only) Set this to the client secret in your application settings.

• CallbackURL: Set this to the Redirect URL in your application settings.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation that persist across connections.

Admin Consent

Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case.

Admin Consent Permissions

When creating a new AzureAD app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked as "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, click Grant Consent for your app to have permissions on the tenant under which it was created.

After the administrator has approved the OAuth Application, you can continue to authenticate.

Client Credentials

Client credentials refers to a flow in OAuth where there is no direct user authentication taking place. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context. This makes the authentication flow a bit different from standard.

Client OAuth Flow

All permissions related to the client oauth flow require admin consent. You must create your own OAuth app in order to use client credentials. See Creating a Custom AzureAD App for more details.

In your App Registration in portal.azure.com, navigate to API Permissions and select the Microsoft Graph permissions. There are two distinct sets of permissions - Delegated and Application permissions. The permissions used during client credential authentication are under Application Permissions. Select the permissions you require for your integration.

You are ready to connect after setting one of the connection properties groups depending on the authentication type.

1. Authenticating using a Client Secret

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

   • AzureTenant: Set this to the tenant you wish to connect to.

   • OAuthGrantType: Set this to CLIENT.

   • OAuthClientId: Set this to the client Id in your app settings.

   • OAuthClientSecret: Set this to the client secret in your app settings.

2. Authenticating using a Certificate

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

   • AzureTenant: Set this to the tenant you wish to connect to.

   • OAuthGrantType: Set this to CLIENT.

   • OAuthClientId: Set this to the client Id in your app settings.

   • OAuthJWTCert: Set this to the JWT Certificate store.

   • OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

Authentication with client credentials takes place automatically like any other connection, except there is no window opened prompting the user. Because there is no user context, there is no need for a browser popup. Connections will take place and be handled internally.

Azure Service Principal

Azure Service Principal is a connection type that goes through OAuth. Set your AuthScheme to AzureServicePrincipal. The authentication as an Azure Service Principal is handled via the OAuth Client Credentials flow, and it does not involve direct user authentication. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.

Note: You must create a custom application prior to assigning a role. See Creating a Custom AzureAD App for more information.

When authenticating using an Azure Service Principal, you must register an application with an Azure AD tenant. Follow the steps below to create a new service principal that can be used with the role-based access control.

Assign a role to the application

To access resources in your subscription, you must assign a role to the application.

1. Open the Subscriptions page by searching and selecting the Subscriptions service from the search bar.

2. Select the particular subscription to assign the application to.

3. Open the Access control (IAM) and select Add > Add role assignment to open the Add role assignment page.

4. Select Owner as the role to assign to your created Azure AD app.

Complete the Authentication

You are ready to connect after setting one of the below connection properties groups, depending on the configured app authentication (client secret or certificate).

In both methods

Before choosing client secret or certicate authentication, follow these steps then continue to the relevant section below:

1. AuthScheme: Set this to the AzureServicePrincipal in your app settings.

2. InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

3. AzureTenant: Set this to the tenant you wish to connect to.

4. OAuthClientId: Set this to the client Id in your app settings.

Authenticating using a Client Secret

Continue with the following:

1. OAuthClientId: Set this to the client Id in your app settings.

2. OAuthClientSecret: Set this to the client secret in your app settings.

Authenticating using a Certificate

Continue with the following:

1. OAuthJWTCert: Set this to the JWT Certificate store.

2. OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

MSI

If you are running Microsoft Teams on an Azure VM, you can leverage Managed Service Identity (MSI) credentials to connect:

• AuthScheme: Set this to AzureMSI.

The MSI credentials are automatically obtained for authentication.

Smartsheet supports connections via the following authentication methods:

• Using the Personal Access Token

• Using OAuth

Personal Access Token

Use the personal token to test and to access your own data. To obtain the personal token, follow the steps below:

1. Log into Smartsheet.

2. Click Account and select Personal Settings.

3. Click API Access and use the form to generate new access tokens or manage existing access tokens.

Set the AuthScheme to PersonalAccessToken. You can then set the PersonalAccessToken to the token you generated.

OAuth

Smartsheet uses the OAuth authentication standard. To use it, you'll need to set the AuthScheme to OAuth. To authenticate using OAuth, you will need to register an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

However, to access your own account or for testing purposes you can instead set the PersonalAccessToken connection property to the Personal Access Token you get when you create an application.

Create an App

For this step you need a developer account. You can follow the procedure below to register an app and obtain the OAuth client credentials, the client Id and client secret:

1. Log into your Smartsheet developer account and click Account -> Developer Tools -> Create New App.

2. Enter a name, description, and other information to be displayed to users when they log in to grant permissions to your app.

3. If you are making a desktop application, set the Redirect URL to http://localhost:33333 or a different port number of your choice.

   If you are making a Web application, set the Redirect URL to a page on your Web app you would like the user to be returned to after they have authorized your application.

Authenticate to Smartsheet

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the App client id in your app settings.

• OAuthClientSecret: Set this to the App secret in your app settings.

• CallbackURL: Set this to the App redirect URL in your app settings.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Refreshes the access token when it expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Connecting to Act! CRM

You can connect to either Act! CRM or Act! Premium Cloud. Set the following to connect:

• User: The username used to authenticate to the Act! database.

• Password: The password used to authenticate to the Act! database.

• URL: The URL where the Act! CRM account is hosted. For example: http://serverName/.

• ActDatabase: The name of the Act! database you want to connect to. This is found by going to the About Act! Premium menu of your account, found at the top right of the page, in the ? menu. Use the Database Name in the window that appears.

• ActCloudName (Act! Premium Cloud only): The handle assigned to the Act! Premium Cloud account. It is found in the browser's address field when opening the online account, in the form https://eup1-iis-04.eu.hosted.act.com/ActCloudName.

Microsoft Dynamics 365 Sales uses oAuth Authentication

Other properties (Proxy...) are detailed in section common properties

Authenticating to Microsoft OneDrive

Microsoft OneDrive uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

Azure AD

Azure AD is a connection type that leverages OAuth to authenticate. OAuth requires the authenticating user to interact with Microsoft Teams using an internet browser. The provider facilitates this in several ways as described below. Set your AuthScheme to AzureAD. All AzureAD flows assume that you have done so.

See Creating a Custom AzureAD App for information about creating custom applications and reasons for doing so.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

• OAuthClientId: (custom applications only) Set this to the client Id in your application settings.

• OAuthClientSecret: (custom applications only) Set this to the client secret in your application settings.

• CallbackURL: Set this to the Redirect URL in your application settings.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation that persist across connections.

Admin Consent

Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case.

Admin Consent Permissions

When creating a new AzureAD app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked as "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, click Grant Consent for your app to have permissions on the tenant under which it was created.

After the administrator has approved the OAuth Application, you can continue to authenticate.

Client Credentials

Client credentials refers to a flow in OAuth where there is no direct user authentication taking place. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context. This makes the authentication flow a bit different from standard.

Client OAuth Flow

All permissions related to the client oauth flow require admin consent. You must create your own OAuth app in order to use client credentials. See Creating a Custom AzureAD App for more details.

In your App Registration in portal.azure.com, navigate to API Permissions and select the Microsoft Graph permissions. There are two distinct sets of permissions - Delegated and Application permissions. The permissions used during client credential authentication are under Application Permissions. Select the permissions you require for your integration.

You are ready to connect after setting one of the connection properties groups depending on the authentication type.

1. Authenticating using a Client Secret

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

   • AzureTenant: Set this to the tenant you wish to connect to.

   • OAuthGrantType: Set this to CLIENT.

   • OAuthClientId: Set this to the client Id in your app settings.

   • OAuthClientSecret: Set this to the client secret in your app settings.

2. Authenticating using a Certificate

   • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

   • AzureTenant: Set this to the tenant you wish to connect to.

   • OAuthGrantType: Set this to CLIENT.

   • OAuthClientId: Set this to the client Id in your app settings.

   • OAuthJWTCert: Set this to the JWT Certificate store.

   • OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

Authentication with client credentials takes place automatically like any other connection, except there is no window opened prompting the user. Because there is no user context, there is no need for a browser popup. Connections will take place and be handled internally.

Azure Service Principal

Azure Service Principal is a connection type that goes through OAuth. Set your AuthScheme to AzureServicePrincipal. The authentication as an Azure Service Principal is handled via the OAuth Client Credentials flow, and it does not involve direct user authentication. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.

Note: You must create a custom application prior to assigning a role. See Creating a Custom AzureAD App for more information.

When authenticating using an Azure Service Principal, you must register an application with an Azure AD tenant. Follow the steps below to create a new service principal that can be used with the role-based access control.

Assign a role to the application

To access resources in your subscription, you must assign a role to the application.

1. Open the Subscriptions page by searching and selecting the Subscriptions service from the search bar.

2. Select the particular subscription to assign the application to.

3. Open the Access control (IAM) and select Add > Add role assignment to open the Add role assignment page.

4. Select Owner as the role to assign to your created Azure AD app.

Complete the Authentication

You are ready to connect after setting one of the below connection properties groups, depending on the configured app authentication (client secret or certificate).

In both methods

Before choosing client secret or certicate authentication, follow these steps then continue to the relevant section below:

1. AuthScheme: Set this to the AzureServicePrincipal in your app settings.

2. InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

3. AzureTenant: Set this to the tenant you wish to connect to.

4. OAuthClientId: Set this to the client Id in your app settings.

Authenticating using a Client Secret

Continue with the following:

1. OAuthClientId: Set this to the client Id in your app settings.

2. OAuthClientSecret: Set this to the client secret in your app settings.

Authenticating using a Certificate

Continue with the following:

1. OAuthJWTCert: Set this to the JWT Certificate store.

2. OAuthJWTCertType: Set this to the type of the certificate store specified by OAuthJWTCert.

MSI

If you are running Microsoft Teams on an Azure VM, you can leverage Managed Service Identity (MSI) credentials to connect:

• AuthScheme: Set this to AzureMSI.

The MSI credentials are automatically obtained for authentication.

Establishing a Connection

Authenticating to Office 365

Office 365 uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.

Authenticating using MSI Authentication

If you are running Office 365 on an Azure VM, you can leverage Managed Service Identity (MSI) credentials to connect:

• AuthScheme: Set this to AzureMSI.

The MSI credentials will then be automatically obtained for authentication.

alesforce Chatter uses OAuth 2.0 authentication. To authenticate to Salesforce Chatter via OAuth 2.0, you will need to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL by registering an app with Salesforce Chatter.

Create a Connected App

You can follow the procedure below to register an app and obtain the OAuth client credentials, the OAuthClientId and OAuthClientSecret:

1. Log into Salesforce.com.

2. From Setup, enter Apps in the Quick Find box and then click the link to create an app. In the Connected Apps section of the resulting page, click New.

3. Enter a name to be displayed to users when they log in to grant permissions to your app, along with a contact email address.

4. Click Enable OAuth Settings and enter a value in the Callback URL box.

   If you are making a desktop application, set the Callback URL to https://localhost:33333 or a different port number of your choice.

   If you are making a Web application, set the Callback URL to a page on your Web app you would like the user to be returned to after they have authorized your application. Note that you must redirect the user to an HTTPS URL.

5. Select the scope of permissions that your app will request from the user, including Chatter.

6. Once you have created the app, click your app name to open a page with information about your app. The OAuth client credentials, the consumer key and consumer secret, are displayed.

Authenticate to Salesforce Chatter :

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the Consumer Key in your app settings.

• OAuthClientSecret: Set this to the Consumer Secret in your app settings.

• CallbackURL: Set this to the Callback URL in your app settings, https://localhost:portNumber.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.

2. Refreshes the access token when it expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

SAP Hybris Cloud for Customer uses basic authentication. Set the Url and Tenant to the appropriate values for your instance and set User and Password to your login credentials.

Oracle Sales uses Basic authentication over SSL; after setting the following connection properties, you are ready to connect:

• Username: Set this to the user name that you use to log into your Oracle Cloud service.

• Password: Set this to your password.

• HostURL: Set this to the Web address (URL) of your Oracle Cloud service.

Highrise uses the OAuth authentication standard. To authenticate to Highrise, you will need to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL by registering an app with Highrise. You will also need to set the AccountId to connect to data.

You can connect to SuiteCRM data via the V4.1 API by simply setting the following connection properties:

• Schema: Set this to suitecrmv4.

• Url: Set this to the URL associated with the SuiteCRM application, for example http://suite.crm.com.

• User: Set this to the user associated with the SuiteCRM account.

• Password: Set this to the password associated with the SuiteCRM account.

Connecting To SuiteCRM V8 API

Before Connecting

Before you connect to SuiteCRM V8 API you will need to first configure it in your SuiteCRM instance. The API can be configured in SuiteCRM version 7.10+. To configure the API, please follow the steps written in the SuiteCRM JSON API docs, found here: https://docs.suitecrm.com/developer/api/developer-setup-guide/json-api/#_before_you_start_calling_endpoints .

The SuiteCRM V8 API uses OAuth2.0 as its main method of authentication using 2 types of grant type, password or client credentials.

The SuiteCRM V8 API uses OAuth2.0 as its main method of authentication using 2 types of grant type, password or client credentials. To authenticate to SuiteCRM V8 API, please do the following. Note that you have to be an admin to create credentials, create roles, assign roles to users etc.

Note: The OAuth flow is the same in a headless machine.

Register an Application

To obtain the OAuth client credentials, the consumer key, and consumer secret:

1. Log in to your admin account.

2. On profile dropdown select Admin > OAuth2 Clients and Tokens and click New Password Client or New Client Credentials Client.

3. Enter a name and a secret.

4. Click Save.

Assign Roles for API Access

Usually when authenticating with a client credentials grant type, you will have full access to the API. For authentication with password grant type, the user should have permissions for each module/table.

Users' access to certain resources can be set by configuring REST roles and assigning users to the specific REST roles.

To create a role:

1. On the profile dropdown, select Admin > Role Management and click Create Role.

2. Enter name and description and click Save. Then, you will be redirected to the role configuration menu where you can select permissions to any operation on any module.

3. After you are done with setting up the permissions, you can click Save.

To assign a role to a user:

1. On profile dropdown, select Admin > Role Management and click on the role you want to assign to a user.

2. Scroll down to the bottom and click Select User.

3. A user search window will appear.

4. Select the users you want to assign the role to and click Select > Save.

Client Credentials Grant

After setting the following connection properties, you are ready to connect:

• Schema: Set this to the suitecrmv8.

• AuthScheme: Set this to OAuthClient.

• OAuthClientId: Set this to the client key that you received.

• OAuthClientSecret: Set this to the client secret that you noted.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

• URL: The base URL of your SuiteCRM system. For example, https://suitecrmhost/.

Password Grant

After setting the following connection properties, you are ready to connect:

• Schema: Set this to the suitecrmv8.

• AuthScheme: Set this to OAuthPassword.

• OAuthClientId: Set this to the client key that you received.

• OAuthClientSecret: Set this to the client secret that you noted.

• User: Set this to the username associated with the user.

• Password: Set this to the password associated with the user.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

• URL: The base URL of your SuiteCRM system. For example, https://suitecrmhost/.

To connect, set the URL and provide authentication. The URL is your Zendesk Support URL: https://{subdomain}.zendesk.com.

Authenticating to Zendesk

Zendesk uses Basic authentication or the OAuth 2 authentication standard.

Use Basic to connect to your own data. Use OAuth to allow other users to connect to their data.

Using Basic Authentication

To use Basic authentication, specify your email address and password or your email address and an API token. Set User to your email address and follow the steps below to provide the Password or ApiToken.

1. Enable password access in the Zendesk Support admin interface at Admin > Channels > API.

2. Manage API tokens in the Zendesk Support Admin interface at Admin > Channels > API. More than one token can be active at the same time. Deleting a token deactivates it permanently.

Using OAuth Authentication

OAuth requires the authenticating user to interact with Zendesk using the browser. The provider facilitates this in various ways as described below.

Register an OAuth Application

Follow the procedure below to register a third-party application and obtain the OAuth client credentials, the OAuthClientId and OAuthClientSecret. Note that this procedure requires admin access to your Zendesk account.

1. In the Zendesk Support Admin interface, go to Admin > Channels > API.

2. Click the OAuth Clients tab on the Channels/API page and then click the plus icon (+) on the right side of the client list.

3. Complete the required fields to create a client.

   If you are making a desktop application, set the Redirect URI to http://localhost:33333 or a different port number of your choice.

   If you are making a Web application, set the Redirect URI to a page on your Web app you would like the user to be returned to after they have authorized your application.

4. Click Save. After the page refreshes, a new prepopulated Secret field appears on the lower side.

5. Use the unique identifier as the OAuthClientId and the secret value as the OAuthClientSecret.

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the client Id that you specified in your app settings.

• OAuthClientSecret: Set this to the client secret that you specified in your app settings.

• CallbackURL: Set this to the Redirect URI you specified in your app settings.

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to manage the process to obtain the OAuthAccessToken.

When you connect, the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process.

1. Extracts the access token from the callback URL and authenticates requests.

2. Obtains a new access token when the old one expires.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Establishing a Connection

Authenticating Using Personal Access Token

To authenticate, set the following:

• AuthScheme: Set this to PersonalAccessToken.

• Token: The token used to access the Databricks server. It can be obtained by navigating to the User Settings page of your Databricks instance and selecting the Access Tokens tab.

Authenticating to Azure Active Directory

To authenticate to Databricks using Azure Service Principal:

• AuthScheme: Set this to AzureServicePrincipal.

• AzureTenantId: Set this to the tenant ID of your Microsoft Azure Active Directory.

• AzureClientId: Set to the application (client) ID of your Microsoft Azure Active Directory application.

• AzureClientSecret: Set to the application (client) secret of your Microsoft Azure Active Directory application.

• AzureSubscriptionId: Set this to the Subscription id of your Microsoft Azure Databricks Service Workspace.

• AzureResourceGroup: Set this to the Resource Group name of your Microsoft Azure Databricks Service Workspace.

• AzureWorkspace: Set this to the name of your Microsoft Azure Databricks Service Workspace.

Connecting to Databricks

To connect to a Databricks cluster, set the properties as described below.

Note: The needed values can be found in your Databricks instance by navigating to Clusters, and selecting the desired cluster, and selecting the JDBC/ODBC tab under Advanced Options.

• Database: Set to the name of the Databricks database.

• Server: Set to the Server Hostname of your Databricks cluster.

• HTTPPath: Set to the HTTP Path of your Databricks cluster.

• Token: Set to your personal access token (this value can be obtained by navigating to the User Settings page of your Databricks instance and selecting the Access Tokens tab).

Cloud Storage Configuration

The provider supports DBFS, Azure Blob Storage, and AWS S3 for uploading CSV files.

DBFS Cloud Storage

To use DBFS for cloud storage, set the following:

• CloudStorageType: Set this to DBFS.

• StoreTableInCloud: Set this to True to store tables in cloud storage when creating a new table.

Authenticating to Azure Blob Storage

Set the following to use Azure Blob Storage for cloud storage:

• CloudStorageType: Set this to Azure Blob storage.

• StoreTableInCloud: Set this to True to store tables in cloud storage when creating a new table.

• AzureStorageAccount: Set this to the name of your Azure storage account.

• AzureAccessKey: Set to the storage key associated with your Databricks account. Find this via the azure portal (using the root acoount). Select your storage account and click Access Keys to find this value.

• AzureBlobContainer: Set to the name of you Azure Blob storage container.

Authenticating to AWS S3

Set the following to use AWS S3 for cloud storage:

• CloudStorageType: Set this to AWS S3.

• StoreTableInCloud: Set this to True to store tables in cloud storage when creating a new table.

• AWSAccessKey: The AWS account access key. This value is accessible from your AWS security credentials page.

• AWSSecretKey: Your AWS account secret key. This value is accessible from your AWS security credentials page.

• AWSS3Bucket: Set to the name of your AWS S3 bucket.

• AWSRegion: The hosting region for your Amazon Web Services. The AWS Region value can be obtained by navigating to the Buckets List page of your Amazon S3 service, such as: us-east-1.

Connecting to Amazon S3

Specify the following to connect to data:

• CustomURL: Specify the base S3 service URL if it has a different URL from 'amazonaws.com'. Make sure to specify the full URL. For example: 'http://127.0.0.1:9000'.

• AWSRegion: Set this to the region where your Amazon S3 data is hosted.

Authenticating to Amazon S3

There are several authentication methods available for connecting to Amazon S3 including: authenticating with Root Credentials, Temporary Credentials, as an AWS Role (from an EC2 Instance or by specifying the root credentials), using SSO and using a Credential File.

Obtain AWS Keys

To obtain the credentials for an IAM user, follow the steps below:

1. Sign into the IAM console.

2. In the navigation pane, select Users.

3. To create or manage the access keys for a user, select the user and then go to the Security Credentials tab.

To obtain the credentials for your AWS root account, follow the steps below:

1. Sign into the AWS Management console with the credentials for your root account.

2. Select your account name or number and select My Security Credentials in the menu that is displayed.

3. Click Continue to Security Credentials and expand the "Access Keys" section to manage or create root account access keys.

Root Credentials

To authenticate using account root credentials, set the following:

• AuthScheme: Set this to AwsRootKeys.

• AWSAccessKey: The access key associated with the AWS root account.

• AWSSecretKey: The secret key associated with the AWS root account.

Note: Use of this authentication scheme is discouraged by Amazon for anything but simple tests. The account root credentials have the full permissions of the user, making this the least secure authentication method.

Temporary Credentials

To authenticate using temporary credentials, specify the following:

• AuthScheme: Set this to TemporaryCredentials.

• AWSAccessKey: The access key of the IAM user to assume the role for.

• AWSSecretKey: The secret key of the IAM user to assume the role for.

• AWSSessionToken: Your AWS session token. This will have been provided alongside your temporary credentials. See AWS Identity and Access Management User Guide for more info.

The provider can now request resources using the same permissions provided by long-term credentials (such as IAM user credentials) for the lifespan of the temporary credentials.

If you are also using an IAM role to authenticate, you must additionally specify the following:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the provider to attempt to retrieve credentials for the specified role.

• AWSExternalId: Only if required when you assume a role in another account.

EC2 Instances

If you are using the provider from an EC2 Instance and have an IAM Role assigned to the instance, you can use the IAM Role to authenticate. To do so, set the following properties to authenticate:

• AuthScheme: Set this to AwsEC2Roles.

Do not specify AWSAccessKey and AWSSecretKey because the provider will automatically obtain your IAM Role credentials and authenticate with them.

If you are also using an IAM role to authenticate, you must additionally specify the following:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the provider to attempt to retrieve credentials for the specified role.

• AWSExternalId: Only if required when you assume a role in another account.

IMDSv2 Support

The Amazon S3 provider now supports IMDSv2. Unlike IMDSv1, the new version requires an authentication token. Endpoints and response are the same in both versions. In IMDSv2, the Amazon S3 provider first attempts to retrieve the IMDSv2 metadata token and then uses it to call AWS metadata endpoints. If it is unable to retrieve the token, the provider reverts to IMDSv1.

AWS IAM Roles

In many situations it may be preferable to use an IAM role for authentication instead of the direct security credentials of an AWS root user.

To authenticate as an AWS role, set the following:

• AuthScheme: Set this to AwsIAMRoles.

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the provider to attempt to retrieve credentials for the specified role.

• AWSExternalId: Only if required when you assume a role in another account.

• AWSAccessKey: The access key of the IAM user to assume the role for.

• AWSSecretKey: The secret key of the IAM user to assume the role for.

Note: Roles may not be used when specifying the AWSAccessKey and AWSSecretKey of an AWS root user.

ADFS

Set the AuthScheme to ADFS. The following connection properties need to be set:

• User: Set this to your ADFS username.

• Password: Set this to your ADFS password.

• SSOLoginURL: Set this to the login URL used by the SSO provider.

Below is an example connection string:

ADFS Integrated

To use the ADFS Integrated flow, specify the SSOLoginURL and leave the username and password empty.

Okta

Set the AuthScheme to Okta. The following connection properties are used to authenticate through Okta:

• User: Set to your Okta user.

• Password: Set to your Okta password.

• SSOLoginURL: Set to the login URL used by the SSO provider.

If you are:

• using a trusted application or proxy that overrides the Okta client request

• configuring MFA

then you need to use combinations of SSOProperties input parameters to authenticate using Okta. Otherwise, you do not need to set any of these values.

In SSOProperties when required, set these input parameters:

• APIToken: When authenticating a user via a trusted application or proxy that overrides the Okta client request context, set this to the API Token the customer created from the Okta organization.

• MFAType: Set this if you have configured the MFA flow. Currently we support the following types: OktaVerify, Email, and SMS.

• MFAPassCode: Set this only if you have configured the MFA flow. If you set this to empty or an invalid value, the provider issues a one-time password challenge to your device or email. After the passcode is received, reopen the connection where the retrieved one-time password value is set to the MFAPassCode connection property.

• MFARememberDevice: Okta supports remembering devices when MFA is required. If remembering devices is allowed according to the configured authentication policies, the provider sends a device token to extend MFA authentication lifetime. This property is, by default, set to True. Set this to False only if you do not want MFA to be remembered.

Example connection string:

PingFederate

Set the AuthScheme to PingFederate. The following connection properties need to be set:

• User: Set this to the PingFederate user.

• Password: Set this to PingFederate password for the user.

• SSOLoginURL: Set this to the login url used by the SSO provider.

• SSOExchangeUrl: The Partner Service Identifier URI configured in your PingFederate server instance under: SP Connections > SP Connection > WS-Trust > Protocol Settings. This should uniquely identify a PingFederate SP Connection, so it is a good idea to set it to your AWS SSO ACS URL. You can find it under AWS SSO > Settings > View Details next to the Authentication field.

The following SSOProperties are needed to authenticate to PingFederate:

• AuthScheme (optional): The authorization scheme to be used for the IdP endpoint. The allowed values for this IdP are None or Basic.

Additionally, you can use the following SSOProperties to configure mutual SSL authentication for SSOLoginURL, the WS-Trust STS endpoint:

• SSLClientCert

• SSLClientCertType

• SSLClientCertSubject

• SSLClientCertPassword

Below is an example connection string:

MFA

For users and roles that require Multi-factor Authentication, specify the following to authenticate:

• AuthScheme: Set this to AwsMFA.

• CredentialsLocation: The location of the settings file where MFA credentials are saved. See the Credentials File Location page under Connection String Options for more information.

• MFASerialNumber: The serial number of the MFA device if one is being used.

• MFAToken: The temporary token available from your MFA device.

If you are connecting to AWS (instead of already being connected such as on an EC2 instance), you must additionally specify the following:

• AWSAccessKey: The access key of the IAM user for whom MFA will be issued.

• AWSSecretKey: The secret key of the IAM user whom MFA will be issued.

If you are also using an IAM role to authenticate, you must additionally specify the following:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the provider to attempt to retrieve credentials for the specified role using MFA.

• AWSExternalId: Only if required when you assume a role in another account.

This causes the provider to submit the MFA credentials in a request to retrieve temporary authentication credentials.

Note that you can control the duration of the temporary credentials by setting the TemporaryTokenDuration property (default 3600 seconds).

Credentials Files

You can use a credentials file to authenticate. Any configurations related to AccessKey/SecretKey authentication, temporary credentials, role authentication, or MFA can be used. To do so, set the following properties to authenticate:

• AuthScheme: Set this to AwsCredentialsFile.

• AWSCredentialsFile: Set this to the location of your credentials file.

• AWSCredentialsFileProfile (optional): Optionally set this to the name of the profile you would like to use from the specified credentials file. If not specified, the profile with the name default will be used.

See AWS Command Line Interface User Guide for more information.

AWS Cognito Credentials

If you want to use the provider with a user registered in a User Pool in AWS Cognito, set the following properties to authenticate:

• AuthScheme: Set this to AwsCognitoSrp (recommended). You can also use AwsCognitoBasic.

• AWSCognitoRegion: Set this to the region of the User Pool.

• AWSUserPoolId: Set this to the User Pool Id.

• AWSUserPoolClientAppId: Set this to the User Pool Client App Id.

• AWSUserPoolClientAppSecret: Set this to the User Pool Client Secret.

• AWSIdentityPoolId: Set this to the Identity Pool Id of the Identity Pool that is linked with the User Pool.

• User: Set this to the username of the user registered in the User Pool.

• Password: Set this to the password of the user registered in the User Pool.

Use the OAuth authentication standard to connect to Box. You can authenticate with a user account or with a service account. A service account is required to grant organization-wide access scopes to the provider. The provider facilitates these authentication flows as described below.

1 Authenticate with a User Account

Note: Set the AuthScheme to OAuth to authenticate with this method.

1. Log in to your Box developers dashboard and click Create New App. Select your app type (e.g., Custom App).

2. Select the Standard OAuth 2.0 (User Authentication) authentication method and click View Your App. (After creating your app, you can click Configuration from the main menu to access your app settings.)

3. Set the Redirect URI to http://localhost:33333 or a different port number of your choice. When you connect you will need to set the CallbackURL connection property to this exact URL.

The OAuthClientId and OAuthClientSecret are also displayed in the same page.

1. Select the scope of user permissions your app will request.

2 Authenticate with a Service Account

Note: Set the AuthScheme to OAuthJWT to authenticate with this method.

Service accounts have silent authentication, without user authentication in the browser. You can also use a service account to delegate enterprise-wide access scopes to the provider.

Follow the steps below to create an OAuth application and generate a private key. You will then authorize the service account.

1. Log in to your Box developers dashboard and click Create New App. Select your app type (e.g., Custom App).

2. Select the OAuth 2.0 with JWT (Server Authentication) authentication method and click View Your App. (After creating your app, you can click Configuration from the main menu to access your app settings.)

3. Select the application access level and the scope of user permissions your app will request. The enterprise access level enables you to work with existing users in your enterprise. The application-level setting restricts access to App-type users, users that have only API access.

4. Generate your RSA keypair. First you need to generate your private key. You can do this by running the following OpenSSL command : "openssl genrsa -aes128 -out private_key.pem 2048" (you can install and use the Cygwin package to run the OpenSSL RSA keypair if you are using Windows).

5. Generate your public key by running the following OpenSSL command: "openssl rsa -pubout -in private_key.pem -out public_key.pem". Copy the contents of the generated public_key.pem file and then add it by using the Add and Manage Public Keys option in your app settings.

6. Authorize the application in the enterprise admin console: Click Apps -> Custom Applications -> Authorize New App and enter the Client Id in your app settings.

Note: If you change the JWT access scopes, you will need to reauthorize the application in the enterprise admin console: Click Apps in the main menu and then select the ellipsis button next to your JWT application name. Select Reauthorize App in the menu.

After setting the following connection properties, you are ready to connect:

• InitiateOAuth: Set to GETANDREFRESH.

• OAuthClientId: Set to the Client Id in your app settings.

• OAuthClientSecret: Set to the Client Secret in your app settings.

• OAuthJWTCertType: Set to "PEMKEY_FILE".

• OAuthJWTCert: Set to the path to the .pem file you generated.

• OAuthJWTCertPassword: Set to the password of the .pem file.

• OAuthJWTCertSubject: Set to "*" to pick the first certificate in the certificate store.

• OAuthJWTSubjectType: Set to "enterprise" or "user" depending on the Application Access Value you selected in your app settings. The default value of this connection property is "enterprise".

• OAuthJWTSubject: Set to your enterprise Id if your subject type is set to "enterprise" or your app user Id if your subject type is set to "user".

• OAuthJWTPublicKeyId: Set to the Id of your public key in your app settings.

When you connect the provider completes the OAuth flow for a service account.

1. Creates and signs the JWT with the claim set required by the provider.

2. Exchanges the JWT for the access token.

3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

4. Submits the JWT for a new access token when the token expires.

The following are the connection properties for Box. Not all properties are required. Enter only property values pertaining to your installation. Several properties will be automatically initialized with the appRules defaults.

1 Authenticate via OAuth Authentication

OAuth requires the authenticating user to interact with Dropbox using the browser. The provider facilitates this in various ways as described below.

1. Log in to your Dropbox developers dashboard and click Create New App. Select the Dropbox API type. Select the Full Dropbox access for your app.

2. After creating your app, you can view Configuration from the main menu that displays your app settings.

3. Set the Redirect URI to http://localhost:33333 or a different port number of your choice. When you connect you will need to set the CallbackURL connection property to this exact URL.

The OAuthClientId and OAuthClientSecret are also displayed in the same page.

There are some views (DeletedResources, Events, Teams, TeamMembers) and stored procedures (DeletePermanently) that require certain scopes that are not present in the default connection. To access these, you will need to create your own custom app and grant the following permissions:

• team_info.read

• files.permanent_delete

• members.read

• groups.read

• team_data.member

• events.read

The following are the connection properties for Dropbox. Not all properties are required. Enter only property values pertaining to your installation. Several properties will be automatically initialized with the appRules defaults.

Connecting to Jira

To connect set the URL to your Jira endpoint; for example, https://yoursitename.atlassian.net.

Accessing Custom Fields

By default the provider surfaces only system fields. To access the custom fields for Issues, set IncludeCustomFields to true. Or, you can extend the provider schemas to configure access to custom fields; Please note that the server response time can be significantly slower when custom fields are included.

Set the IncludeCustomFields property to True to expose access to all custom fields.

Authenticating to Jira

OAuth 2.0

You can leverage Jira's "three-legged" OAuth 2.0 support (3LO) to connect to data without providing your login credentials.

AuthScheme must be set to OAuth in all OAuth flows.

To obtain the OAuth client credentials, consumer key, and consumer secret:

1. Log in to your JIRA Cloud site.

2. Navigate to application management at https://developer.atlassian.com/apps/ (not your OAuth credentials at yoursitename.atlassian.net/secure/admin/oauth-credentials, which is for self-hosted tools.)

3. Select Create new app, then name the application. This creates the application.

4. If missing, add OAuth 2.0 functionality to your application by navigating to APIS AND FEATURES > + Add > Add OAuth 2.0 (3LO).

5. From APIS AND FEATURES > + Add, add the Jira platform REST API to your application .

6. From APIS AND FEATURES > + Jira platform REST API, add the desired scopes to your application .

7. You'll additionally need to set up your Callback URL. Navigate to APIS AND FEATURES > OAuth 2.0 (3LO). Enter a URL that is accessible to your application and save the changes.

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set to the consumer key in your application details.

• OAuthClientSecret: Set to the consumer secret in your application details.

• CallbackURL: Set to the callback URL found in your application details under APIS AND FEATURES > OAuth 2.0 (3LO).

• InitiateOAuth: Set to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

• OAuthVersion: Set to 2.0.

• Url: The URL to your JIRA endpoint; for example, https://yoursitename.atlassian.net.

When you connect, the provider opens Jira's OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

• The provider obtains an access token from Jira and uses it to request data.

• Extracts the access token from the callback URL and authenticates requests.

• Saves OAuth values in the path specified in OAuthSettingsLocation. These values persist across connections.

The provider refreshes the access token automatically when it expires.

OAuth 1.0

To connect to Jira you have to follow the steps below:

1. Generate an RSA public/private key pair. In your terminal, run the following commands:
2. Create application links in your account. Go to Settings > Applications > Application links.

3. Enter a test URL for the url field, click Create new link.

4. Ignore the error and click continue. You need only configure incoming calls (from the application to Jira).

5. In the Link applications window, filling in the fields is optional, since they are not relevant to this task. But make sure to select Create incoming link. Click Continue. to go to the next page.

6. Fill in the required fields:

   • Consumer Key: Use any string you want. This is required for the OAuthClientId connection property.

   • Consumer Name: Use any string you want.

   • Public key: Enter the key from the jira_publickey.pem file you generated earlier.

7. Click Continue.

To connect set the following properties:

• URL (for example: https://yoursitename.atlassian.net).

• OAuthClientId to the Consumer Key of your application.

• OAuthClientSecret to any value (such as 'testClientSecret').

• CertificateStore to the location of your private key file.

• CertificateStoreType to the appropriate option based on the private key file being used. If using the generated PEM key file, set CertificateStoreType to PEMKEY_FILE.

• InitiateOAuth to GETANDREFRESH.

API Token

You can establish a connection to any Jira Cloud account by setting the AuthScheme to APIToken and providing the User and APIToken. An API token is necessary for basic authentication to Cloud instances. To generate one, log in to your Atlassian account and navigate to Security > Create and manage API tokens > Create API token. The generated token will be displayed.

Basic

You can establish a connection to any Jira Server instance by setting the AuthScheme to Basic. To connect to a Server Instance provide the User and Password. (Note: Password has been deprecated for connecting to a Cloud Account and is now used only to connect to a Server Instance.)

LDAP

You can establish a connection to any Jira Server instance by setting the AuthScheme to LDAP. Additionally provide the URL, User and Password of the Jira instance. (Note: LDAP Authentication is not currently supported for Cloud accounts.)

Crowd

Set the AuthScheme to Crowd. The following connection properties are used to connect to Crowd:

• User: The CROWD user account.

• Password: The password associated with the Crowd account.

• SSOLoginURL: The login URL associated with the Crowd account. You can find the IDP URL by navigating to your application -> SSO -> SSO information -> Identity provider single sign-on URL.

• SSOAppName: The name of the application in which SSO is enabled.

• SSOAppPassword: The password of the application in which SSO is enabled.

• SSOExchangeUrl: The URL used used to exchange the SAML token for Jira cookies. This URL may have the following formats:

  • https://<authority of Jira instance>/plugins/servlet/samlconsumer

  • https://<authority of Jira instance>/plugins/servlet/samlsso

The following is an example connection string:

Okta

Set the AuthScheme to Okta. The following connection properties are used to authenticate through Okta:

• User: Set to your Okta user.

• Password: Set to your Okta password.

• SSOLoginURL: Set to the login URL used by the SSO provider.

• SSOExchangeUrl: The URL used used to exchange the SAML token for Jira cookies. This URL may have the following formats:

  • https://<authority of Jira instance>/plugins/servlet/samlconsumer

  • https://<authority of Jira instance>/plugins/servlet/samlsso

If you are:

• using a trusted application or proxy that overrides the Okta client request

• configuring MFA