Referência da API SCIM

Esta página é técnica. Ela descreve a API SCIM 2.0 do BreezeAuth para os desenvolvedores e as equipes que configuram um sistema de provisionamento ou constroem o seu próprio cliente SCIM. O BreezeAuth segue a RFC 7643 (schemas) e a RFC 7644 (protocolo), com o escopo e os limites descritos aqui. O que cada operação faz com usuários e grupos está explicado em Provisionar usuários e Provisionar grupos.

URL base e endpoints

Cada organização tem a sua própria URL base. Veja Encontre a sua URL base do SCIM.

https://api.breezeauth.com/organizations/<ID da organização>/scim/v2

Método	Caminho	Descrição
GET	/ServiceProviderConfig	Os recursos que este servidor SCIM suporta.
GET	/ResourceTypes, /ResourceTypes/{name}	Os tipos de recurso: User e Group.
GET	/Schemas, /Schemas/{id}	Os schemas User (core), Enterprise User e Group (core).
GET	/Users	Listar e filtrar usuários.
POST	/Users	Criar um usuário.
GET	/Users/{id}	Ler um usuário.
PUT	/Users/{id}	Substituir um usuário.
PATCH	/Users/{id}	Alterar alguns atributos de um usuário.
DELETE	/Users/{id}	Excluir um usuário.
GET	/Groups	Listar e filtrar grupos.
POST	/Groups	Criar um grupo.
GET	/Groups/{id}	Ler um grupo com os seus membros diretos.
PUT	/Groups/{id}	Substituir um grupo e os seus membros.
PATCH	/Groups/{id}	Renomear um grupo, ou adicionar ou remover membros.
DELETE	/Groups/{id}	Excluir um grupo sem membros.

/Bulk e /Me não estão disponíveis.

Autenticação

Toda requisição precisa levar, no cabeçalho Authorization, um token de acesso de um usuário de serviço com o papel Provisionador SCIM:

Authorization: Bearer <token de acesso>

Os tokens são obtidos em https://api.breezeauth.com/oauth/token com a concessão OAuth 2.0 client credentials e a credencial do usuário de serviço. Eles têm curta duração: solicite um novo antes que expires_in acabe, ou quando uma requisição retornar 401 Unauthorized. Veja Obter tokens de acesso para o formato da requisição e exemplos de código.

Todos os controles que valem para usuários de serviço valem também para as requisições SCIM: a credencial e o usuário de serviço precisam estar ativos, e a requisição precisa vir de uma rede e de um país permitidos, se a sua organização os restringe.

Requisições e respostas

• Envie os corpos das requisições em JSON, com Content-Type: application/scim+json ou application/json.
• As respostas usam Content-Type: application/scim+json.
• O atributo schemas é opcional nas requisições. O BreezeAuth sempre o inclui nas respostas.
• As requisições POST bem-sucedidas retornam 201 Created e o endereço do novo recurso no cabeçalho Location. As requisições DELETE bem-sucedidas retornam 204 No Content, sem corpo.
• As datas em meta.created e meta.lastModified estão no formato ISO 8601 e em UTC.

Listar e filtrar

GET /Users e GET /Groups retornam uma ListResponse:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 128,
  "startIndex": 1,
  "itemsPerPage": 50,
  "Resources": [{ "id": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "userName": "[email protected]", "…": "…" }]
}

Parâmetro	Descrição
filter	Uma expressão de igualdade. Veja abaixo.
startIndex	A posição, a partir de 1, do primeiro resultado. Padrão 1.
count	Quantos resultados por página. Padrão 50. O máximo é filter.maxResults em /ServiceProviderConfig; valores maiores são reduzidos a ele.

Filtros

O BreezeAuth suporta uma única expressão de igualdade (eq) nestes atributos:

Recurso	Atributos	Exemplo
Usuários	userName, externalId	userName eq "[email protected]"
Grupos	displayName, externalId	displayName eq "Equipe de Vendas"

Escape aspas duplas e barras invertidas no valor com uma barra invertida, e codifique o filtro inteiro para URL na query string. Outros operadores (co, sw, gt…), and, or e not são recusados com 400 Bad Request e scimType invalidFilter.

Paginação

Os resultados são retornados em páginas de count itens. Uma página sempre começa em um múltiplo de count, mais um: com count=50, as páginas começam em 1, 51, 101 e assim por diante. Se você pedir outro startIndex, o BreezeAuth retorna a página que o contém, e o startIndex da resposta indica onde essa página realmente começa. Para ler todos os resultados, comece em 1 e some itemsPerPage ao startIndex até ter totalResults itens.

GET /Groups não inclui os membros. Leia cada grupo com GET /Groups/{id} para obtê-los.

Selecionar atributos

Use attributes para retornar apenas alguns atributos, ou excludedAttributes para deixar alguns de fora. Os dois recebem uma lista separada por vírgulas e não podem ser usados na mesma requisição. Eles funcionam em toda requisição que retorna usuários ou grupos, inclusive POST, PUT e PATCH.

GET /Users?attributes=userName,name.givenName,active
GET /Users?excludedAttributes=urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Subatributos usam um ponto, como em name.givenName. Os atributos da extensão Enterprise usam a URN completa do schema como prefixo, como em urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department. schemas, id e meta são sempre retornados.

Erros

Os erros seguem o formato de erro do SCIM:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "email_already_used"
}

Status	scimType	Significado
400 Bad Request	invalidSyntax	O corpo não é uma mensagem SCIM válida, por exemplo um PATCH sem Operations.
400 Bad Request	invalidValue	Um valor está faltando ou é inválido, como um userName ausente, um membro sem type válido ou uma troca de e-mail que o BreezeAuth não permite.
400 Bad Request	invalidFilter	O filtro não é suportado. Veja Filtros.
400 Bad Request	invalidPath	O caminho do PATCH não é suportado.
400 Bad Request	mutability	O atributo não pode ser removido, como active ou userName.
400 Bad Request	tooMany	O grupo tem mais membros diretos do que o SCIM consegue retornar.
401 Unauthorized		O token está ausente, é inválido ou expirou; a credencial ou o usuário de serviço está inativo; o papel não permite a operação; a requisição vem de uma rede fora das suas zonas de rede; ou o usuário é um Proprietário.
403 Forbidden		A requisição vem de um país que a sua organização não permite.
404 Not Found		O usuário, grupo, membro ou schema não existe nesta organização.
409 Conflict	uniqueness	Outro usuário já tem esse userName ou externalId, ou outro grupo já tem esse externalId.
409 Conflict		O grupo ainda tem membros e não pode ser excluído.
429 Too Many Requests		Requisições demais. Veja Limites de requisições.
500 Internal Server Error		Um erro inesperado. Tente de novo mais tarde; se persistir, fale com o suporte do BreezeAuth.

O campo detail traz um código curto que diz exatamente o que deu errado. Os mais comuns:

detail	Significado
scim_user_name_required	O userName está ausente ou vazio.
scim_group_display_name_required	O displayName está ausente ou vazio.
scim_member_type_not_supported	O type de um membro está ausente ou não é User nem Group.
scim_value_invalid	Um valor tem o tipo ou o formato errado, por exemplo um active que não é booleano.
scim_filter_not_supported	O filtro usa um operador ou um atributo que não é suportado.
scim_attribute_path_invalid	O caminho do PATCH não é suportado, ou o atributo não pode ser removido.
scim_operation_invalid	Um PATCH não tem operações, ou uma operação não é add, replace nem remove.
scim_group_members_limit_exceeded	O grupo tem membros diretos demais para ser retornado pelo SCIM.
email_already_used	Outro usuário da organização já tem esse endereço de e-mail.
scim_external_id_already_used	Outro usuário ou, no caso de um grupo, outro grupo já tem esse externalId.
email_address_of_guest_membership_cannot_be_updated	O e-mail de convidados não pode ser alterado.
email_address_of_verified_user_to_unverified_domain_cannot_be_updated	O e-mail de um usuário gerenciado só pode mudar para outro domínio verificado.
cannot_delete_group_with_assignments	O grupo ainda tem membros.

Limites de requisições

As requisições SCIM são limitadas por token de acesso:

Janela	Requisições
1 segundo	50
10 segundos	400
30 segundos	1.500
1 minuto	4.000

Acima desses limites, o BreezeAuth responde 429 Too Many Requests. Aguarde um pouco e tente de novo, aumentando a espera a cada novo 429. A maioria dos sistemas de provisionamento faz isso sozinha.

Recursos suportados

GET /ServiceProviderConfig descreve estas capacidades no formato padrão:

Recurso	Suportado
patch	Sim
filter	Sim, apenas igualdade. maxResults é o maior tamanho de página.
bulk	Não
sort	Não
etag	Não
changePassword	Não
authenticationSchemes	OAuth Bearer Token