This is an automated email from the ASF dual-hosted git repository.
dzamo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/drill-site.git
The following commit(s) were added to refs/heads/master by this push:
new 8a8fe47ac Document the new storage plugin authentication modes.
8a8fe47ac is described below
commit 8a8fe47ac89fcf2f7eb032844e1817703bf39986
Author: James Turton <[email protected]>
AuthorDate: Tue Feb 21 16:55:26 2023 +0200
Document the new storage plugin authentication modes.
---
.../040-storage-plugin-auth-modes.md | 111 +++++++++++++++++++++
1 file changed, 111 insertions(+)
diff --git a/_docs/en/connect-a-data-source/040-storage-plugin-auth-modes.md
b/_docs/en/connect-a-data-source/040-storage-plugin-auth-modes.md
new file mode 100644
index 000000000..823fa59ba
--- /dev/null
+++ b/_docs/en/connect-a-data-source/040-storage-plugin-auth-modes.md
@@ -0,0 +1,111 @@
+---
+title: "Storage plugin authentication modes"
+slug: "Storage plugin authentication modes"
+parent: "Storage Plugin Configuration"
+---
+**Introduced in release: 1.21**
+
+Drill 1.21 brings with it the ability to configure storage authentication
modes on a per-plugin basis. Three authentication modes are provided but note
that not every plugin need support every mode. Consult the respective plugin
documentation page for information about the authentication modes that it
supports.
+
+## SHARED_USER
+This is the default authentication mode for storage plugins and matches the
authentication behaviour of storage plugins in previous versions of Drill.
Drill connects to the storage using a single set of shared credentials stored
in some credential provider. If no credentials are present, the plugin may
connect with no credentials or make implicit use of the Drillbit's identity
(e.g. OS process user). Authentication to the storage is unaffected by the
Drill query user's identity.
+
+## USER_TRANSLATION
+{% include startnote.html %}At the present time, to use the USER_TRANSLATION
authentication mode the global option `drill.exec.impersonation` must be set to
true.{% include endnote.html %}
+
+Drill connects to the storage using credentials looked up ("translated") for
the Drill query user. Authentication to the storage is a function of the Drill
query user's identity (and that function may be 1-1 or *-1).
+
+## USER_IMPERSONATION
+This authentication mode is not yet implemented but is planned to replace the
global option `drill.exec.impersonation`.
+
+## Syntax
+The authentication mode for a storage plugin is specified in its storage
configuration usign the `authMode` property.
+```
+"authMode" : "SHARED_USER" | "USER_TRANSLATION" | "USER_IMPERSONATION"
+```
+
+## Credential Provider support for authentication modes
+Every credential provider continues to support the default SHARED_USER mode in
the same way that they did for previous versions of Drill. At the time of
writing, the two credential providers that support USER_TRANSLATION are
+
+1. the Plain credentials provider which stores a table of credentials
alongside other storage configuration (with credentials configurable in the
Drill web UI)
+2. the Hashicorp Vault credentials provider which stores credentials at paths
that can be looked up dynamically in Vault.
+
+## SHARED_USER mode examples
+
+### Using the Plain credentials provider
+
+```json
+{
+ "type": "jdbc",
+ "driver": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
+ "url": "jdbc:sqlserver://mssql.somewhere.com:1433;databaseName=test",
+ "username": "sa",
+ "password": "drowssap",
+ "sourceParameters": {
+ "minimumIdle": 0,
+ "keepaliveTime": 60000,
+ "idleTimeout": 300000,
+ "maximumPoolSize": 5
+ },
+ "authMode": "SHARED_USER",
+ "writerBatchSize": 10000,
+ "enabled": true
+}
+```
+
+### Using the Vault credentials provider
+
+```json
+{
+ "type": "jdbc",
+ "driver": "com.mysql.jdbc.Driver",
+ "url": "jdbc:mysql://mysql.somewhere.com:3306",
+ "sourceParameters": {
+ "minimumIdle": 0,
+ "keepaliveTime": 60000,
+ "idleTimeout": 300000,
+ "maximumPoolSize": 5,
+ "registerMbeans": true
+ },
+ "credentialsProvider": {
+ "credentialsProviderType": "VaultCredentialsProvider",
+ "secretPath": "drill/credentials/orgUnit/dataSource-8",
+ "propertyNames": {
+ "username": "username",
+ "password": "password"
+ }
+ },
+ "authMode": "SHARED_USER",
+ "writerBatchSize": 10000,
+ "enabled": true
+}
+```
+
+## USER_TRANSLATION Example
+
+### Using the Vault crendentials provider
+```json
+{
+ "type": "jdbc",
+ "driver": "com.mysql.jdbc.Driver",
+ "url": "jdbc:mysql://mysql.somewhere.com:3306",
+ "sourceParameters": {
+ "minimumIdle": 0,
+ "keepaliveTime": 60000,
+ "idleTimeout": 300000,
+ "maximumPoolSize": 5,
+ "registerMbeans": true
+ },
+ "credentialsProvider": {
+ "credentialsProviderType": "VaultCredentialsProvider",
+ "secretPath": "drill/credentials/orgUnit/alice/dataSource-436",
+ "propertyNames": {
+ "username": "username",
+ "password": "password"
+ }
+ },
+ "authMode": "USER_TRANSLATION",
+ "writerBatchSize": 10000,
+ "enabled": true
+}
+```
