Credentials

A credential is an authentication object for a resource or repository that is external to the database. It consists of the credentials used to authenticate to that external system, with the goal of providing an authentication token to any database object that may need to connect to that system.

A credential name must adhere to the standard naming criteria. Each credential exists within a schema and follows the standard name resolution rules for tables.

The following can make use of credentials:

Any user can create a credential for their own use.

The following services are supported:

  • Amazon S3
  • Azure
  • Docker Repository
  • Google Cloud
  • HDFS
  • JDBC
  • Kafka
    • Apache Cluster
    • Confluent Cluster

Managing Credentials

A credential can be managed using the following API endpoint calls. For managing credentials in SQL, see CREATE CREDENTIAL.

API CallDescription
/create/credentialCreates a credential, given authentication and connection information
/alter/credentialModifies the properties of a credential
/drop/credentialRemoves the credential reference from the database
/show/credentialOutputs the credential's properties
/grant/permission/credentialGrants the permission for a user to use or manage a credential or all credentials
/revoke/permission/credentialRevokes the permission for a user to use or manage a credential or all credentials

Creating a Credential

To create a credential, auser_azure_active_dir_creds, that connects to Azure Active Directory, in Python:

Create Credential (Azure AD) Example 
1
2
3
4
5
6

h_db.create_credential(
    credential_name = 'auser_azure_active_dir_creds',
    type = 'azure_ad',
    identity = uid,
    secret = pwd
)

To create a credential, kafka_ssl_cred, that connects to Kafka via SSL, in Python:

Create Credential (Kafka SSL) Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

h_db.create_credential(
    credential_name = 'kafka_ssl_cred',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://ssl/ca-bundle.crt',
        'ssl.certificate.location': 'kifs://ssl/client.pem',
        'ssl.key.location': 'kifs://ssl/client.key',
        'ssl.key.password': 'Passw0rd!'
    }
)

Provider-Specific Syntax

Several authentication schemes across multiple providers are supported.

Azure BLOB

Password 
1
2
3
4
5
6
7

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'azure_storage_key',
    identity = '<azure storage account name>',
    secret = '<azure storage account key>',
    options = {}
)
SAS Token 
1
2
3
4
5
6
7

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'azure_sas',
    identity = '<azure storage account name>',
    secret = '<azure sas token>',
    options = {}
)
Active Directory 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'azure_ad',
    identity = '<ad client id>',
    secret = '<ad client secret key>',
    options = {
        'azure_storage_account_name': '<azure storage account name>',
        'azure_tenant_id': '<azure tenant id>'
    }
)

GCS

User ID & Key 
1
2
3
4
5
6
7

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'gcs_service_account_id',
    identity = '<gcs account id>',
    secret = '<gcs account private key>',
    options = {}
)
JSON Key 
1
2
3
4
5
6
7
8
9

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'gcs_service_account_keys',
    identity = '',
    secret = '',
    options = {
        'gcs_service_account_keys': '<gcs account json key text>'
    }
)

HDFS

Password 
1
2
3
4
5
6
7

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'hdfs',
    identity = '<hdfs username>',
    secret = '<hdfs password>',
    options = {}
)
Kerberos Keytab 
1
2
3
4
5
6
7
8

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'hdfs',
    identity = '<hdfs username>',
    options = {
        'hdfs_kerberos_keytab': 'kifs://<keytab file path>'
    }
)
Kerberos Token 
1
2
3
4
5
6
7
8
9

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'hdfs',
    identity = '<hdfs username>',
    secret = '',
    options = {
        'hdfs_use_kerberos': 'true'
    }
)

JDBC

Password 
1
2
3
4
5
6
7

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'jdbc',
    identity = '<jdbc username>',
    secret = '<jdbc password>',
    options = {}
)

Kafka (Apache)

Password 
1
2
3
4
5
6

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '<username>',
    secret = '<password>'
)
SSL (Truststore) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://<client truststore path>'
    }
)
SSL (Truststore/Client Auth) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://<client truststore path>',
        'ssl.certificate.location': 'kifs://<client certificate path>'
    }
)
SSL (Encryption) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://<client truststore path>',
        'ssl.certificate.location': 'kifs://<client certificate path>',
        'ssl.key.location': 'kifs://<client key path>',
        'ssl.key.password': '<client key password>'
    }
)
SASL 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SASL_SSL',
        'sasl.mechanism': 'PLAIN',
        'sasl.username': '<sasl username>',
        'sasl.password': '<sasl password>'
    }
)
Kerberos 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SASL_PLAINTEXT',
        'sasl.mechanism': 'GSSAPI',
        'sasl.kerberos.service.name': '<kerberos service name>',
        'sasl.kerberos.keytab': 'kifs://<kerberos keytab file>',
        'sasl.kerberos.principal': '<kerberos principal>'
    }
)
Kerberos SSL 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'kafka',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SASL_SSL',
        'sasl.mechanism': 'GSSAPI',
        'sasl.kerberos.service.name': '<kerberos service name>',
        'sasl.kerberos.keytab': 'kifs://<kerberos keytab file>',
        'sasl.kerberos.principal': '<kerberos principal>',
        'ssl.ca.location': 'kifs://<client truststore path>',
        'ssl.certificate.location': 'kifs://<client certificate path>',
        'ssl.key.location': 'kifs://<client key path>',
        'ssl.key.password': '<client key password>'
    }
)

Kafka (Confluent)

Password 
1
2
3
4
5
6

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '<username>',
    secret = '<password>'
)
SSL (Truststore) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://<client truststore path>'
    }
)
SSL (Truststore/Client Auth) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://<client truststore path>',
        'ssl.certificate.location': 'kifs://<client certificate path>'
    }
)
SSL (Encryption) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SSL',
        'ssl.ca.location': 'kifs://<client truststore path>',
        'ssl.certificate.location': 'kifs://<client certificate path>',
        'ssl.key.location': 'kifs://<client key path>',
        'ssl.key.password': '<client key password>'
    }
)
SASL 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SASL_SSL',
        'sasl.mechanism': 'PLAIN',
        'sasl.username': '<sasl username>',
        'sasl.password': '<sasl password>'
    }
)
Kerberos 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SASL_PLAINTEXT',
        'sasl.mechanism': 'GSSAPI',
        'sasl.kerberos.service.name': '<kerberos service name>',
        'sasl.kerberos.keytab': 'kifs://<kerberos keytab file>',
        'sasl.kerberos.principal': '<kerberos principal>'
    }
)
Kerberos SSL 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'confluent',
    identity = '',
    secret = '',
    options = {
        'security.protocol': 'SASL_SSL',
        'sasl.mechanism': 'GSSAPI',
        'sasl.kerberos.service.name': '<kerberos service name>',
        'sasl.kerberos.keytab': 'kifs://<kerberos keytab file>',
        'sasl.kerberos.principal': '<kerberos principal>',
        'ssl.ca.location': 'kifs://<client truststore path>',
        'ssl.certificate.location': 'kifs://<client certificate path>',
        'ssl.key.location': 'kifs://<client key path>',
        'ssl.key.password': '<client key password>'
    }
)

S3 (Amazon)

Access Key 
1
2
3
4
5
6

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'aws_access_key',
    identity = '<aws access key id>',
    secret = '<aws secret access key>'
)
IAM Role 
1
2
3
4
5
6
7
8
9

h_db.create_credential(
    credential_name = '[<schema name>.]<credential name>',
    type = 'aws_iam_role',
    identity = '<aws access key id>',
    secret = '<aws secret access key>',
    options = {
        's3_aws_role_arn': '<amazon resource name>'
    }
)

Altering a Credential

To alter an existing credential, auser_azure_active_dir_creds, for a new secret, in Python:

1
2
3
4
5
6
7

h_db.alter_credential(
    credential_name = 'auser_azure_active_dir_creds',
    credential_updates_map = {
      'secret': new_pwd
    },
    options = {}
)

Removing a Credential

To remove an existing credential, auser_azure_active_dir_creds, in Python:

1

h_db.drop_credential('auser_azure_active_dir_creds')

Showing a Credential

To show the configuration for an existing credential, auser_azure_active_dir_creds, while masking the secret, in Python:

1
2
3

h_db_read = gpudb.GPUdb(host = [args.url], username = 'auser', password = 'password')

response = h_db_read.show_credential('auser_azure_active_dir_creds')

The output for the above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
    "credential_names": [
        "ki_home.auser_azure_active_dir_creds"
    ],
    "credential_types": [
        "azure_ad"
    ],
    "credential_identities": [
        "uid"
    ],
    "credentials": [
        "{\"credential_name\":\"ki_home.auser_azure_active_dir_creds\",\"type\":\"azure_ad\",\"identity\":\"uid\",\"secret\":\"[redacted]\",\"options\":{}}"
    ],
    "additional_info": [
        {}
    ],
    "info": {},
    "status_info": {
        "status": "OK",
        "message": "",
        "data_type": "show_credential_response",
        "response_time": 5e-05
    }
}

Updating Credential Permissions

To grant credential_read permission to a user, auser, in Python:

1
2
3
4
5

h_db.grant_permission_credential(
    name = 'auser',
    permission = 'credential_read',
    credential_name = 'auser_azure_active_dir_creds'
)

To revoke credential_read permission from a user, auser, in Python:

1
2
3
4
5

h_db.revoke_permission_credential(
    name = 'auser',
    permission = 'credential_read',
    credential_name = 'auser_azure_active_dir_creds'
)