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 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.

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 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.