# Aprovisionamento de aplicações

Crie, atualize e desative contas em aplicações a jusante automaticamente através de SCIM de saída, com mapeamentos de atributos e grupos.

O aprovisionamento mantém automaticamente as contas nas suas aplicações a jusante em sintonia com a plataforma. Quando cria, altera ou desativa um utilizador, ou atribui e retira uma aplicação, a plataforma envia a alteração correspondente para a aplicação ligada, pelo que não tem de manter contas manualmente em cada sistema.

A plataforma aprovisiona através de **SCIM 2.0**. Atua exclusivamente como **cliente SCIM de saída**: envia alterações *para* as aplicações que liga. **Não** disponibiliza um servidor SCIM de entrada, pelo que outros sistemas não podem aprovisionar *para dentro* da plataforma através de SCIM.

O aprovisionamento é configurado no separador **Aprovisionamento** de uma aplicação, em **Integrações → Aplicações**.

> **Nota sobre o plano:** O aprovisionamento está incluído no plano Essential e superiores (e no Trial); não faz parte do plano Free. No plano Free, o separador de aprovisionamento continua a mostrar o que o aprovisionamento faz, mas não pode ser configurado nem ativado.

## O que o aprovisionamento faz

Quando o aprovisionamento está ativo para uma aplicação, a plataforma pode:

- **Criar** uma conta na aplicação a jusante quando um utilizador lhe é atribuído.
- **Atualizar** a conta a jusante quando os atributos mapeados do utilizador mudam.
- **Desativar** a conta a jusante quando o utilizador perde o acesso e **reativá-la** quando o acesso é restabelecido.
- **Sincronizar grupos e as respetivas filiações**, para que a estrutura de grupos seja replicada a jusante.

Cada uma destas operações tem o seu próprio interruptor, pelo que pode, por exemplo, criar e atualizar contas, mas nunca desativá-las. A plataforma aprovisiona principalmente **utilizadores e os respetivos atributos**; o envio de grupos é um extra opcional que replica os objetos de grupo e quem pertence aos mesmos, não uma forma de gerir a estrutura de grupos própria da aplicação a jusante (essa permanece na aplicação de destino).

## Estado do aprovisionamento

O aprovisionamento de uma aplicação passa por um pequeno conjunto de estados, apresentado no topo do separador de aprovisionamento:

| Estado | Significado |
|---|---|
| **Disabled** | Ainda não foi configurado nenhum aprovisionamento. |
| **Enabled** | Os dados de ligação estão guardados, mas ainda não foram verificados. |
| **Tested** | A ligação ao endpoint SCIM a jusante foi bem-sucedida. |
| **Activated** | O aprovisionamento está em funcionamento; a plataforma mantém a aplicação sincronizada. |

O percurso habitual é *disabled → enabled → tested → activated*. Pode desativar o aprovisionamento a qualquer momento ou eliminar a configuração para voltar a *disabled*.

## Configurar o aprovisionamento

1. Abra a aplicação e aceda ao separador **Aprovisionamento**.
2. Introduza o **URL base do SCIM** da aplicação a jusante e escolha um **método de autenticação**:
   - **Bearer Token**: um token enviado no cabeçalho `Authorization`.
   - **Basic**: um nome de utilizador e uma palavra-passe.
   - **Cabeçalho HTTP personalizado**: um nome e um valor de cabeçalho enviados tal como estão, para destinos com um esquema proprietário (por exemplo `Authorization: PLANONKEY accesskey=...` ou `X-Api-Key`).
   
   Nas aplicações do catálogo, o URL base e o método são pré-preenchidos a partir da integração e são só de leitura; apenas fornece as credenciais.
3. Escolha as operações a ativar: **criar utilizadores**, **atualizar utilizadores**, **desativar utilizadores**, **reativar utilizadores** e **sincronização de grupos**.
4. Escolha a **ação de desaprovisionamento**, ou seja, o que acontece a jusante quando um utilizador deixa de ter direito de acesso (consulte [Comportamento de desativação](#deactivation-behaviour)).
5. Opcionalmente, em **Conectividade**, selecione um ou mais **conectores de aprovisionamento** se o sistema de destino se encontrar dentro da sua rede (ver abaixo).
6. **Teste a configuração**. Um teste bem-sucedido muda o estado para *tested*.
7. **Ative** o aprovisionamento. A partir deste momento, a plataforma mantém a aplicação sincronizada automaticamente.

### Alcançar um destino dentro da sua rede

Se a aplicação a jusante não estiver acessível a partir da Internet, encaminhe o aprovisionamento através de um ou mais **Enterprise Connectors** do tipo *provisioning*. Em **Conectividade**, no separador de aprovisionamento, selecione os conectores a utilizar, por ordem de prioridade. Quando há conectores selecionados, o aprovisionamento passa **apenas** por eles; quando nenhum está selecionado, a plataforma liga-se diretamente ao destino através da Internet. Consulte [Enterprise Connectors](https://dts-identity.com/pt/docs/directories/enterprise-connectors.md).

[Image: The provisioning tab of an application, with its SCIM connection and the operations it pushes]

## Mapeamento de atributos

O aprovisionamento mapeia cada utilizador da plataforma para um registo de utilizador SCIM. O mapeamento padrão abrange os atributos comuns (nome de utilizador, ou seja, o identificador de início de sessão ou o e-mail quando não existe um início de sessão separado; nome de apresentação; nome próprio, apelido e nome do meio; e-mail e telefone principais; e o indicador de ativo) e inclui a extensão empresarial SCIM para atributos como número de colaborador, departamento e gestor, quando existem.

O estado **active** de um utilizador é derivado do respetivo estado, pelo que desativar um utilizador na plataforma marca a conta a jusante como inativa.

Os **grupos** são mapeados pelo nome e os seus membros referenciam os identificadores SCIM dos utilizadores que foram aprovisionados na mesma aplicação.

O mapeamento é **fixo e de um para um**: cada campo da plataforma corresponde ao seu equivalente SCIM, com algumas alternativas sensatas (por exemplo, o nome de utilizador recorre ao e-mail quando não está definido um início de sessão separado). **Não existe motor de expressões, scripting nem transformação por atributo**: a plataforma não calcula nem reescreve valores, pelo que não deve procurar um editor de regras. Nas aplicações do catálogo, o mapeamento é fornecido com a integração; nas aplicações personalizadas, segue este mapeamento SCIM padrão.

### Porque é que a minha alteração chegou (ou não) à aplicação?

Só os atributos **mapeados** são enviados a jusante. Se alterar um campo do perfil que faz parte do mapeamento padrão (nome, e-mail, telefone, departamento, etc.), a plataforma envia-o para todas as aplicações em que o utilizador está aprovisionado, desde que **atualizar utilizadores** esteja ativado para essa aplicação. Se alterar um campo que *não* consta do mapeamento, nada é enviado: a conta a jusante não é afetada.

Assim, quando uma alteração não aparece numa aplicação ligada, verifique, por esta ordem: se o utilizador ainda tem uma atribuição ativa, se **atualizar utilizadores** está ativado e se o campo que alterou é um dos que o mapeamento transporta. Consulte [Pessoas](https://dts-identity.com/pt/docs/directories/people.md) e [Perfis e atributos de utilizador](https://dts-identity.com/pt/docs/directories/user-profiles-and-attributes.md) para saber que campos existem.

### Quando cada operação é executada

Não existe uma divisão entre apenas criação e apenas atualização por atributo: o mesmo mapeamento é utilizado em ambos os casos:

- Com **criar utilizadores** ativado, o registo mapeado completo é escrito quando o utilizador obtém pela primeira vez uma atribuição à aplicação.
- Com **atualizar utilizadores** ativado, a plataforma volta a enviar os atributos mapeados sempre que o perfil do utilizador muda (ignora os utilizadores cujo perfil não mudou desde a última sincronização, a menos que force uma atualização completa).

Se **criar utilizadores** estiver ativado mas **atualizar utilizadores** estiver desativado, a conta é configurada uma vez e as alterações posteriores nunca lhe chegam. Ative **atualizar utilizadores** se precisar que as alterações continuem a ser transmitidas.

## Modelos de aprovisionamento do catálogo

As integrações do catálogo podem incluir um **modelo de aprovisionamento**, para que não tenha de determinar o endpoint, o método de autenticação e os mapeamentos por si próprio. Quando adiciona uma aplicação deste tipo, a respetiva ligação de aprovisionamento é pré-preenchida e apenas fornece as credenciais.

Algumas entradas do catálogo são **apenas de aprovisionamento**: criam e mantêm contas a jusante, mas não oferecem single sign-on. Aparecem como um tipo de aplicação apenas de aprovisionamento, sem client secret e sem fluxo de início de sessão; configura apenas o respetivo separador de aprovisionamento.

## Forçar uma sincronização completa

Normalmente, o aprovisionamento funciona de forma contínua: a plataforma reage a alterações de utilizadores e grupos e a alterações de atribuições, e reconcilia cada aplicação ativada num ciclo curto e recorrente em segundo plano. Não precisa de desencadear manualmente as alterações comuns.

Se precisar de enviar tudo novamente, por exemplo depois de corrigir um mapeamento ou de recuperar o sistema a jusante, utilize **Forçar atualização completa** no separador de aprovisionamento. Isto volta a enviar todos os utilizadores e grupos atribuídos no próximo ciclo de sincronização, mesmo os registos que não mudaram.

Se as credenciais a jusante deixarem de funcionar (por exemplo, se o token for revogado), o aprovisionamento regressa automaticamente a *enabled* para que possa fornecer novas credenciais e testar novamente.

## O que desencadeia o aprovisionamento

A plataforma aprovisiona em resposta a:

- um utilizador ser **atribuído** à aplicação ou **retirado** da mesma (diretamente ou através de um grupo, diretório ou organização),
- uma alteração ao **perfil** de um utilizador,
- um utilizador ser **desativado** ou **eliminado**,
- uma alteração a um **grupo** ou à respetiva **filiação**.

A atribuição é a condição: um utilizador só é aprovisionado numa aplicação enquanto detiver uma [atribuição](https://dts-identity.com/pt/docs/integrations/applications.md#assigning-applications-to-users) ativa à mesma.

## Comportamento de desativação [#deactivation-behaviour]

Um utilizador **perde o direito de acesso** quando a sua atribuição é removida ou quando é suspenso, desaprovisionado ou eliminado na plataforma (consulte [Ciclo de vida do utilizador](https://dts-identity.com/pt/docs/directories/user-lifecycle.md)). Nesse momento, a plataforma aplica a **ação de desaprovisionamento** da aplicação:

| Ação | Efeito a jusante |
|---|---|
| **Manter** | Deixa a conta a jusante intacta; apenas a ligação local é removida. |
| **Desativar** | Marca a conta a jusante como inativa (reversível). |
| **Eliminar** | Remove completamente a conta a jusante. |

A predefinição é **desativar**: uma saída reversível que desativa a conta a jusante em vez de a eliminar definitivamente, para que um utilizador que regresse possa ser reativado. Escolha **eliminar** apenas quando a aplicação ligada não deva manter de todo a conta, ou **manter** quando o sistema a jusante tenha de conservar registos históricos.

Isto permite-lhe prever a saída de utilizadores: suspenda ou desaprovisione um utilizador na plataforma e a conta de cada aplicação ligada segue a ação que definir aqui. Se **reativar utilizadores** estiver ativado, restaurar o utilizador volta a ativar uma conta a jusante anteriormente desativada.

## Resolução de problemas

- **O teste falha**: verifique novamente o URL base do SCIM e as credenciais, e se o endpoint SCIM da aplicação a jusante está acessível.
- **O aprovisionamento regressou a *enabled***: as credenciais guardadas foram rejeitadas. Introduza novas credenciais e teste novamente.
- **Um utilizador não foi criado a jusante**: confirme que o utilizador tem uma atribuição ativa à aplicação e que **criar utilizadores** está ativado.
