- Criado por Danilo Basilio Medeiros, última alteração por Jandir Deodato De Souza Silva em 20 mar, 2024
Rest users
O SCIM 'users' é um protocolo de aplicação REST para provisionamento e gerenciamento de dados de identidade na web. O protocolo suporta a criação, modificação, recuperação e descoberta de usuários.
O serviço users do Protheus permite a inclusão e manipulação de dados de usuário no sistema. É altamente aconselhável que a autenticação de serviços esteja habilitada no servidor rest para evitar manipulação indevida dos dados. Todos os usuários que se autenticarem para utilizar este serviço devem possuir acesso a rotina CFGA510 (o cadastro de usuários no Protheus)
Detalhes da configuração do REST Protheus e como ligar a autenticação dos serviços acesse a página do REST Protheus aqui.
Atenção
- Via REST apenas é possível a criação básica do usuário. Para configurar permissões, acessos, menus, etc, é necessária a utilização do Identity.
- Quando a senha do usuário é alterada via REST, mesmo enviando a informação
forceChangePassword
comofalso
, caso a senha não esteja de acordo com as Políticas de Senha do Protheus, ao efetuar o login o sistema exibirá a tela de troca de senha. - Este serviço é do tipo
NOTENANT
(faz autenticação, mas não valida empresa e filial).
Métodos disponíveis
GET
Sintaxe /users/{userId}
Para recuperar um usuário conhecido, os clientes enviam requisições GET. Se o usuário existir o servidor responde com o código de estado 200 e inclui o resultado no corpo da resposta. Também é possível listar os usuários do sistema, omitindo o envio do pathParam {userId}.
Parâmetros
Nome | Tipo | Descrição | Default |
---|---|---|---|
userId | string | id ou código do usuário no sistema |
Nome | Tipo | Descrição | Default |
---|---|---|---|
showAdmin | boolean | Indica se o get deve retornar o usuário admin | false |
count | numérico | Indica quantos usuários deverão ser retornados pelo método | Todos |
startIndex | numérico | Indica a partir de qual usuário encontrado deverá ocorrer o retorno. | 1 |
attributes | string | Indica quais atributos do jSon devem ser retornados. Os atributos devem ser separados por ','. | Retorna todos os atributos |
foundBy | string | Parâmetro opcional, usado para determinar o tipo de busca do usuário por ID, LOGIN, MAIL, ou AD | Todos |
domainId | string | Domínio cadastrado para o Usuário, parâmetro obrigatório quando o tipo de busca for AD(Active Directory) |
Atenção
O parâmetro atributes é case sensitive.
Caso o parâmetro foundBy não for informado, a busca é feita com base em todos os tipos.
Parâmetros foundBy e domainId disponíveis a partir da versão de lib_20230918.
Retorno:
Parâmetros
Nome | Tipo | Descrição |
---|---|---|
totalResults | numérico | Indica a quantidade de registros encontrados |
itemsPerPage | numérico | Quantidade de itens retornados na requisição |
startIndex | numérico | Registro “a partir de” do retorno dos registros |
Id | string | Id ou código do usuário no Protheus |
meta | jSon | Relacionado a criação do usuário |
created | String | Data de criação do usuário. Retorna no formato AAAA-MM-DD_HH:MM:SS |
lastModified | String | Data da última alteração do usuário. Retorna no formato AAAA-MM-DD_HH:MM:SS |
externalId | string | Código externo do usuário (e-mail para a maioria dos sistemas) |
name | string | Código do usuário no sistema |
givenName | string | Primeiro nome do usuário |
familyName | string | Segundo nome do usuário |
displayName | string | nome do usuário no sistema |
emails | array de objetos | |
emails:value | string | E-mail no sistema |
emails:type | string | Tipo do e-mail. Sempre retorna "work" |
primary | boolean | Indica se é o e-mail primário do usuário. Sempre retorna true |
active | boolean | Retorna se o usuário está ativo ou não no sistema |
groups | array de objetos | Grupos ao qual o usuário pertence |
groups:value | string | Código do grupo |
groups:display | string | Descrição do grupo |
title | string | Cargo do usuário |
employeeNumber | string | Código de funcionário |
department | string | Código do departamento do usuário |
manager | array de objetos | Informações dos superiores do usuário |
manager:manageId | string | Código do superior do usuário |
manager:displayName | string | Nome do superior no sistema |
{ "schemas": [ "urn:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:enterprise:2.0:User" ], "id": "000021", "meta": { "created": "2018-02-13_00:00:00", "lastModified": "2018-02-13_00:00:00" }, "externalId": "[email protected]", "userName": "User1", "name": { "formatted": "User1", "givenName": "User1", "familyName": "." }, "displayName": "Use1r", "emails": [ { "value": "[email protected]", "type": "work", "primary": true } ], "active": true, "groups": [ { "value": "000001", "display": "grupo2" } ], "title": "Coordenador", "employeeNumber": "02|00|000001", "department": "RH", "manager": [ { "managerId": "000000", "displayName": "Administrador" } ] }
A busca por um usuário passando o Id difere apenas da omissão no resultado dos parâmetros totalResult, itensPerPage e startIndex.
GET (GetUserId)
Sintaxe /users/GetUserId
Retorna o id do usuário atualmente logado pelo serviço REST no Protheus.
{ "userID": "000000" }
POST
Sintaxe /users/{userid}/{operation}
Cria novos usuários no sistema devolvendo na requisição, quando bem sucedida, o código de resposta 201 (created).
Parâmetros
Nome | Tipo | Descrição | Default |
---|---|---|---|
userId | string | Código do usuário no sistema (POST para bloquear ou desbloquear um usuário existente. Para bloquear ou desbloquear é necessário também enviar o parâmetro operation) | |
operation | string | Valores aceitos: activate e deactivate. Indica se o usuário será ativado no sistema (activate) ou se o usuário será bloqueado via SAML (deactivate) ou se um novo usuário será criado (parâmetro vazio ou qualquer outro valor diferente dos anteriores. Caso o parâmetro userId seja enviado mas não seja enviado o parâmetro operation é assumido que um novo usuário será criado no sistema |
Nome | Tipo | Descrição | Default |
---|---|---|---|
userName | string | Nome do usuário | valor do atributo ext/adDomain |
displayName | string | nome completo do usuário | |
externalId | string | Código externo do usuário | Código externo do usuário. Quando enviado indica que o usuário bloqueado via SAML será reativado. O Envio de um externalId que não exista irá gerar a inclusão de um novo usuário. |
title | string | Cargo do usuário | |
emails * obrigatório | array de objetos | O primeiro e-mail com o valor primary apontado como true é o email cadastrado para o usuário (é necessário no mínimo um email primário. Qualquer email não primário enviado é descartado). Caso o e-mail enviado já exista em outro usuário o e-mail ficará em branco. | |
emails:value | string | Código do e-mail | |
emails:primary | boolean | Indica se é um email primário | |
active | boolean | indica se o usuário estará ativo ou bloqueado | true |
groups | array de objetos | grupos ao qual o usuário está associado | |
groups:value * obrigatório | string | código do grupo | |
password | string | senha do usuário. Quando não informado a senha deverá ser alterada posteriormente pelo admin. | hash randômico. |
ext/SAMAccountName | string | Indica o login do usuário no SSO (caso informado, ele substituirá o valor informado no campo userName) | |
ext/adDomain | string | domínio do usuário do SSO | |
urn:scim:schemas:extension:enterprise:2.0:User | objeto | Indica as configurações de usuário superior | |
urn:scim:schemas:extension:enterprise:2.0:User:manager | array de objetos | Array contendo informações do usuário superior | |
urn:scim:schemas:extension:enterprise:2.0:User:manager:managerId | string | código do usuário superior | |
urn:scim:schemas:extension:totvs:2.0:User/forceChangePassword | boolean | Identifica se deve ou não realizar a troca de senha no primeiro acesso | false |
urn:scim:schemas:extension:totvs:2.0:User/employeeNumber | string | Vínculo fincional do usuário. Devem ser enviados os valores de Grupo de Empresas, Filial e Código do vínculo separados por “|”. Exemplo para o grupo 18, filial D MG 01 e código 002: 18|D MG 01|002 | |
urn:scim:schemas:extension:totvs:2.0:User/department | string | código do departamento do usuário | |
urn:scim:schemas:extension:totvs:2.0:User/groupRule | numérico | Define a regra de priorização por grupo: 1 priorizar, 2 desconsiderar e 3 somar. Qualquer valor diferente deste, quando enviado, assume o valor 1. | |
userAllEmp | boolean | Define se o usuário será criado com acessos a todas as empresas, campo considerado apenas na inclusão de usuário. (disponível a partir da lib 20231121) | |
userAllModule | boolean | Define se o usuário será criado com acessos a todos os módulos, campo considerado apenas na inclusão de usuário. (disponível a partir da lib 20231121) | |
userAllAccess | boolean | Define se o usuário será criado com todos os acessos habilitados, campo considerado apenas na inclusão de usuário. (disponível a partir da lib 20231121) |
Exemplo de requisição para a inclusão de usuário:
{ "schemas":[ "urn:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:enterprise:2.0:User" ], "externalId":"TesteUsr", "meta":{ }, "userName":"Usr Tst", "displayName":"User", "title":"Coordenador", "emails":[ { "value":"[email protected]", "primary":true } ], "active":true, "groups":[ { "value":"000002" } ], "password":"pass001", "urn:scim:schemas:extension:totvs:2.0:User/forceChangePassword":true, "urn:scim:schemas:extension:enterprise:2.0:User/employeeNumber":"02|00|000001", "urn:scim:schemas:extension:enterprise:2.0:User/department":"RH", "urn:scim:schemas:extension:totvs:2.0:User/groupRule":2, "ext/sAMAccountName":"user0007", "ext/adDomain":"XP01", "urn:scim:schemas:extension:enterprise:2.0:User":{ "manager":[ { "managerid":"000000" } ] } }
PUT
Sintaxe /users/{userid}
Método utilizado para atualizar um usuário existente. Todos os parâmetros podem ser enviados, tal qual o método POST.
Parâmetros
Nome | Tipo | Descrição | Default |
---|---|---|---|
userId * obrigatório | string | Código do usuário |
Nome | Tipo | Descrição | Default |
---|---|---|---|
foundBy | string | Parâmetro opcional, usado para determinar o tipo de busca do usuário por ID, LOGIN, MAIL, ou AD | Todos |
domainId | string | Domínio cadastrado para o Usuário, parâmetro obrigatório quando o tipo de busca for AD(Active Directory) |
Atenção
Caso o parâmetro foundBy não for informado, a busca é feita com base em todos os tipos.
Parâmetros foundBy e domainId disponíveis a partir da versão de lib_20230918.
Retorno: true, false ou o erro gerado.
DELETE
Sintaxe /users/{userid}
Método utilizado para bloquear um usuário existente. O usuário é bloqueado, e todos os itens amarrados ao seu registro (grupos, vínculo funcional, etc) são desassociados.
Parâmetros
Nome | Tipo | Descrição | Default |
---|---|---|---|
userId * obrigatório | string | Código do usuário |
Nome | Tipo | Descrição | Default |
---|---|---|---|
foundBy | string | Parâmetro opcional, usado para determinar o tipo de busca do usuário por ID, LOGIN, MAIL, ou AD | Todos |
domainId | string | Domínio cadastrado para o Usuário, parâmetro obrigatório quando o tipo de busca for AD(Active Directory) |
Retorno: true, false ou o erro gerado.
Status do documento | Concluído |
---|---|
Data | 14/02/2018 |
Versão | 2.0 |
Versão anterior | 1.0 |
Autores |
Índice |