Creación de roles de Postgres

Al crear un proyecto, Lakebase crea varios roles de Postgres en el proyecto:

• Un rol de Postgres para la identidad de Azure Databricks del propietario del proyecto (por ejemplo, user@databricks.com), que posee la base de datos predeterminada databricks_postgres
• Un databricks_superuser rol administrativo

Ambos roles están visibles en la pestaña Roles y bases de datos cuando abra el proyecto por primera vez.

La databricks_postgres base de datos se crea para que pueda conectarse y probar Lakebase inmediatamente después de la creación del proyecto.

También se crean varios roles administrados por el sistema. Estos son roles internos que usan los servicios de Azure Databricks para las operaciones de administración, supervisión y datos.

Consulte Roles creados previamente y Roles del sistema.

Creación de roles de Postgres

Lakebase admite dos tipos de roles de Postgres para el acceso a bases de datos:

• Roles de OAuth para identidades de Azure Databricks: Cree estos mediante la interfaz de usuario de Lakebase, la databricks_auth extensión con SQL o el SDK de Python y la API REST. Permite que las identidades de Azure Databricks (usuarios, entidades de servicio y grupos) se conecten mediante tokens de OAuth.
• Roles de contraseña de Postgres nativos: Cree estos mediante la interfaz de usuario de Lakebase, SQL o el SDK de Python y la API REST. Use cualquier nombre de rol válido con autenticación de contraseña.

Para obtener instrucciones sobre cómo elegir el tipo de rol que se va a usar, consulte Introducción a la autenticación. Cada uno está diseñado para diferentes casos de uso.

Creación de un rol de OAuth para identidades de Azure Databricks

Para permitir que las identidades de Azure Databricks (usuarios, entidades de servicio o grupos) se conecten mediante tokens de OAuth, cree un rol de OAuth mediante la interfaz de usuario de Lakebase, la databricks_auth extensión con SQL o la API REST.

Para obtener instrucciones detalladas sobre cómo obtener tokens de OAuth, consulte Obtención de un token de OAuth en un flujo de usuario a máquina y Obtención de un token de OAuth en un flujo de máquina a máquina.

Interfaz de usuario

1. En la pestaña Roles y bases de datos>Agregar rol>OAuth , seleccione el usuario, la entidad de servicio o el grupo para conceder acceso a la base de datos.
2. Después de crear el rol, conceda los privilegios de base de datos adecuados. Obtenga información sobre cómo: Administrar permisos

SQL

Requisitos previos:

• Debe tener los permisos CREATE y CREATE ROLE en la base de datos.
• Debe autenticarse como una identidad de Azure Databricks con un token de OAuth válido.
• Las sesiones autenticadas de Native Postgres no pueden crear roles de OAuth

1. Cree la databricks_auth extensión. Cada base de datos de Postgres debe tener su propia extensión.

   CREATE EXTENSION IF NOT EXISTS databricks_auth;
   

2. Use la databricks_create_role función para crear un rol de Postgres para la identidad de Azure Databricks:

   SELECT databricks_create_role('identity_name', 'identity_type');
   

   Para un usuario de Azure Databricks:

   SELECT databricks_create_role('myuser@databricks.com', 'USER');
   

   Para un principal de servicio de Azure Databricks:

   SELECT databricks_create_role('8c01cfb1-62c9-4a09-88a8-e195f4b01b08', 'SERVICE_PRINCIPAL');
   

   Para un grupo de Azure Databricks:

   SELECT databricks_create_role('My Group Name', 'GROUP');
   

   El nombre del grupo distingue entre mayúsculas y minúsculas y debe coincidir exactamente con la forma en que aparece en el área de trabajo de Azure Databricks. Al crear un rol de Postgres para un grupo, cualquier miembro directo o indirecto (usuario o entidad de servicio) de ese grupo de Databricks puede autenticarse en Postgres como rol de grupo mediante su token de OAuth individual. Este modelo de permisos de nivel de grupo le permite administrar permisos en Postgres en lugar de mantener permisos para usuarios individuales.

3. Conceda permisos de base de datos al rol recién creado.

La databricks_create_role() función crea un rol de Postgres con solo LOGIN permiso. Después de crear el rol, debe conceder los privilegios y permisos de base de datos adecuados en las bases de datos, esquemas o tablas específicos a las que el usuario necesita acceder. Obtenga información sobre cómo: Administrar permisos

SDK de Python

Establezca en identity_type, USER, SERVICE_PRINCIPAL o GROUP. Establezca postgres_role en la dirección de correo electrónico de la identidad, el ID de la aplicación (UUID) o el nombre visible del grupo, respectivamente. Este valor se convierte en el nombre del rol Postgres y es lo que se usa en las cadenas de conexión y en las instrucciones GRANT.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleIdentityType, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            identity_type=RoleIdentityType.USER,
            postgres_role="user@example.com"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

Después de crear el rol, conceda los privilegios de base de datos adecuados. Obtenga información sobre cómo: Administrar permisos

CLI

Establezca en identity_type, USER, SERVICE_PRINCIPAL o GROUP. Establezca postgres_role en la dirección de correo electrónico de la identidad, el ID de la aplicación (UUID) o el nombre visible del grupo, respectivamente. Este valor se convierte en el nombre del rol Postgres y es lo que se usa en las cadenas de conexión y en las instrucciones GRANT.

Para un usuario de Azure Databricks:

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

Para un principal de servicio de Azure Databricks:

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "8c01cfb1-62c9-4a09-88a8-e195f4b01b08"}}'

Para un grupo de Azure Databricks:

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-group-role \
  --json '{"spec": {"identity_type": "GROUP", "postgres_role": "My Group Name"}}'

El comando espera a que se complete la operación y devuelva el rol creado. Use --no-wait para devolver inmediatamente y sondear por separado con databricks postgres get-operation.

Después de crear el rol, conceda los privilegios de base de datos adecuados. Obtenga información sobre cómo: Administrar permisos

curl

Establezca en identity_type, USER, SERVICE_PRINCIPAL o GROUP. Establezca postgres_role en la dirección de correo electrónico de la identidad, el ID de la aplicación (UUID) o el nombre visible del grupo, respectivamente. Este valor se convierte en el nombre del rol Postgres y es lo que se usa en las cadenas de conexión y en las instrucciones GRANT.

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "identity_type": "USER",
      "postgres_role": "user@example.com"
    }
  }' | jq

El punto de conexión devuelve una operación de ejecución prolongada. Realice el sondeo hasta que done sea true, y a continuación, use el campo de rol name para las llamadas API posteriores. Consulte Operaciones de ejecución prolongada.

Después de crear el rol, conceda los privilegios de base de datos adecuados. Obtenga información sobre cómo: Administrar permisos

Autenticación basada en grupos

Al crear un rol de Postgres para un grupo de Azure Databricks, se habilita la autenticación basada en grupos. Esto permite que cualquier miembro del grupo de Azure Databricks se autentique en Postgres mediante el rol del grupo, lo que simplifica la administración de permisos.

Funcionamiento:

1. Cree un rol de Postgres para un grupo de Azure Databricks.
2. Conceda permisos de base de datos al rol de grupo en Postgres. Consulte Administración de permisos.
3. Cualquier miembro directo o indirecto (usuario o entidad de servicio) del grupo de Azure Databricks puede conectarse a Postgres mediante su token de OAuth individual.
4. Al conectarse, el miembro se autentica como el rol de grupo y hereda todos los permisos concedidos a ese rol.

Flujo de autenticación:

Cuando se conecta un miembro del grupo, especifican el nombre del rol postgres del grupo como nombre de usuario y su propio token de OAuth como contraseña:

export PGPASSWORD='<OAuth token of a group member>'
export GROUP_ROLE_NAME='<pg-case-sensitive-group-role-name>'

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUP_ROLE_NAME

Consideraciones importantes:

• Validación de pertenencia a grupos: La pertenencia a grupos solo se valida en el momento de la autenticación. Si se quita un miembro del grupo de Azure Databricks después de establecer una conexión, la conexión permanece activa. Se rechazan los nuevos intentos de conexión de los miembros eliminados.
• Ámbito del área de trabajo: Solo se admiten los grupos asignados al mismo área de trabajo de Azure Databricks que el proyecto para la autenticación basada en grupos. Para obtener información sobre cómo asignar grupos a un área de trabajo, consulte Administración de grupos.
• Distinción entre mayúsculas y minúsculas: El nombre de grupo usado en databricks_create_role() debe coincidir exactamente con el nombre del grupo tal como aparece en el área de trabajo de Azure Databricks, incluido el caso.
• Administración de permisos: La administración de permisos en el nivel de grupo en Postgres es más eficaz que administrar permisos de usuario individuales. Al conceder permisos al rol de grupo, todos los miembros del grupo actuales y futuros heredan esos permisos automáticamente.
• Nombre de identidad: Si el nombre para mostrar de un usuario o un grupo cambia en Azure Databricks, se interrumpe la autenticación y las concesiones de base de datos existentes. Quite el rol anterior, cree uno nuevo con el nombre actualizado y actualice las cadenas de conexión y las concesiones.

Creación de un rol nativo de contraseña de Postgres

Las conexiones de contraseña se pueden deshabilitar en el nivel de proyecto o proceso. Consulte Bloquear conexiones de contraseña.

Interfaz de usuario

1. En la pestaña Roles y bases de datos> Agregarcontraseña de>, escriba un nombre de rol y, opcionalmente, conceda databricks_superuser o atributos del sistema (CREATEDB, CREATEROLE, BYPASSRLS).
2. Copie la contraseña generada y proporciónela de forma segura al usuario. No se vuelve a mostrar.

SQL

CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';

La contraseña debe tener al menos 12 caracteres con una combinación de caracteres en minúsculas, mayúsculas, números y símbolos. Las contraseñas definidas por el usuario se validan en tiempo de creación para comprobar la entropía de 60 bits.

SDK de Python

Omitir identity_type para crear una función de contraseña. La API devuelve una contraseña generada en la respuesta.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            postgres_role="my-app-role"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

CLI

Omitir identity_type para crear una función de contraseña. La API genera una contraseña y la devuelve en la respuesta.

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

El comando espera a que se complete la operación. La respuesta incluye la contraseña generada: guárdela de forma segura, ya que no se muestra de nuevo.

curl

Omitir identity_type para crear una función de contraseña. El punto de conexión devuelve una operación de ejecución prolongada. Consulte hasta que done sea true.

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "postgres_role": "my-app-role"
    }
  }' | jq

Visualización de roles de Postgres

Interfaz de usuario

Para ver todos los roles de Postgres del proyecto, vaya a la pestaña Roles y bases de datos de la rama en la aplicación Lakebase. Se muestran todos los roles creados en la rama, a excepción de los roles del sistema. La columna Tipo de autenticación indica si cada rol usa autenticación de OAuth o Contraseña.

PostgreSQL

Ver todos los roles con \du el comando :

Puede ver todos los roles de Postgres, incluidos los roles del sistema, mediante el \du metacomando desde cualquier cliente de Postgres (como psql) o el editor sql de Lakebase:

\du
                                      List of roles
          Role name          |                         Attributes
-----------------------------+------------------------------------------------------------
 cloud_admin                 | Superuser, Create role, Create DB, Replication, Bypass RLS
 my.user@databricks.com      | Create role, Create DB, Bypass RLS
 databricks_control_plane    | Superuser
 databricks_gateway          |
 databricks_monitor          |
 databricks_reader_12345     | Create role, Create DB, Replication, Bypass RLS
 databricks_replicator       | Replication
 databricks_superuser        | Create role, Create DB, Cannot login, Bypass RLS
 databricks_writer_12345     | Create role, Create DB, Replication, Bypass RLS

SDK de Python

Enumerar todos los roles:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

roles = w.postgres.list_roles(parent="projects/my-project/branches/production")
for role in roles:
    print(f"{role.status.postgres_role} ({role.status.identity_type or 'PASSWORD'}): {role.name}")

Obtener un rol específico:

role = w.postgres.get_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
print(role)

CLI

Enumerar todos los roles:

databricks postgres list-roles projects/my-project/branches/production

Obtener un rol específico:

databricks postgres get-role projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

La salida incluye el name campo (por ejemplo, rol-xxxx-xxxxxxxxxx) necesario para las llamadas de actualización y eliminación.

curl

Enumerar todos los roles:

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Obtener un rol específico:

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

La respuesta incluye el name campo (por ejemplo, rol-xxxx-xxxxxxxxxx) necesario para las llamadas de actualización y eliminación.

Actualización de un rol

Para actualizar los atributos de un rol en la interfaz de usuario, seleccione Editar rol en el menú rol de la pestaña Roles y bases de datos .

Use la API o CLI para actualizar los roles del sistema o atributos de un rol. Solo cambian los campos especificados en la máscara de actualización.

CLI

Actualice un rol mediante el patrón de máscara de actualización. La máscara de actualización es el segundo argumento posicional después del nombre del recurso.

Al actualizar spec.attributes, debe proporcionar los tres campos de atributo (createdb, createrole, bypassrls), la API reemplaza al objeto de atributos completo:

databricks postgres update-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  "spec.attributes" \
  --json '{
    "spec": {
      "attributes": {"createdb": true, "createrole": false, "bypassrls": false}
    }
  }'

Para actualizar también los roles de pertenencia, agregue spec.membership_roles a la máscara de actualización:

databricks postgres update-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  "spec.membership_roles" \
  --json '{"spec": {"membership_roles": ["DATABRICKS_SUPERUSER"]}}'

Para quitar databricks_superuser, pase una matriz vacía: "membership_roles": [].

curl

curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx?update_mask=spec.membership_roles%2Cspec.attributes.createdb" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx",
    "spec": {
      "membership_roles": ["DATABRICKS_SUPERUSER"],
      "attributes": { "createdb": true }
    }
  }' | jq

Para quitar databricks_superuser, pase una matriz vacía: "membership_roles": [].

Quitar un rol de Postgres

Puede eliminar roles basados en identidades de Azure Databricks y roles de contraseña integrados de Postgres.

Interfaz de usuario

La eliminación de un rol es una acción permanente que no se puede deshacer. Para eliminar un rol que posee una base de datos, debe especificar el rol al que se reasignarán los objetos de los que es propietario. De lo contrario, la base de datos debe eliminarse manualmente antes de eliminar el rol que posee la base de datos.

Para eliminar cualquier rol de Postgres mediante la interfaz de usuario:

1. Vaya a la pestaña Roles y bases de datos de la rama en la aplicación Lakebase.
2. Seleccione Eliminar rol en el menú rol y confirme la eliminación.

PostgreSQL

Puede quitar cualquier rol de Postgres mediante comandos estándar de Postgres. Para más información, consulte la documentación de PostgreSQL sobre la eliminación de roles.

Quitar un rol:

DROP ROLE role_name;

Después de quitar un rol basado en identidad de Azure Databricks, esa identidad ya no se puede autenticar en Postgres mediante tokens de OAuth hasta que se crea un nuevo rol.

CLI

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

Si el rol posee objetos de base de datos, use --reassign-owned-to para transferir la propiedad a otro rol antes de la eliminación:

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  --reassign-owned-to projects/my-project/branches/production/roles/rol-yyyy-yyyyyyyyyy

SDK de Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

operation = w.postgres.delete_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
operation.wait()

curl

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Roles creados previamente

Una vez creado un proyecto, Azure Databricks crea automáticamente roles de Postgres para la administración de proyectos y la introducción.

Más información sobre las funcionalidades y privilegios específicos de estos roles: funcionalidades de rol creadas previamente

Roles del sistema creados por Azure Databricks

Azure Databricks crea los siguientes roles de sistema necesarios para los servicios internos. Puede ver estos roles emitiendo un comando desde \du, desde psql o el Editor de SQL de Lakebase.

Para obtener información sobre cómo funcionan los roles, los privilegios y las pertenencias a roles en Postgres, use los siguientes recursos en la documentación de Postgres:

• Roles de base de datos
• Privilegios

Pasos siguientes

• Administración de permisos
• Conexión al proyecto
• Información sobre la autenticación