Configurar o provisionamento SCIM com a API SCIM da Udemy

Visão geral

O Sistema para gerenciamento de identidade entre domínios (SCIM) é uma API padrão para automatizar o provisionamento/desprovisionamento de usuário e grupo, bem como atualizar os dados de usuário e grupo a partir do Provedor de identidade (IdP) do cliente na conta da Udemy Business.  O SCIM é compatível com diversos provedores de identidade, como Okta, Azure AD e OneLogin.  Você também pode usar a API SCIM da Udemy Business para outros IdPs ou ferramentas internas.

Se a sua organização usa um dos seguintes IdPs, consulte nossos guias abaixo sobre a configuração do SCIM:

O SCIM usa uma API REST padrão com dados formatados em JSON. A Udemy Business é compatível com a versão 2.0 do SCIM padrão. A API está disponível para todos os clientes do plano Enterprise.

A API SCIM da Udemy Business é compatível com os seguintes recursos: 

  • Provisionar usuários
  • Desprovisionar usuários (desativação)
  • Alterar endereços de e-mail
  • Alterar detalhes do usuário
  • Provisionar grupos
  • Adicionar/remover usuários de grupos

Descrição do protocolo SCIM

O protocolo SCIM é um protocolo REST no nível da aplicação para provisionar e gerenciar dados de identidade na web. O protocolo é cliente-servidor, onde o cliente é o provedor de identidade (IdP) e o servidor é a Udemy Business.

O fluxo básico é o seguinte:

  • Quando o acesso à Udemy Business é concedido ao usuário no IDP pelo cliente, o IdP nos envia uma solicitação para verificar se o usuário específico existe no nosso banco de dados. Ele emite uma solicitação de busca de usuário por um atributo como userName ou email.
  • Se o usuário não existe, o IdP envia uma solicitação para criar um usuário.
  • Se o usuário existe, o IdP envia uma solicitação de atualização para o usuário.
  • Quando o acesso à Udemy Business é revogado, o IdP envia uma solicitação para desativar o usuário do nosso banco de dados.
  • O IdP também pode enviar solicitações de alteração dos detalhes do usuário.

Como acessar a API?

Para obter as credenciais de autorização para conectar à API SCIM, você deverá configurar a integração do SCIM na página Gerenciar -> Configurações -> Provisionamento (SCIM) da sua conta da Udemy Business. Observação: apenas administradores têm acesso a essa página. 

Clique em Iniciar configuração.

provisioning_scim.png
Na próxima etapa, selecione Escolher provedor, depois Personalizado.

select_provider.png

Clique em Gerar token.

generate_token.png

Nessa tela, clique em Copiar para copiar o token do portador para a área de transferência.

copy_bearer_token.png

Você deverá incluir o cabeçalho HTTP Authorization com o token do portador nas suas solicitações, por exemplo:

GET /scim/v2/Users HTTP/1.1

 Host: myorganization.udemy.com

 Accept: application/scim+json

 Authorization: Bearer <insira seu token de portador aqui>

 Content-Type: application/scim+json

A API SCIM da Udemy Business usa o protocolo HTTP e está disponível apenas via uma conexão HTTPS segura.

O URL básico da API é https://<organization>.udemy.com/scim/v2/. 

Se você estiver desenvolvendo uma aplicação para interagir com a API SCIM da Udemy Business, é recomendável consultar os SCIM RFCs incluídos ao fim deste documento. A implementação da API SCIM da Udemy Business está em conformidade com o padrão.

Endpoints da API SCIM

Endpoints informacionais

Esses endpoints são informativos e servem para configurar os clientes. Eles não exigem autenticação, então não é preciso incluir o cabeçalho Authorization ao acessá-los.

GET /ServiceProviderConfig

Retorna detalhes sobre a implementação do SCIM da Udemy Business, incluindo quais métodos são compatíveis.

GET /Schemas

Retorna informações sobre os esquemas compatíveis com nossa implementação de SCIM. Os esquemas compatíveis são Users e Groups.

GET /Schemas/Users

Retorna todos os atributos compatíveis para os recursos User.

GET /Schemas/Groups

Retorna todos os atributos compatíveis para os recursos Group.

Endpoints de usuário

Usando esses endpoints, é possível listar usuários, filtrar por atributos, adicionar novos usuários, atualizar informações de usuários ou desativar/anonimizar usuários. Lembre-se de que você só poderá acessar usuários que foram criados usando a API SCIM, os usuários criados dentro da Udemy Business não estarão disponíveis a menos que você os reconcilie pelo SCIM. Veja mais detalhes sobre reconciliação abaixo.

Atributos compatíveis

Atributo SCIM

Obrigatório?

Descrição

userName

Sim

O userName do IdP. Deve ser exclusivo.

name, { givenName, familyName }

Não

Nome e sobrenome do usuário. Embora não seja obrigatório, recomendamos sempre especificar esses atributos para facilitar a identificação de usuários.

emails[type=”work”]]['value’]

Sim

E-mail do usuário, deve ser exclusivo

active

Sim

Sinaliza a desativação/reativação de usuários

title

Não

Cargo do usuário, por exemplo, "Engenheiro sênior"

externalId

Sim

O externalId do usuário do IdP. Deve ser exclusivo.

Observação: se você especificar qualquer outro atributo que não esteja nessa lista, ele será ignorado.

GET /Users

Retorna uma lista paginada de usuários, 12 usuários por página como padrão. Você pode passar os parâmetros count e startIndex para paginar o conjunto de resultados. Por exemplo:

GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1

 Host: myorganization.udemy.com

 Accept: application/scim+json

 Authorization: Bearer <insira seu token de portador aqui>

  • startIndex é o índice baseado em 1 do primeiro resultado no conjunto atual de resultados (compensação)
  • count é o número de recursos retornados em uma página de resposta de lista (limite). Até 1.000 usuários podem ser recuperados em uma única solicitação. Se esse item for omitido, o padrão será 12.

GET /Users?filter=

Esse endpoint é usado para filtrar usuários por atributos específicos. Por exemplo, é possível pesquisar pelo atributo userName:

GET /Users?filter=userName eq "gloria.graynor”


Observação: no exemplo acima, você precisará fazer a codificação URL dos parâmetros, para que o URL seja:
GET /Users?filter=userName%20eq%20%22gloria.graynor%22

Isso retornará uma lista de recursos do usuário. Se não houver resultados, uma lista vazia será exibida.

Os filtros compatíveis são:

  • userName
  • externalID
  • emails[type eq=”work”]

Os operadores compatíveis são:

  • and
  • eq

Resposta:

  • Código 200 do status HTTP com a lista de entidades em sucesso
  • Código 501 do status HTTP se um filtro incompatível for fornecido

POST /Users

Esse endpoint é usado para criar (provisionar) novos usuários na Udemy Business. 

A resposta conterá um atributo id que deve ser usado ao referir esse usuário em todas as solicitações subsequentes.

Observação:

  • Novos usuários criados dessa maneira não consumirão uma licença até que o usuário faça login pela primeira vez.
  • Se havia um convite pendente para usuário, ele será usado nesse momento.
    O usuário será adicionado a grupos e atribuído à função/às tarefas de curso adequadas de acordo com o que estiver especificado no convite.
  • Uma tentativa de criar um usuário que já existe na Udemy Business fará com que o usuário se torne gerenciado pelo SCIM (ele será exibido com um pequeno ícone de link nas páginas Gerenciar usuários). O status e o uso de licença do usuário não serão alterados. Se o usuário estava ativo, permanecerá assim, e se o usuário estava desativado, continuará desativado.

Resposta:

  • Código 201 do status HTTP e o recurso do usuário em sucesso
  • Código 409 do status HTTP se o membro com o mesmo userName já existe na Organização
  • Código 400 do status HTTP com os detalhes do erro no corpo da resposta se a solicitação não foi aprovada na validação

GET /Users/<id>

Esse endpoint é usado para recuperar detalhes de um usuário especificado. O parâmetro id na solicitação acima é um identificador exclusivo que retornou quando o usuário foi criado usando o SCIM ou ao listar todos os usuários existentes.

Resposta:

  • Código 200 do status HTTP com o recurso do usuário em sucesso
  • Código 404 do status HTTP se o usuário não foi encontrado

PUT /Users/<id>

Esse endpoint é usado para substituir (sobrescrever) os detalhes do usuário na Udemy Business. Se especificado, o atributo active pode ser usado para desativar ou reativar o usuário.

Resposta:

  • Código 200 do status HTTP e recurso do usuário atualizado
  • Código 404 do status HTTP se o usuário não existe. 
  • Código 400 do status HTTP em caso de tentativa de desativação de um proprietário da organização.

PATCH /Users/<id>

Esse endpoint é usado para fazer atualizações parciais nos detalhes do usuário em nosso sistema, ou seja, você pode usar para alterar apenas alguns atributos do usuário. Ele é oposto ao PUT, que substitui todo o usuário. 

Pode conter o atributo active, que fará com que o usuário seja desativado ou reativado.

  • O corpo de cada solicitação DEVE conter o atributo "schemas" com o valor URI de "urn:ietf:params:scim:api:messages:2.0:PatchOp".
  • O corpo de uma solicitação HTTP PATCH DEVE conter o atributo "Operations", cujo valor é uma matriz de uma ou mais operações PATCH.  Cada objeto de operação PATCH DEVE conter exatamente um membro "op", cujo valor indica a operação a ser realizada e PODE ser "add", "remove" ou "replace".
  • O atributo "path" pode estar vazio. Nesse caso, "value" deve ser um dicionário no formato {"path": "value"}.

Resposta:

  • Código 200 do status HTTP com o recurso do usuário atualizado em sucesso
  • Código 404 do status HTTP se o usuário não foi encontrado
  • Código 400 do status HTTP se há a tentativa de desativar um proprietário da organização ou em caso de uma operação inválida.

Endpoints do grupo

Atributos compatíveis

Atributo SCIM

Obrigatório?

Descrição

displayName

Sim

Título do grupo. Deve ser exclusivo dentre todos os grupos da Udemy Business.

externalId

Não

O externalId do grupo do provedor de identidade

Observação: se você especificar qualquer outro atributo que não esteja nessa lista, ele será ignorado.

GET /Groups

Esse endpoint é usado para obter uma lista paginada de todos os grupos provisionados. Inclua os parâmetros da cadeia de consulta startIndex e count para paginar os resultados. 

Lembre-se de que apenas grupos criados usando o SCIM serão retornados. Os grupos criados na Udemy Business não aparecerão.

GET /Groups?filter=

Esse endpoint é usado para filtrar grupos por atributos específicos. Por exemplo, é possível pesquisar pelo atributo displayName:

GET /Groups?filter=displayName eq "Marketing”

Isso retornará uma lista de recursos do grupo. Se não houver resultados, uma lista vazia será exibida.

Você precisará fazer a codificação URL dos parâmetros, para que a solicitação seja:
GET /Groups?filter=displayName%20eq%20%22Marketing%22

Os filtros compatíveis são:

  • displayName
  • externalId
  • Id
  • member.value

Os operadores compatíveis são:

  • and
  • eq

Resposta:

  • Código 200 do status HTTP com a lista de entidades em sucesso
  • Código 501 do status HTTP se um filtro incompatível for usado

POST /Groups

Esse endpoint é usado para criar (provisionar) novos grupos na Udemy Business. 

Resposta:

  • Código 409 do status HTTP se o grupo provisionado com o mesmo nome já existe na organização, o 409 (Conflito) será exibido com um código de erro scimType de uniqueness.
  • Quando o grupo for criado com sucesso, retornaremos a representação completa do grupo com o código 201 do status HTTP (Criado) juntamente com o cabeçalho Location que contém o URL do recurso de criação do grupo.

GET /Groups/<id>

Esse endpoint é usado para obter os detalhes do grupo da Udemy Business. 

Resposta:

  • Código 200 do status HTTP e um recurso de grupo
  • Código 404 do status HTTP se o grupo não foi encontrado

PUT /Groups/<id>

Esse endpoint é usado para substituir os detalhes do grupo da Udemy Business.

Resposta:

  • Código 200 do status HTTP e recurso do grupo atualizado 
  • Código 404 do status HTTP se o grupo não existe. 

PATCH /Groups/<id>

Esse endpoint é usado para fazer atualizações parciais nos detalhes do grupo da Udemy Business. 

O endpoint PATCH é mais complicado que outros, pois é compatível com diferentes tipos de operação (e é possível fazer combinações):

  • replace operação que altera o valor especificado. No nosso caso, é o nome ou membros do grupo.
  • remove operação que remove um membro do grupo.
  • add operação que adiciona membros ao grupo.

As regras são as seguintes:

  • Nunca removemos membros não provisionados do grupo (no caso da operação de membros "replace", por exemplo).
  • A solicitação PATCH, independentemente do número de operações, DEVERÁ ser considerada atômica.

As validações de entrada são as seguintes:

  • O corpo de cada solicitação DEVE conter o atributo "schemas" com o valor URI de "urn:ietf:params:scim:api:messages:2.0:PatchOp".
  • O corpo de uma solicitação HTTP PATCH DEVE conter o atributo "Operations", cujo valor é uma matriz de uma ou mais operações PATCH.  Cada objeto de operação PATCH DEVE conter exatamente um membro "op", cujo valor indica a operação a ser realizada e PODE ser "add", "remove" ou "replace".
  • O atributo "path" pode estar vazio. Nesse caso, "value" deve ser um dicionário no formato {"path": "value"}.
  • Para a operação "Remove", o caminho "members" é obrigatório.
  • Para a operação "Add", os caminhos "members" ou "externalId" devem estar presentes.
  • Para a operação "Replace", o caminho "members" pode estar presente. Se não estiver, significa que vamos substituir os detalhes do grupo (como o nome do grupo), mas não os membros.

Nota:

  • A atribuição/o cancelamento de atribuição de usuários a um grupo ocorre de maneira assíncrona, então as mudanças não serão refletidas imediatamente na Udemy Business.
  • Não oferecemos compatibilidade com grupos aninhados, então eles serão ignorados durante essa solicitação.

Resposta:

  • Código 204 do status HTTP se a operação foi bem sucedida.
  • Código 404 do status HTTP se o grupo não existe.
  • Código 404 do status HTTP com os detalhes do erro se houve uma tentativa de atribuir um usuário que não é membro da organização a um grupo.
  • Código 400 do status HTTP com os detalhes do erro no corpo da resposta se a solicitação não foi aprovada na validação

DELETE /Groups/<id>

Esse endpoint é usado para remover ou desprovisionar um grupo na Udemy Business. Excluir um grupo não apagará os usuários desse grupo. Os usuários simplesmente serão removidos do grupo excluído.

As regras são as seguintes:

  • Se o grupo contém membros não provisionados, remova os usuários provisionados do grupo, exclua o registro "OrganizationSCIMGroup".

Resposta:

  • Código 204 do status HTTP se a operação foi bem sucedida.
  • Código 404 do status HTTP se o grupo não existe.

Leia mais

Artigos relacionados

Fale conosco