Gerenciar atributos de identidade com o SCIM da conta

A API 2.1 do System for Cross-domain Identity Management (SCIM) da conta provisiona os nove atributos de identidade para usuários da conta Databricks, seja por meio de um conector de provisionamento ou diretamente.

info

Beta

Esse recurso está em Beta. Os administradores da conta podem gerenciar o acesso a esse recurso na página Prévias do console da conta. Consulte Gerenciar prévias em nível de conta.

O Databricks recomenda a gestão automática de identidades em vez do SCIM para gerenciar atributos de identidade. Para obter mais informações, consulte Gestão automática de identidades.

Pré-requisitos

Você deve ser um administrador da account.
Configure o provisionamento SCIM no nível da conta para sua conta. Consulte Sincronizar usuários e grupos com sua conta Databricks.
Os atributos de identidade são gerenciados no account SCIM 2.1 , em https://accounts.cloud.databricks.com/api/2.1/accounts/<account-id>/scim/v2/. Esta é a única superfície que faz a leitura e a gravação do conjunto completo de atributos.
Você não precisa habilitar a prévia do recurso Identity Attribute Control List para gravar atributos por meio do SCIM. Se a prévia estiver habilitada, certifique-se de que os atributos que você pretende enviar estejam na lista de controle de atributos da sua conta, ou a gravação será rejeitada. Consulte Identity Attribute Control List.

Configurar um conector SCIM

Os atributos de identidade chegam ao Databricks a partir do seu provedor de identidade por meio de um conector de provisionamento SCIM que os envia (push), ou por meio do gerenciamento automático de identidade, que os recupera (pull). Esta seção aborda a rota do conector para o Okta e o Microsoft Entra ID.

Em ambos os provedores, o trabalho é o mesmo em linhas gerais: estenda o esquema de saída do provedor para que ele saiba que os nove atributos do Databricks existem, mapeie cada um para um atributo de origem no perfil do usuário e, em seguida, sincronize. Você pode atualizar seu aplicativo de conector SCIM existente para fazer isso; não é necessário criar um novo aplicativo em seu provedor de identidade.

Okta

Crie primeiro o aplicativo de conector SCIM do Databricks, seguindo a configuração padrão do Okta para o Databricks. Em seguida, estenda seu esquema de saída.

Acesse Applications > seu aplicativo Databricks > Provisionamento > To App , depois abra Go to Profile Editor .
Escolha Adicionar atributo e adicione os nove atributos na tabela a seguir. Todos os nove são do tipo de dados string .
Para Namespace externo , use urn:ietf:params:scim:schemas:core:2.0:User para os primeiros cinco atributos (Título até País de trabalho) e urn:ietf:params:scim:schemas:extension:enterprise:2.0:User para os últimos quatro (Centro de custo até Departamento).
Retorne à tab Provisionamento e edite a seção Mapeamentos para mapear cada atributo do Databricks ao atributo de perfil de usuário do Okta do qual ele deve ser extraído.

O External name e o External namespace são o que o Okta envia na rede, portanto, eles devem corresponder exatamente aos caminhos SCIM.

Nome de exibição	Nome da variável	Nome externo
Título	`title`	`title`
Tipo de usuário	`userType`	`userType`
Localidade de trabalho	`workLocality`	`addresses.^[type=='work'].locality`
Região de trabalho	`workRegion`	`addresses.^[type=='work'].region`
País de trabalho	`workCountry`	`addresses.^[type=='work'].country`
Centro de custo	`costCenter`	`costCenter`
Organização	`organization`	`organization`
Divisão	`division`	`division`
Departamento	`department`	`department`

Nome de exibição	Nome da variável	Nome externo
Título	`title`	`title`
Tipo de usuário	`userType`	`userType`
Localidade de trabalho	`workLocality`	`addresses.^[type=='work'].locality`
Região de trabalho	`workRegion`	`addresses.^[type=='work'].region`
País de trabalho	`workCountry`	`addresses.^[type=='work'].country`
Centro de custo	`costCenter`	`costCenter`
Organização	`organization`	`organization`
Divisão	`division`	`division`
Departamento	`department`	`department`

Para testar o resultado, crie um usuário em Diretório > Pessoas > Adicionar pessoa , defina os atributos mapeados em seu perfil e, em seguida, atribua-os ao aplicativo na tab Atribuições . Abra a tab provisionamento e escolha Force Sync se precisar que os atributos sejam sincronizados imediatamente. Os atributos aparecem no usuário no console da conta do Databricks em cerca de cinco minutos.

O conector Okta se comporta da seguinte maneira:

Os valores de atributo diferenciam maiúsculas de minúsculas e são armazenados exatamente como enviados.
Os símbolos _, -, . e espaços são sincronizados sem problemas.
Atributos com valores de matriz não são compatíveis. O mapeamento de um produz um erro no Okta e o valor no Databricks permanece inalterado. Isso se aplica até mesmo a uma matriz de elemento único.

Microsoft Entra ID

Crie o aplicativo de provisionamento SCIM no Microsoft Entra ID seguindo a configuração padrão do Microsoft Entra ID para o Databricks.

O editor de esquema não é exposto por default. Acrescente ?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true ao URL do portal e mantenha-o definido durante toda a sessão de configuração. Sem isso, a opção Editar esquema não aparecerá.

Abra seu aplicativo e vá para Provisionamento > Mapeamento de atributos .
Em Opções avançadas , escolha Editar atributos de usuário do Databricks .
Adicione os nove atributos a seguir, todos do tipo String :
- title
- userType
- addresses[type eq "work"].locality
- addresses[type eq "work"].region
- addresses[type eq "work"].country
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
Retorne à tela de mapeamento de atributos e escolha Adicionar Mapeamento de Atributo para cada atributo, usando um tipo de mapeamento Direto e os atributos de origem na tabela a seguir.

O Microsoft Entra ID não possui um campo de origem nativo para centro de custo ou divisão, portanto, deixe esses dois não mapeados, a menos que você tenha um atributo de extensão personalizado ou expressão adequada para vinculá-los.

Destino Databricks	Atributo de origem do Microsoft Entra ID
`title`	`jobTitle`
`userType`	`employeeType`
`addresses[type eq "work"].locality`	`city`
`addresses[type eq "work"].region`	`state`
`addresses[type eq "work"].country`	`country`
`...:enterprise:2.0:User:organization`	`companyName`
`...:enterprise:2.0:User:department`	`department`
`...:enterprise:2.0:User:costCenter`	não mapeado
`...:enterprise:2.0:User:division`	não mapeado

Destino Databricks	Atributo de origem do Microsoft Entra ID
`title`	`jobTitle`
`userType`	`employeeType`
`addresses[type eq "work"].locality`	`city`
`addresses[type eq "work"].region`	`state`
`addresses[type eq "work"].country`	`country`
`...:enterprise:2.0:User:organization`	`companyName`
`...:enterprise:2.0:User:department`	`department`
`...:enterprise:2.0:User:costCenter`	não mapeado
`...:enterprise:2.0:User:division`	não mapeado

Para testar, crie um usuário em Users > New User e preencha os campos mapeados. Adicione-os ao aplicativo em Provisioning > Users and Groups , depois abra Provision on demand e selecione o usuário. Os atributos aparecem então na tab Identity attributes do usuário no console account do Databricks. Limpar o valor de um atributo no usuário do Microsoft Entra ID e realizar o provisionamento sob demanda novamente remove o valor no Databricks, para que os dois lados permaneçam em sincronia.

nota

Se um conector anteriormente íntegro começar a falhar após a lista de controle de atributos ser habilitada ou restringida, a causa é quase sempre que o conector ainda está enviando um atributo que a account não permite mais. O Databricks rejeita toda a solicitação com um 400, portanto, a sincronização falha em vez de ser aplicada parcialmente. Para corrigir, adicione o atributo de volta à lista de controle ou remova esse atributo do mapeamento do conector e, em seguida, force uma sincronização novamente. Um conector que reenvia um valor inalterado não é rejeitado, pois a imposição se aplica apenas a valores que realmente mudam. Consulte Lista de Controle de Atributos de Identidade.

Gerenciar atributos com a API SCIM

Os atributos de identidade são gerenciados no account SCIM 2.1. Cinco dos atributos residem no esquema de usuário principal do SCIM, e os outros quatro residem na extensão de usuário corporativo padrão, cujo URN é urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.

Atributo	Onde ele reside no SCIM
`title`	Usuário principal: `title`
`userType`	Usuário principal: `userType`
`locality`	Usuário principal: `addresses[type eq "work"].locality`
`region`	Usuário principal: `addresses[type eq "work"].region`
`country`	Usuário principal: `addresses[type eq "work"].country`
`costCenter`	Extensão corporativa: `costCenter`
`organization`	Extensão corporativa: `organization`
`division`	Extensão corporativa: `division`
`department`	Extensão corporativa: `department`

Atributo	Onde ele reside no SCIM
`title`	Usuário principal: `title`
`userType`	Usuário principal: `userType`
`locality`	Usuário principal: `addresses[type eq "work"].locality`
`region`	Usuário principal: `addresses[type eq "work"].region`
`country`	Usuário principal: `addresses[type eq "work"].country`
`costCenter`	Extensão corporativa: `costCenter`
`organization`	Extensão corporativa: `organization`
`division`	Extensão corporativa: `division`
`department`	Extensão corporativa: `department`

Em solicitações e respostas, os quatro atributos corporativos são endereçados por seu caminho totalmente qualificado. Por exemplo, urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter.

Criar um usuário com atributos de identidade

Text
POST /api/2.1/accounts/<account-id>/scim/v2/Users
Authorization: Bearer <token>
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane.doe@example.com",
  "displayName": "Jane Doe",
  "title": "Staff Engineer",
  "userType": "Employee",
  "addresses": [
    { "locality": "Mountain View", "region": "CA", "country": "US" }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "costCenter": "4130",
    "organization": "Databricks",
    "division": "Platform",
    "department": "Identity"
  }
}

O Databricks responde 201 Created com o registro completo do usuário. A forma da resposta tem as seguintes características:

schemas sempre anuncia tanto o URN de usuário principal quanto o URN de extensão corporativa, mesmo quando nenhum atributo corporativo está definido.
Atributos sem valor armazenado são omitidos completamente em vez de retornados como null.
Exatamente um endereço é armazenado por usuário, portanto addresses sempre contém um único elemento. O Databricks o marca como "type": "work" e "primary": true automaticamente; ambos são somente leitura e não podem ser mapeados a partir de um provedor de identidade.
O SCIM 2.1 da conta não retorna meta ou entitlements em usuários.

Ler atributos de identidade

Text
GET /api/2.1/accounts/<account-id>/scim/v2/Users/<user-id>
Authorization: Bearer <token>

A resposta tem a mesma forma que a resposta de criação. As leituras nunca são filtradas pela lista de controle de atributos . Um atributo armazenado anteriormente permanece totalmente visível em um GET mesmo após ser removido da lista de controle. Apenas as gravações são controladas.

Atualizar atributos de identidade

Todas as três formas de operação PATCH (add, replace e remove) funcionam para cada atributo, incluindo os caminhos corporativos totalmente qualificados.

Text
PATCH /api/2.1/accounts/<account-id>/scim/v2/Users/<user-id>
Authorization: Bearer <token>
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "title", "value": "Principal Engineer" },
    { "op": "replace", "path": "userType", "value": "Contractor" },
    {
      "op": "replace",
      "path": "addresses",
      "value": [{ "locality": "Seattle", "region": "WA", "country": "US" }]
    },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter",
      "value": "9001"
    }
  ]
}

O Databricks responde 200 OK com o usuário atualizado. addresses é substituído como um valor complexo inteiro, portanto, envie todos os subcampos que você deseja manter. Omitir country do valor acima o limparia.

Remover atributos de identidade

Text
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "remove", "path": "userType" },
    {
      "op": "remove",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division"
    }
  ]
}

O Databricks responde 200 OK, e os atributos removidos não aparecem mais no registro do usuário. As remoções sempre são bem-sucedidas, independentemente da lista de controle de atributos , portanto, um administrador sempre pode retirar um valor armazenado, inclusive para um atributo que a conta não tem mais permissão para gravar.

Quando a lista de controle de atributos rejeita uma gravação

Assim que sua conta for inscrita na visualização da Lista de Controle de Atributos de Identidade, a gravação de um atributo que não esteja na lista será rejeitada. Por exemplo, enviar {"op": "replace", "path": "userType", "value": "Vendor"} quando userType está fora da lista retorna 400 Bad Request:

JSON
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "The following identity attributes are not on this account's attribute control list and cannot be created or updated: userType. Add them to the control list, or remove them from the request. Existing values can still be removed."
}

Antes de integrar, entenda os seguintes comportamentos de imposição:

A imposição é por atributo, não por esquema. Um atributo corporativo fora da lista, como division, é rejeitado mesmo quando outros atributos corporativos na mesma solicitação são permitidos.
Um PATCH é atômico. Se qualquer operação tiver como alvo um atributo fora da lista, toda a solicitação será rejeitada e nenhuma das alterações permitidas será aplicada. Execuções de validação ocorrem antes que o registro de usuário seja alterado.
Apenas valores alterados são verificados. O reenvio de um valor idêntico ao armazenado é uma operação nula (no-op) e passa mesmo para um atributo fora da lista. Isso é importante para conectores de provedor de identidade, que reenviam valores inalterados a cada sincronização.
Os subcampos de endereço são verificados individualmente. locality, region e country precisam, cada um, de sua própria entrada na lista de controle.

Para saber como configurar a lista, consulte Lista de controle de atributos de identidade.

Descubra atributos compatíveis

GET /api/2.1/accounts/<account-id>/scim/v2/Schemas retorna um SCIM ListResponse. Quando os atributos de identidade estão habilitados para a superfície, ela contém quatro recursos de esquema: User (que suporta os atributos adicionais descritos nesta página), Group, ServicePrincipal e a extensão de usuário enterprise.

O esquema de usuário principal anuncia title, userType e addresses. Dentro de addresses, os três subatributos provenientes do provedor de identidade são readWrite, enquanto type e primary são readOnly porque o Databricks os define:

JSON
{
  "name": "addresses",
  "type": "complex",
  "multiValued": true,
  "description": "A physical mailing address for this user.",
  "mutability": "readWrite",
  "returned": "default",
  "subAttributes": [
    { "name": "locality", "type": "string", "mutability": "readWrite" },
    { "name": "region", "type": "string", "mutability": "readWrite" },
    { "name": "country", "type": "string", "mutability": "readWrite" },
    { "name": "type", "type": "string", "mutability": "readOnly", "canonicalValues": ["work"] },
    { "name": "primary", "type": "boolean", "mutability": "readOnly" }
  ]
}

A extensão enterprise também pode ser resolvida por conta própria em GET /api/2.1/accounts/<account-id>/scim/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User, que retorna os quatro atributos enterprise como strings readWrite:

JSON
{
  "id": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
  "name": "EnterpriseUser",
  "description": "Enterprise User",
  "attributes": [
    { "name": "costCenter", "type": "string", "mutability": "readWrite" },
    { "name": "department", "type": "string", "mutability": "readWrite" },
    { "name": "division", "type": "string", "mutability": "readWrite" },
    { "name": "organization", "type": "string", "mutability": "readWrite" }
  ],
  "meta": { "resourceType": "Schema" }
}

A saída /Schemas é estática. Ele não é afetado pela lista de controle de atributos ou pelo que qualquer usuário individual definiu. Isso reflete apenas se a superfície gerencia atributos de identidade.

Ler seus próprios atributos

O SCIM da conta para workspaces é servido a partir do host do workspace em https://<workspace-host>/api/2.0/account/scim/v2/. Esta superfície não expõe atributos de identidade em leituras ou gravações, e os administradores do workspace não têm permissão para ler ou modificar atributos de identidade de outros usuários.

atenção

As gravações em atributos de identidade nesta superfície retornam 2xx, mas são descartadas silenciosamente , não rejeitadas. Uma resposta bem-sucedida não significa que o atributo foi armazenado. Para gravar atributos de identidade, use o SCIM 2.1 da conta. Consulte Gerenciar atributos com a API SCIM.

/Me é a única exceção. Como ele retorna apenas o perfil do próprio chamador, um usuário pode ler seus próprios atributos de identidade lá:

Text
GET /api/2.0/account/scim/v2/Me
Authorization: Bearer <workspace-token>

JSON
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "1234567890123456",
  "userName": "jane.doe@example.com",
  "displayName": "Jane Doe",
  "active": true,
  "emails": [{ "type": "work", "primary": true, "value": "jane.doe@example.com" }],
  "name": { "givenName": "Jane", "familyName": "Doe" },
  "title": "Staff Engineer",
  "userType": "Employee",
  "addresses": [
    {
      "locality": "Mountain View",
      "region": "CA",
      "country": "US",
      "type": "work",
      "primary": true
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "costCenter": "4130",
    "organization": "Databricks",
    "division": "Platform",
    "department": "Identity"
  },
  "groups": [{ "value": "987654321098765", "display": "engineering" }]
}

Considere o seguinte sobre /Me:

/Me é somente leitura aqui. POST, PUT, PATCH e DELETE retornam 501 com "detail": "Endpoint not supported."
groups é sempre retornado em /Me, ao contrário de uma leitura de usuário administrativo.
A lista de controle de atributos não tem efeito sobre /Me, uma vez que a lista rege as gravações e /Me não pode gravar.
O SCIM no nível do workspace (/api/2.0/preview/scim/v2/) é uma API diferente e nunca expõe atributos de identidade no nível da conta em nenhum endpoint, incluindo seu próprio /Me.

Pré-requisitos​

Configurar um conector SCIM​

Okta​

Microsoft Entra ID​

Gerenciar atributos com a API SCIM​

Criar um usuário com atributos de identidade​

Ler atributos de identidade​

Atualizar atributos de identidade​

Remover atributos de identidade​

Quando a lista de controle de atributos rejeita uma gravação​

Descubra atributos compatíveis​

Ler seus próprios atributos​