# Funções

Agrupar permissões de API em funções e atribuí-las a utilizadores e grupos, para que as aplicações autorizem com base em funções.

Requires: rbac

> **Nota sobre o plano:** O controlo de acesso baseado em funções (RBAC) está disponível a partir do plano Advanced (e no Trial).

Uma **função** é um conjunto nomeado de permissões de API que atribui a utilizadores e grupos. Quando um utilizador inicia sessão numa aplicação e essa aplicação pede um token para uma [API com RBAC ativado](https://dts-identity.com/pt/docs/integrations/apis.md#role-based-access-control), a plataforma pode incorporar as funções e permissões do utilizador no token, para que a aplicação possa tomar decisões de autorização granulares sem manter o seu próprio modelo de permissões.

As funções são geridas na Admin Console em **Integrações → Funções**.

> **Nota:** Os administradores delegados (de nível programador) gerem as funções através dos [workspaces](https://dts-identity.com/pt/docs/governance/workspaces.md) a que pertencem. Uma função adicionada a um workspace pode ser gerida e atribuída pelos membros com a permissão **Gerir recursos**; os administradores com acesso total continuam a gerir todas as funções.

## As funções dizem respeito às aplicações, não à Admin Console

Convém deixar claro o que estas funções **não** regem. Controlam o que um utilizador pode fazer **dentro das suas aplicações**, através dos scopes transportados nos tokens de API. **Não** controlam quem pode administrar a plataforma; isso é regido separadamente pelos níveis de acesso que atribui à sua equipa de administração na área **Segurança**.

## Funções de sistema e personalizadas

- As **funções de sistema** são integradas. O nome, a descrição e as permissões são fixos; pode visualizá-las, mas não editá-las nem eliminá-las.
- As **funções personalizadas** são as que cria e gere. Define o nome e a descrição, escolhe as permissões e atribui-as a utilizadores e grupos.

## Criar uma função e adicionar permissões

1. Na página Funções, selecione **Criar função** e atribua-lhe um nome e uma descrição.
2. Abra a função e aceda ao separador **Permissões**.
3. Selecione **Adicionar permissões**, escolha uma **Custom API** e selecione os scopes dessa API a incluir.
4. Guarde.

As permissões de uma função estão sempre associadas a uma Custom API específica. Apenas as **Custom APIs com RBAC ativado** podem contribuir com permissões para uma função, pelo que deve primeiro ativar **Incluir funções e permissões (RBAC)** na API (consulte [APIs](https://dts-identity.com/pt/docs/integrations/apis.md#role-based-access-control)). Se uma função contiver permissões para uma API na qual o RBAC foi posteriormente desativado, ou cuja API foi eliminada, essas entradas são assinaladas na função para que as possa limpar.

> **Nota (CIAM):** em implementações com a capacidade de clientes empresariais (B2B), o formulário de criação de funções oferece uma **allowed relationship**: escolha se a função está disponível para *todos* os utilizadores, apenas para utilizadores *customer* ou apenas para utilizadores *employee*. Isto seleciona a população de utilizadores a que a função se aplica e fica fixo na criação. Sem essa capacidade, uma função aplica-se a todos os utilizadores.

[Image: A lista de funções na Admin Console]

## Atribuir funções

Abra uma função e utilize o separador **Utilizadores** para a atribuir. Pode atribuir uma função a:

- **utilizadores** individuais: consulte [Pessoas](https://dts-identity.com/pt/docs/directories/people.md), e
- **grupos**: consulte [Grupos](https://dts-identity.com/pt/docs/directories/groups.md), para que todos os membros herdem a função.

Para remover uma função de um utilizador, retire-o da lista de utilizadores da função. Eliminar uma função personalizada remove-a de todos aqueles a quem estava atribuída.

Quando um utilizador tem uma função, as permissões nela agrupadas ficam disponíveis para serem incorporadas em tokens para as APIs correspondentes com RBAC ativado.

## Como uma permissão chega a um token

A cadeia desde a definição de uma permissão até à sua aplicação na sua aplicação:

1. **Define uma permissão** (um scope) numa Custom API com RBAC ativado.
2. **Agrupa-a numa função** no separador de permissões da função.
3. **Atribui a função** a um utilizador, diretamente ou através de um [grupo](https://dts-identity.com/pt/docs/directories/groups.md), para que todos os membros a herdem.
4. Quando esse utilizador inicia sessão e uma aplicação pede um token para a API, as permissões a que o utilizador tem direito são resolvidas e podem ser **incorporadas no access token**.

Se os nomes das funções e as permissões aparecem efetivamente no token é controlado por API através das opções **roles in access token** e **permissions in access token** (consulte [APIs](https://dts-identity.com/pt/docs/integrations/apis.md#role-based-access-control)). O compromisso:

- **Ligado**: a aplicação lê as funções/permissões diretamente do token, sem consulta adicional. O custo é um token maior, e um token emitido antes de uma alteração de função mantém as claims antigas até expirar (possível desatualização).
- **Desligado**: o token mantém-se leve; a aplicação resolve ela própria os direitos do utilizador quando precisa deles, o que se mantém atual, mas requer um callback.

### Aplicar no access token, não no ID token [#enforce-on-the-access-token-not-the-id-token]

Uma aplicação que pede o scope `roles` recebe também uma claim `roles` no seu **ID token**. Utilize-a apenas para apresentação: mostrar uma entrada de menu de administração, ocultar um botão. Nunca tome uma decisão de acesso com base nela.

As duas claims não são intermutáveis. O ID token comprova quem iniciou sessão e é dirigido à própria aplicação; não se destina a ser reencaminhado para uma API, e um serviço que o aceite como prova de direitos confia num token que nunca foi emitido para ele. A sua claim `roles` é também a menos precisa das duas: lista nomes de funções sem referência a qualquer API, pelo que não indica se uma função tem algum significado para o recurso chamado.

O access token é o que é dirigido à API, e as suas claims estão circunscritas a essa API. Aplique as decisões aí.

## Referência

| Termo | Significado |
|---|---|
| Função | Um conjunto nomeado de permissões de API atribuído a utilizadores e grupos. |
| Função de sistema | Uma função integrada e não editável. |
| Função personalizada | Uma função que cria e gere. |
| Permissão | Um único scope de API com que uma função contribui para os tokens de um utilizador. |

Consulte também o [glossário](https://dts-identity.com/pt/docs/reference/glossary.md).
