API de provisionamento SCIM
- Leitura
- 4 min
- Categoria
- Proton VPN for Business
Visão geral
A API de provisionamento SCIM (System for Cross-domain Identity Management) é um protocolo padrão para automatizar o provisionamento e o gerenciamento de identidades de usuário em aplicativos baseados na nuvem. O Proton suporta esta API, que permite criar, atualizar, excluir e gerenciar contas de usuário e grupos. A API é baseada na especificação SCIM 2.0, que fornece um esquema de usuário comum e uma interface de API RESTful para facilitar a integração.
O Proton oferece suporte aos seguintes provedores de identidade:
- Okta (https://www.okta.com/(nova janela))
- Microsoft Entra ID
A URL base para todas as chamadas do provedor de identidade é: https://scim.proton.me/{tenentId}/v2/(nova janela). Todos os métodos SCIM são ramificações desta URL base.
Autenticação
O token deve ser incluído em um cabeçalho Authorization com um tipo de Bearer ao chamar qualquer um dos métodos SCIM. Este token pode ser gerado e substituído na seção Single-sign-on > SCIM automatic provisioning. Clique no botão “Gerar novo token” e copie o token gerado.
Por exemplo:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Usuários
Atributos principais
| id | Um identificador único para um recurso SCIM, como um usuário, que é definido pelo Proton. |
| userName (obrigatório) | Um identificador exclusivo para o usuário. Aqui usamos o e-mail como Nome de usuário. |
| active | Um valor booleano que indica se o Usuário está Ativo. O padrão é true. |
Operações
Recuperar uma lista paginada de todos os Usuários
Solicitação
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Resposta
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"itemsPerPage": 1,
"startIndex": 1,
"Resources": [
{
"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true
}
]
}Criar um usuário
Solicitação
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Resposta
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true,
"meta": {
"resourceType": "User",
"created": "2024-07-25T04:39:27Z",
"lastModified": "2024-07-25T04:39:27Z",
"location": "https://scim.proton.me/{tenent-id}/v2/Users/avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"version": "1"
}
}
Recuperar um único Usuário
Solicitação
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Resposta
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true,
"meta": {
"resourceType": "User",
"created": "2024-07-24T06:22:20Z",
"lastModified": "2024-07-24T06:22:20Z",
"location": "https://scim.proton.me/{tenentId}/v2/Users/avveKyJZ_cCkUL1iBZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"version": "1"
},
"externalId": "00uganxwluxxxxxxxxxx"
}Excluir um usuário
Solicitação
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Grupos
Atributos principais
| id | Um identificador único para um recurso SCIM, como um usuário, que é definido pelo Proton. |
| displayName | Nome para o grupo. |
| membros | Uma Lista de membros do grupo. |
Operações
Obter Lista de Grupos
Solicitação
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Resposta
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 0,
"itemsPerPage": 100,
"startIndex": 1,
"Resources": [
{
"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
"displayName": "Admins",
"members": [
{
"value": "2819c223-7f76-453a-919d-413861904646",
"display": "John Doe"
}
],
"meta": {
"resourceType": "Group",
"created": "2024-07-25T05:10:22Z",
"lastModified": "2024-07-25T05:10:22Z",
"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
}
}
]
}Recuperar os detalhes de um grupo pelo seu ID exclusivo
Solicitação
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Resposta
{
"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
"displayName": "Admins",
"members": [{ "value": "2819c223-7f76-453a-919d-xxxxxxxxxxxx", "display": "John Doe" }],
"meta": {
"resourceType": "Group",
"created": "2024-07-25T05:10:22Z",
"lastModified": "2024-07-25T05:10:22Z",
"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
}
}
Tratamento de erro
As respostas são formatadas seguindo a RFC-7644 seção 3.12(nova janela), que são entregues com um código de Status HTTP indicando a natureza do erro e um corpo de resposta fornecendo mais detalhes.
Resposta de erro
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Os erros mais comuns
- 400 Bad Request: A solicitação era inválida ou não pode ser atendida de outra forma.
- 404 Not Found: O recurso solicitado não pôde ser encontrado.
- 409 Conflict: A solicitação não pôde ser concluída devido a um conflito com o estado atual do recurso de destino.
uniqueness: Um Valor de atributo exclusivo já existe no Sistema.
- 500 Internal Server Error: Um erro ocorreu no lado do servidor.