Establishing a Connection

Enabling SSIS in Visual Studio 2022

If you're using Visual Studio 2022, you will need to install the SQL Server Integration Services Projects extension to use SSIS.

Navigate to Extensions > Manage Extensions.
In the Manage Extensions window's search box, search for "SQL Server Integration Services Projects 2022" and select the extension in the list.
Click Download.
Close Visual Studio and run the downloaded Microsoft.DataTools.IntegrationServices.exe installer. Proceed through the installer with default settings.
Open Visual Studio. There should now be an "Integration Services Project" project template available.

Adding the Apache CouchDB Connection Manager

Create a new connection manager as follows:

Create a Visual Studio project with the "Integration Services Project" template.
In the project, right-click within the Connection Managers window and select New Connection from the menu.
In the Description column, select CData Apache CouchDB Connection Manager and click Add...
Configure the component as described in the next section.

Alternatively, if you have an existing project and CData Apache CouchDB Source or CData Apache CouchDB Destination:

Right-click your CData Apache CouchDB source or destination component in your data flow
Select Edit... to open an editor window.
Click the New... button next to the Connection manager: dropdown selector to create a connection manager.
Configure the component as described in the next section.

Connecting to Apache CouchDB

Apache CouchDB supports three types of authentication:

Basic: Basic username/password authentication.
JWT: Authentication with JWT token.
None: Anonymous access for databases that are public.

If you want your users (or JWT tokens) to have access to only specific databases, you have to configure the admin_only_all_dbs option in the Apache CouchDB instance to grant all users access to the "/_all_dbs" endpoint which is required by the component for listing tables. Otherwise the component won't be able to connect, because the endpoint will throw an authentication error.

Basic Authentication

Set the following to connect to data:

AuthScheme: Basic.
Url: The Url of your Apache CouchDB instance. For example: http://localhost:5984
User The Apache CouchDB user account used to authenticate.
Password The Apache CouchDB password associated with the authenticating user.

JWT Authentication

The following connection properties are required and must always be specified:

AuthScheme: JWT.
Url: The Url of your Apache CouchDB instance. For example: http://localhost:5984.

From here you can:

1. Set the following so that the component automatically generates (and refreshes if applicable) the tokens for you:

Required

JWTSubject: The name of the user to assign to the JWT token.
JWTAlgorithm: The algorithm to use for the JWT token signature.
JWTKeyType: The type of the encryption key.
JWTKey: The encryption key used to sign the JWT token generated by the component.

Optional

JWTIssuer: The issuer of the JWT token.
JWTExpiration: How long the JWT token should remain valid, in seconds.
JWTHeaders: A collection of extra headers that should be included in the JWT header.
JWTClaims: A collection of extra claims that should be included in the JWT payload.
CredentialsLocation: The location of the settings file where the JWT token is saved.

2. Or you can generate the tokens yourself manually and pass them to the component by using the JWTToken connection property.

Generating the key pair

When using asymmetric algorithms to sign the tokens, you must generate a private/public key pair. For that, a cryptographic library like OpenSSL can be used. For example:

# generate private key
openssl genrsa --out private_rsa256.pem 2048

# extract public key
openssl rsa -in private_rsa256.pem -pubout > public_rsa256.pem

JWT Configurations

Refer to CouchDB JWT Authentication Documentation for the following.

The alg and sub are required claims and will always be validated by the Apache CouchDB instance. Other required claims can be configured in the server (see required_claims). In that case, you must use JWTHeaders and JWTClaims so that the component can include those additional claims when generating the JWT token.

You can use roles_claim_name or the roles_claim_path options to assign roles to the JWT tokens.

Refer to the following example for configuring the server and the component:

server configuration

[chttpd]
...
authentication_handlers = {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}
admin_only_all_dbs = false
...

[jwt_auth]
...
required_claims = exp
roles_claim_path = my.nested._couchdb\.roles
rsa:rsa_256 = -----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY\n-----END PUBLIC KEY-----\n
...

component configuration

Url=http://localhost:5984;
JWTSubject=JWT User 1;
JWTAlgorithm=RS256;
JWTKeyType=PEMKEY_FILE;
JWTKey=PATH_TO_FOLDER\private_rsa256.pem;
JWTHeaders=kid : rsa_256 | Custom Header 1 : Test 1;
JWTClaims= my : eyJuZXN0ZWQiOnsiX2NvdWNoZGIucm9sZXMiOlsidXNlcjIiXX19 | Custom Claim 1 : Test 1;

Anonymous