Secrets API

Secrets API permite administrar secretos, ámbitos secretos y permisos de acceso. Para administrar secretos, debe:

  1. Crear un ámbito de secreto.
  2. Agregue los secretos al ámbito.
  3. Si tiene el plan Azure Databricks Premium, asigne el control de acceso al ámbito secreto.

Para más información sobre la creación y administración de secretos, consulte Administración de secretos. Puede acceder a los secretos y hacer referencia a estos en cuadernos y trabajos mediante la utilidad Secrets (dbutils.secrets).

Importante

Para acceder a las API REST de Databricks, es preciso autenticarse. Para usar secrets API con Azure Key Vault secretos, debe autenticarse mediante un token Azure Active Directory datos.

Creación de un ámbito de secreto

punto de conexión Método HTTP
2.0/secrets/scopes/create POST

Puede:

  • Cree un ámbito Azure Key Vault en el que los secretos se almacenan en el almacenamiento administrado por Azure y se cifran con una clave de cifrado específica basada en la nube.
  • Cree un ámbito de secretos basado en Databricks en el que los secretos se almacenan en el almacenamiento administrado por Databricks y se cifran con una clave de cifrado específica basada en la nube.

Creación de un ámbito Azure Key Vault con copia de seguridad

Nombre del ámbito:

  • Debe ser único dentro de un área de trabajo.
  • Debe constar de caracteres alfanuméricos, guiones, caracteres de subrayado y puntos, y no puede superar los 128 caracteres.

Los nombres se consideran no confidenciales y todos los usuarios del área de trabajo pueden leer los nombres. De forma predeterminada, un área de trabajo está limitada a un máximo de 100 ámbitos secretos. Para aumentar este máximo para un área de trabajo, póngase en contacto con su representante de Databricks.

Solicitud de ejemplo:

{
  "scope": "my-simple-azure-keyvault-scope",
  "scope_backend_type": "AZURE_KEYVAULT",
  "backend_azure_keyvault":
  {
    "resource_id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azure-rg/providers/Microsoft.KeyVault/vaults/my-azure-kv",
    "dns_name": "https://my-azure-kv.vault.azure.net/"
  },
  "initial_manage_principal": "users"
}

Si se especifica , la ACL inicial aplicada al ámbito se aplica a la entidad de seguridad proporcionada (usuario o initial_manage_principal grupo) con MANAGE permisos. La única entidad de seguridad admitida para esta opción es el grupo users , que contiene todos los usuarios del área de trabajo. Si no se especifica, la ACL inicial con permiso aplicado al ámbito se asigna a la identidad de usuario del emisor de la solicitud initial_manage_principal MANAGE de API.

Se produce RESOURCE_ALREADY_EXISTS si ya existe un ámbito con el nombre especificado. Se produce si se supera el número máximo de ámbitos del RESOURCE_LIMIT_EXCEEDED área de trabajo. Se produce INVALID_PARAMETER_VALUE si el nombre del ámbito no es válido.

Creación de un ámbito de secreto compatible con Databricks

Nombre del ámbito:

  • Debe ser único dentro de un área de trabajo.
  • Debe constar de caracteres alfanuméricos, guiones, caracteres de subrayado y puntos, y no puede superar los 128 caracteres.

Los nombres se consideran no confidenciales y todos los usuarios del área de trabajo pueden leer los nombres. Un área de trabajo está limitada a un máximo de 100 ámbitos secretos.

Solicitud de ejemplo:

{
  "scope": "my-simple-databricks-scope",
  "initial_manage_principal": "users"
}

Si se especifica , la ACL inicial aplicada al ámbito se aplica a la entidad de seguridad proporcionada (usuario o initial_manage_principal grupo) con MANAGE permisos. La única entidad de seguridad admitida para esta opción es el grupo users , que contiene todos los usuarios del área de trabajo. Si no se especifica, la ACL inicial con permiso aplicado al ámbito se asigna a la identidad de usuario del emisor de la solicitud initial_manage_principal MANAGE de API.

Se produce RESOURCE_ALREADY_EXISTS si ya existe un ámbito con el nombre especificado. Se produce si se supera el número máximo de ámbitos del RESOURCE_LIMIT_EXCEEDED área de trabajo. Se produce INVALID_PARAMETER_VALUE si el nombre del ámbito no es válido.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre de ámbito solicitado por el usuario. Los nombres de ámbito son únicos. Este campo es obligatorio.
initial_manage_principal STRING La entidad de seguridad a la que se concedió MANAGE permiso inicialmente para el ámbito creado.

Eliminación del ámbito del secreto

punto de conexión Método HTTP
2.0/secrets/scopes/delete POST

Elimina un ámbito de secreto.

Solicitud de ejemplo:

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

Produce si RESOURCE_DOES_NOT_EXIST el ámbito no existe. Se produce PERMISSION_DENIED si el usuario no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito que se eliminará. Este campo es obligatorio.

Enumeración de ámbitos de secretos

punto de conexión Método HTTP
2.0/secrets/scopes/list GET

Enumera todos los ámbitos de secreto disponibles en el área de trabajo.

Respuesta de ejemplo:

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

Se produce PERMISSION_DENIED si no tiene permiso para realizar esta llamada API.

Estructura de respuesta

Nombre del campo Tipo Descripción
ámbitos Una matriz de SecretScope Ámbitos de secreto disponibles.

Put secret

El método para crear o modificar un secreto depende del tipo de back-end de ámbito. Para crear o modificar un secreto en un ámbito Azure Key Vault, use la API REST SetSecret de Azure. Para crear o modificar un secreto desde un ámbito con respaldo de Databricks, use el siguiente punto de conexión:

punto de conexión Método HTTP
2.0/secrets/put POST

Inserte un secreto en el ámbito proporcionado con el nombre especificado. Si ya existe un secreto con el mismo nombre, este comando sobrescribe el valor del secreto existente. El servidor cifra el secreto mediante la configuración de cifrado del ámbito del secreto antes de almacenarlo. Debe tener el WRITE permiso o en el ámbito del MANAGE secreto.

La clave secreta debe constar de caracteres alfanuméricos, guiones, caracteres de subrayado y puntos, y no puede superar los 128 caracteres. El tamaño máximo permitido del valor secreto es de 128 KB. El número máximo de secretos en un ámbito determinado es 1000.

Solo puede leer un valor secreto desde dentro de un comando en un clúster (por ejemplo, a través de un cuaderno); no hay ninguna API para leer un valor secreto fuera de un clúster. El permiso aplicado se basa en quién invoca el comando y debe tener al menos READ permiso.

Solicitud de ejemplo:

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

Los campos de entrada "string_value" o "bytes_value" especifican el tipo del secreto, que determinará el valor devuelto cuando se solicite el valor del secreto. Se debe especificar exactamente uno.

Se produce RESOURCE_DOES_NOT_EXIST si no existe ese ámbito de secreto. Se produce RESOURCE_LIMIT_EXCEEDED si se supera el número máximo de secretos en el ámbito. Se produce INVALID_PARAMETER_VALUE si el nombre de clave o la longitud del valor no son válidos. Se produce PERMISSION_DENIED si el usuario no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
string_value O bytes_value STRING O BYTES Si string_value, si se especifica, el valor se almacenará en formato UTF-8 (MB4).

Si bytes_value, si se especifica, el valor se almacenará como bytes.
scope STRING Nombre del ámbito al que se asociará el secreto. Este campo es obligatorio.
key STRING Nombre único para identificar el secreto. Este campo es obligatorio.

Eliminar secreto

El método para eliminar un secreto depende del tipo de back-end de ámbito. Para eliminar un secreto de un ámbito con el respaldo de Azure Key Vault, use la API REST SetSecret de Azure. Para eliminar un secreto de un ámbito con respaldo de Databricks, use el siguiente punto de conexión:

punto de conexión Método HTTP
2.0/secrets/delete POST

Elimine el secreto almacenado en este ámbito de secreto. Debe tener el WRITE permiso o en el ámbito del MANAGE secreto.

Solicitud de ejemplo:

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

Se produce RESOURCE_DOES_NOT_EXIST si no existe ese ámbito de secreto o secreto. Se produce PERMISSION_DENIED si no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito que contiene el secreto que se eliminará. Este campo es obligatorio.
key STRING Nombre del secreto que se eliminará. Este campo es obligatorio.

Enumeración de secretos

punto de conexión Método HTTP
2.0/secrets/list GET

Enumera las claves secretas que se almacenan en este ámbito. Se trata de una operación de solo metadatos; no se pueden recuperar datos secretos mediante esta API. Debe tener permiso READ para realizar esta llamada.

Respuesta de ejemplo:

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

El last_updated_timestamp devuelto es en milisegundos desde la época.

Se produce RESOURCE_DOES_NOT_EXIST si no existe ese ámbito de secreto. Se produce PERMISSION_DENIED si no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito cuyos secretos desea enumerar. Este campo es obligatorio.

Estructura de respuesta

Nombre del campo Tipo Descripción
secrets Matriz de SecretMetadata Información de metadatos de todos los secretos incluidos en el ámbito especificado.

Put secret ACL

punto de conexión Método HTTP
2.0/secrets/acls/put POST

Cree o sobrescriba la ACL asociada a la entidad de seguridad especificada (usuario o grupo) en el punto de ámbito especificado. En general, un usuario o grupo usará el permiso más eficaz disponible para ellos y los permisos se ordenan de la manera siguiente:

  • MANAGE - Se permite cambiar las ACL y leer y escribir en este ámbito de secreto.
  • WRITE - Se permite leer y escribir en este ámbito de secreto.
  • READ - Se permite leer este ámbito de secreto y enumerar qué secretos están disponibles.

Debe tener el permiso MANAGE para invocar esta API.

Solicitud de ejemplo:

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

La entidad de seguridad es un nombre de usuario o grupo que corresponde a una entidad Azure Databricks entidad de seguridad a la que se va a conceder o revocar el acceso.

Se produce RESOURCE_DOES_NOT_EXIST si no existe ese ámbito de secreto. Se produce RESOURCE_ALREADY_EXISTS si ya existe un permiso para la entidad de seguridad. Se produce INVALID_PARAMETER_VALUE si el permiso no es válido. Se produce PERMISSION_DENIED si no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito al que se aplicarán los permisos. Este campo es obligatorio.
entidad de seguridad STRING Entidad de seguridad a la que se aplica el permiso. Este campo es obligatorio.
permiso AclPermission Nivel de permiso aplicado a la entidad de seguridad. Este campo es obligatorio.

Eliminación de acl secreta

punto de conexión Método HTTP
2.0/secrets/acls/delete POST

Elimine la ACL dada en el ámbito especificado.

Debe tener el permiso MANAGE para invocar esta API.

Solicitud de ejemplo:

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

Se produce RESOURCE_DOES_NOT_EXIST si no existe ningún ámbito de secreto, entidad de seguridad o ACL. Se produce PERMISSION_DENIED si no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito del que se quitarán los permisos. Este campo es obligatorio.
entidad de seguridad STRING Entidad de seguridad de la que se quitará una ACL existente. Este campo es obligatorio.

Obtener acl de secreto

punto de conexión Método HTTP
2.0/secrets/acls/get GET

Describa los detalles sobre la ACL dada, como el grupo y el permiso.

Debe tener el permiso MANAGE para invocar esta API.

Respuesta de ejemplo:

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

Produce si RESOURCE_DOES_NOT_EXIST no existe este ámbito de secreto. Inicia si PERMISSION_DENIED no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito del que se va a capturar información de ACL. Este campo es obligatorio.
entidad de seguridad STRING Entidad de seguridad para la que se va a capturar información de ACL. Este campo es obligatorio.

Estructura de respuesta

Nombre del campo Tipo Descripción
entidad de seguridad STRING Entidad de seguridad a la que se aplica el permiso. Este campo es obligatorio.
permiso AclPermission Nivel de permiso aplicado a la entidad de seguridad. Este campo es obligatorio.

Enumeración de acl secretas

punto de conexión Método HTTP
2.0/secrets/acls/list GET

Enumerar las ACL establecidas en el ámbito especificado.

Debe tener el permiso MANAGE para invocar esta API.

Respuesta de ejemplo:

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

Produce si RESOURCE_DOES_NOT_EXIST no existe este ámbito de secreto. Inicia si PERMISSION_DENIED no tiene permiso para realizar esta llamada API.

Estructura de solicitudes

Nombre del campo Tipo Descripción
scope STRING Nombre del ámbito del que se va a capturar información de ACL. Este campo es obligatorio.

Estructura de respuesta

Nombre del campo Tipo Descripción
items Matriz de AclItem Regla de ACL asociada aplicada a las entidades de seguridad en el ámbito especificado.

Estructuras de datos

En esta sección:

AclItem

Elemento que representa una regla de ACL aplicada a la entidad de seguridad determinada (usuario o grupo) en el punto de ámbito asociado.

Nombre del campo Tipo Descripción
entidad de seguridad STRING Entidad de seguridad a la que se aplica el permiso. Este campo es obligatorio.
permiso AclPermission Nivel de permiso aplicado a la entidad de seguridad. Este campo es obligatorio.

SecretMetadata

Metadatos sobre un secreto. Se devuelve al enumerar secretos. No contiene el valor del secreto real.

Nombre del campo Tipo Descripción
key STRING Nombre único para identificar el secreto.
last_updated_timestamp INT64 Marca de tiempo actualizada por última vez (en milisegundos) para el secreto.

SecretScope

Un recurso organizativo para almacenar secretos. Los ámbitos de secreto pueden ser tipos diferentes y las ACL se pueden aplicar para controlar los permisos de todos los secretos dentro de un ámbito.

Nombre del campo Tipo Descripción
name STRING Nombre único para identificar el ámbito del secreto.
backend_type ScopeBackendType Tipo de back-end de ámbito secreto.

AclPermission

Los niveles de permiso de ACL para las ACL secretas aplicadas a los ámbitos secretos.

Permiso Descripción
READ Se permite realizar operaciones de lectura (get, list) en secretos en este ámbito.
WRITE Se permite leer y escribir secretos en este ámbito secreto.
ADMINISTRAR Se permite leer y escribir ACL y leer y escribir secretos en este ámbito secreto.

ScopeBackendType

Tipo de back-end de ámbito secreto.

Tipo Descripción
AZURE_KEYVAULT Ámbito de secreto en el que los secretos se almacenan en un Azure Key Vault.
DATABRICKS Ámbito secreto en el que los secretos se almacenan en el almacenamiento administrado de Databricks y se cifran con una clave de cifrado específica basada en la nube.