com.databricks.sdk.service.workspace

Class SecretsAPI

java.lang.Object

com.databricks.sdk.service.workspace.SecretsAPI

Direct Known Subclasses:

SecretsExt

@Generated
public class SecretsAPI
extends Object

The Secrets API allows you to manage secrets, secret scopes, and access permissions.

Sometimes accessing data requires that you authenticate to external data sources through JDBC. Instead of directly entering your credentials into a notebook, use Databricks secrets to store your credentials and reference them in notebooks and jobs.

Administrators, secret creators, and users granted permission can read Databricks secrets. While Databricks makes an effort to redact secret values that might be displayed in notebooks, it is not possible to prevent such users from reading secrets.

Constructor Summary

Constructors

Constructor and Description
SecretsAPI(ApiClient apiClient) Regular-use constructor
SecretsAPI(SecretsService mock) Constructor for mocks

Method Summary

Modifier and Type	Method and Description
void	createScope(CreateScope request) Creates a new secret scope.
void	deleteAcl(DeleteAcl request) Deletes the given ACL on the given scope.
void	deleteScope(DeleteScope request) Deletes a secret scope.
void	deleteScope(String scope)
void	deleteSecret(DeleteSecret request) Deletes the secret stored in this secret scope.
AclItem	getAcl(GetAclRequest request) Describes the details about the given ACL, such as the group and permission.
AclItem	getAcl(String scope, String principal)
GetSecretResponse	getSecret(GetSecretRequest request) Gets a secret for a given key and scope.
GetSecretResponse	getSecret(String scope, String key)
SecretsService	impl()
Iterable<AclItem>	listAcls(ListAclsRequest request) Lists the ACLs set on the given scope.
Iterable<AclItem>	listAcls(String scope)
Iterable<SecretScope>	listScopes() Lists all secret scopes available in the workspace.
Iterable<SecretMetadata>	listSecrets(ListSecretsRequest request) Lists the secret keys that are stored at this scope.
Iterable<SecretMetadata>	listSecrets(String scope)
void	putAcl(PutAcl request) Creates or overwrites the ACL associated with the given principal (user or group) on the specified scope point.
void	putSecret(PutSecret request) Inserts a secret under the provided scope with the given name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SecretsAPI

public SecretsAPI(ApiClient apiClient)

Regular-use constructor

SecretsAPI

public SecretsAPI(SecretsService mock)

Constructor for mocks

Method Detail

createScope

public void createScope(CreateScope request)

Creates a new secret scope.

The scope name must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters.

Example request:

.. code::

{ "scope": "my-simple-databricks-scope", "initial_manage_principal": "users" "scope_backend_type": "databricks|azure_keyvault", # below is only required if scope type is azure_keyvault "backend_azure_keyvault": { "resource_id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/xxxx/providers/Microsoft.KeyVault/vaults/xxxx", "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dns_name": "https://xxxx.vault.azure.net/", } }

If ``initial_manage_principal`` is specified, the initial ACL applied to the scope is applied to the supplied principal (user or group) with ``MANAGE`` permissions. The only supported principal for this option is the group ``users``, which contains all users in the workspace. If ``initial_manage_principal`` is not specified, the initial ACL with ``MANAGE`` permission applied to the scope is assigned to the API request issuer's user identity.

If ``scope_backend_type`` is ``azure_keyvault``, a secret scope is created with secrets from a given Azure KeyVault. The caller must provide the keyvault_resource_id and the tenant_id for the key vault. If ``scope_backend_type`` is ``databricks`` or is unspecified, an empty secret scope is created and stored in Databricks's own storage.

Throws ``RESOURCE_ALREADY_EXISTS`` if a scope with the given name already exists. Throws ``RESOURCE_LIMIT_EXCEEDED`` if maximum number of scopes in the workspace is exceeded. Throws ``INVALID_PARAMETER_VALUE`` if the scope name is invalid. Throws ``BAD_REQUEST`` if request violated constraints. Throws ``CUSTOMER_UNAUTHORIZED`` if normal user attempts to create a scope with name reserved for databricks internal usage. Throws ``UNAUTHENTICATED`` if unable to verify user access permission on Azure KeyVault

deleteAcl

public void deleteAcl(DeleteAcl request)

Deletes the given ACL on the given scope.

Users must have the ``MANAGE`` permission to invoke this API.

Example request:

.. code::

{ "scope": "my-secret-scope", "principal": "data-scientists" }

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope, principal, or ACL exists. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call. Throws ``INVALID_PARAMETER_VALUE`` if the permission or principal is invalid.

deleteScope

public void deleteScope(String scope)

deleteScope

public void deleteScope(DeleteScope request)

Deletes a secret scope.

Example request:

.. code::

{ "scope": "my-secret-scope" }

Throws ``RESOURCE_DOES_NOT_EXIST`` if the scope does not exist. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call. Throws ``BAD_REQUEST`` if system user attempts to delete internal secret scope.

deleteSecret

public void deleteSecret(DeleteSecret request)

Deletes the secret stored in this secret scope. You must have ``WRITE`` or ``MANAGE`` permission on the Secret Scope.

Example request:

.. code::

{ "scope": "my-secret-scope", "key": "my-secret-key" }

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope or secret exists. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call. Throws ``BAD_REQUEST`` if system user attempts to delete an internal secret, or request is made against Azure KeyVault backed scope.

getAcl

public AclItem getAcl(String scope,
                      String principal)

getAcl

public AclItem getAcl(GetAclRequest request)

Describes the details about the given ACL, such as the group and permission.

Users must have the ``MANAGE`` permission to invoke this API.

Example response:

.. code::

{ "principal": "data-scientists", "permission": "READ" }

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope exists. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call. Throws ``INVALID_PARAMETER_VALUE`` if the permission or principal is invalid.

getSecret

public GetSecretResponse getSecret(String scope,
                                   String key)

getSecret

public GetSecretResponse getSecret(GetSecretRequest request)

Gets a secret for a given key and scope. This API can only be called from the DBUtils interface. Users need the READ permission to make this call.

Example response:

.. code::

{ "key": "my-string-key", "value": }

Note that the secret value returned is in bytes. The interpretation of the bytes is determined by the caller in DBUtils and the type the data is decoded into.

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret or secret scope exists. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call.

Note: This is explicitly an undocumented API. It also doesn't need to be supported for the /preview prefix, because it's not a customer-facing API (i.e. only used for DBUtils SecretUtils to fetch secrets).

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope or secret exists. Throws ``BAD_REQUEST`` if normal user calls get secret outside of a notebook. AKV specific errors: Throws ``INVALID_PARAMETER_VALUE`` if secret name is not alphanumeric or too long. Throws ``PERMISSION_DENIED`` if secret manager cannot access AKV with 403 error Throws ``MALFORMED_REQUEST`` if secret manager cannot access AKV with any other 4xx error

listAcls

public Iterable<AclItem> listAcls(String scope)

listAcls

public Iterable<AclItem> listAcls(ListAclsRequest request)

Lists the ACLs set on the given scope.

Users must have the ``MANAGE`` permission to invoke this API.

Example response:

.. code::

{ "acls": [{ "principal": "admins", "permission": "MANAGE" },{ "principal": "data-scientists", "permission": "READ" }] }

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope exists. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call.

listScopes

public Iterable<SecretScope> listScopes()

Lists all secret scopes available in the workspace.

Example response:

.. code::

{ "scopes": [{ "name": "my-databricks-scope", "backend_type": "DATABRICKS" },{ "name": "mount-points", "backend_type": "DATABRICKS" }] }

Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call.

listSecrets

public Iterable<SecretMetadata> listSecrets(String scope)

listSecrets

public Iterable<SecretMetadata> listSecrets(ListSecretsRequest request)

Lists the secret keys that are stored at this scope. This is a metadata-only operation; secret data cannot be retrieved using this API. Users need the READ permission to make this call.

Example response:

.. code::

{ "secrets": [ { "key": "my-string-key"", "last_updated_timestamp": "1520467595000" }, { "key": "my-byte-key", "last_updated_timestamp": "1520467595000" }, ] }

The lastUpdatedTimestamp returned is in milliseconds since epoch.

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope exists. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call.

putAcl

public void putAcl(PutAcl request)

Creates or overwrites the ACL associated with the given principal (user or group) on the specified scope point. In general, a user or group will use the most powerful permission available to them, and permissions are ordered as follows:

* ``MANAGE`` - Allowed to change ACLs, and read and write to this secret scope. * ``WRITE`` - Allowed to read and write to this secret scope. * ``READ`` - Allowed to read this secret scope and list what secrets are available.

Note that in general, secret values can only be read from within a command on a cluster (for example, through a notebook). There is no API to read the actual secret value material outside of a cluster. However, the user's permission will be applied based on who is executing the command, and they must have at least READ permission.

Users must have the ``MANAGE`` permission to invoke this API.

Example request:

.. code::

{ "scope": "my-secret-scope", "principal": "data-scientists", "permission": "READ" }

The principal is a user or group name corresponding to an existing Databricks principal to be granted or revoked access.

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope exists. Throws ``RESOURCE_ALREADY_EXISTS`` if a permission for the principal already exists. Throws ``INVALID_PARAMETER_VALUE`` if the permission or principal is invalid. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call.

putSecret

public void putSecret(PutSecret request)

Inserts a secret under the provided scope with the given name. If a secret already exists with the same name, this command overwrites the existing secret's value. The server encrypts the secret using the secret scope's encryption settings before storing it. You must have ``WRITE`` or ``MANAGE`` permission on the secret scope.

The secret key must consist of alphanumeric characters, dashes, underscores, and periods, and cannot exceed 128 characters. The maximum allowed secret value size is 128 KB. The maximum number of secrets in a given scope is 1000.

Example request:

.. code::

{ "scope": "my-databricks-scope", "key": "my-string-key", "string_value": "foobar" }

The input fields "string_value" or "bytes_value" specify the type of the secret, which will determine the value returned when the secret value is requested. Exactly one must be specified.

Throws ``RESOURCE_DOES_NOT_EXIST`` if no such secret scope exists. Throws ``RESOURCE_LIMIT_EXCEEDED`` if maximum number of secrets in scope is exceeded. Throws ``INVALID_PARAMETER_VALUE`` if the request parameters are invalid. Throws ``PERMISSION_DENIED`` if the user does not have permission to make this API call. Throws ``MALFORMED_REQUEST`` if request is incorrectly formatted or conflicting. Throws ``BAD_REQUEST`` if request is made against Azure KeyVault backed scope.

impl

public SecretsService impl()