Documentação do Oracle Cloud Infrastructure

Configurando o Provisionamento JIT SAML

O Provisionamento Just-In-Time (JIT) SAML automatiza a criação de conta de usuário quando o usuário tenta pela primeira vez executar SSO e o usuário ainda não existe no domínio de identidades. Além da criação automática de usuário, o Provisionamento JIT SAML permite conceder e revogar associações de grupos como parte do provisionamento. O Provisionamento JIT SAML pode ser configurado para atualizar os usuários provisionados, de forma que os atributos de usuários no armazenamento do Provedor de Serviços (SP) possam ser mantidos sincronizados com os atributos de armazenamento de usuário do Provedor de Identidades (IdP).

Ao configurar o Provisionamento JIT SAML, você define como os dados do usuário enviados pelo seu IdP SAML serão usados para criar e/ou atualizar usuários no seu domínio de identidades. Primeiro, você cria e configura um SAML IdP para SSO federado e, em seguida, ativa e configura as opções de Provisionamento JIT SAML para esse IdP.

O Provisionamento JIT SAML só pode ser configurado usando o ponto final da API REST /admin/v1/IdentityProviders.

A tabela a seguir descreve os atributos de configuração IdP relevantes para o Provisionamento JIT SAML. Para obter informações sobre como usar o OAuth 2 para Acessar a API REST, consulte Usando o OAuth 2 para Acessar a API REST.
Propriedade IdentityProvider Descrição Exemplo de JSON
jitUserProvEnabled

Propriedade booleana para ativar/desativar o recurso Provisionamento JIT SAML para este IdP.

Se essa propriedade for true, pelo menos um de jitUserProvCreateUserEnabled ou jitUserProvAttributeUpdateEnabled também deverá ser true.		 
"jitUserProvEnabled": true,
jitUserProvCreateUserEnabled

Propriedade booleana que indica se um usuário deve ser criado, com base na asserção recebida, se o usuário ainda não existir.

Por padrão, os usuários criados usando o Provisionamento JIT SAML são usuários "federados". Os usuários federados não têm credenciais para acessar diretamente o domínio de identidades, mas devem ser autenticados pelo provedor de identidades externo. O status federado de um usuário pode ser alterado usando a console Admin e atualizando o atributo isFederatedUser usando a API REST. Por exemplo, talvez você queira alterar o status federado de usuários com privilégios de administrador para que eles possam acessar diretamente a Console. Se você preferir que todos os usuários criados usando o Provisionamento JIT SAML sejam criados como usuários não federados (criados com uma senha de acesso do domínio de identidades), defina isFederatedUser=false na configuração de mapeamentos de atributo JIT. Consulte attributeMappings na tabela a seguir.

 
"jitUserProvCreateUserEnabled": true,
jitUserProvAttributeUpdateEnabled

Propriedade booleana que indica se os atributos do usuário devem ser atualizados, com base na asserção recebida, se o usuário já existir.

 
"jitUserProvAttributeUpdateEnabled": true,
jitUserProvAttributes

Essa é uma referência a um objeto MappedAttributes, que define o mapeamento dos valores do atributo de asserção SAML IdP para os atributos do usuário do domínio de identidades, para criação dinâmica do usuário e atualizações do atributo do usuário. (Defina na criação do IdentityProvider, não atualize essa referência.)

Veja abaixo detalhes do uso de jitUserProvAttributes do recurso MappedAttributes.
jitUserProvGroupAssertionAttributeEnabled

Propriedade booleana que indica se as associações de grupo devem ser designadas ao usuário com base em uma lista de nomes de grupo recebidos do IdP em um atributo SAML.

Se essa propriedade for true, a propriedade jitUserProvGroupSAMLAttributeName deverá ser definida.

 
"jitUserProvGroupAssertionAttributeEnabled": true,
jitUserProvGroupMappingMode

Propriedade de string que controla como os grupos em IdP são mapeados para aqueles no domínio de identidades. O valor deve ser:

explícito - Os grupos IdP são mapeados explicitamente para os grupos no domínio de identidades usando a propriedade de configuração jitUserProvGroupMappings.

implícito - Os nomes de grupo na asserção SAML devem corresponder aos nomes de grupo no domínio de identidades.

O padrão é explicit se nenhum valor for especificado.

 
"jitUserProvGroupMappingMode": "explicit",
jitUserProvGroupMappings

Array de mapeamentos entre grupos na asserção IdP e grupos no domínio de identidades.

Cada objeto no array representa um mapeamento entre um grupo IdP e um grupo de domínios de identidades.

idpGroup é o identificador de grupo na asserção IdP e value é o identificador de grupo no domínio de identidades.

O número máximo de mapeamentos de grupo por IdP é 250.

 

		"jitUserProvGroupMappings": [
   {
     "idpGroup": "7e18e37e-1b2f-46d9-9d9c-6df136570b27",
     "value": "4bce9b677ab447f18b65ba7bf9a61c21"
   },
   {
     "idpGroup": "cf6f7594-d454-40ac-971b-07cf0627ca17",
     "value": "6d8448a643b94b268d986e9d31e20cbc"
   }
 ]
jitUserProvGroupSAMLAttributeName

O nome do atributo de asserção SAML que conterá grupos a serem designados ao usuário, se a propriedade jitUserProvGroupAssertionAttributeEnabled for true.

O atributo de asserção pode incluir:
  • um único elemento Valor do Atributo, contendo uma lista separada por vírgulas de nomes de grupo; ou
  • vários elementos AttributeValue, cada um com um único nome de grupo.
 
"jitUserProvGroupSAMLAttributeName": "FederatedGroups",
jitUserProvGroupStaticListEnabled

Propriedade booleana que indica se as associações de grupo devem ser atribuídas ao usuário com base em uma lista estática de nomes de grupo.

Se essa propriedade for true, a propriedade jitUserProvAssignedGroups deverá ser definida.

 
"jitUserProvGroupStaticListEnabled": true,
jitUserProvAssignedGroups

Array de grupos a serem designados ao usuário, além de quaisquer valores recebidos na asserção SAML, se a propriedade jitUserProvGroupStaticListEnabled for true.

Observação: os valores definidos nesta matriz são IDs de grupo (não nomes de grupo).

 
"jitUserProvAssignedGroups": 
[
{"value": "21f273857a304684a8f7e353e452a2e1"},
{"value": "1962687f74b84121b69c5560769e8b06"}
],
jitUserProvGroupAssignmentMethod

Propriedade de string que controla como as associações de grupo serão designadas ao usuário no domínio de identidades. O valor deve ser:

  • Overwrite - Substitui todas as associações de grupo do usuário pelas recebidas na asserção SAML e/ou configuradas estaticamente aqui.
  • Merge - Adicione às associações de grupo existentes do usuário as mapeadas implicitamente da asserção SAML e/ou configuradas estaticamente aqui. Os grupos mapeados explicitamente são sempre substituídos/substituídos pelos valores de asserção SAML. Observação: Ao usar a opção de mesclagem, se você remover um usuário do IdP, também deverá remover o usuário do domínio de identidades. As permissões não são removidas automaticamente do domínio de identidades. 
"jitUserProvGroupAssignmentMethod": "Merge",
jitUserProvIgnoreErrorOnAbsentGroups

Propriedade booliana que determina a ação a ser tomada quando o atributo de asserção de entrada especifica um grupo que não existe ou um grupo para o qual um mapeamento de grupo não existe no domínio de identidades.

Se essa propriedade for verdadeira, o grupo ausente será ignorado e o usuário será criado.

Se esta propriedade for falsa e um grupo não existente for especificado, a criação do usuário falhará.

O padrão é verdadeiro para o modo explicit e falso para o modo implicit especificado usando jitUserProvGroupMappingMode.

 
"jitUserProvIgnoreErrorOnAbsentGroups": true,

Configurando o Mapeamento jitUserProvAttributes

Depois que o IdentityProvider tiver sido criado e os atributos de Provisionamento JIT SAML configurados conforme necessário, o recurso jitUserProvAttributes deverá ser atualizado para adicionar seus mapeamentos de atributo de entrada. O recurso MappedAttributes, referenciado por jitUserProvAttributes, é criado e excluído automaticamente com o recurso IdentityProvider, e essa propriedade é marcada como imutável. Os mapeamentos de atributo de Provisionamento JIT SAML são configurados atualizando o objeto MappedAttributes existente, não substituindo-o.

A tabela a seguir descreve as propriedades MappedAttributes usadas pelo Provisionamento JIT SAML.
Propriedade MappedAttributes Descrição Exemplos de JSON
attributeMappings
A lista de mapeamentos entre os atributos de asserção SAML e os atributos do usuário do domínio de identidades. Cada mapeamento consiste em:
  • idcsAttributeName - Uma expressão que define o caminho para o atributo do usuário ao qual deve ser atribuído um valor de entrada. As expressões seguem a sintaxe SCIM, conforme usada pelo recurso Sincronização do Usuário dos domínios de identidades. A expressão fornecida para este atributo é validada no esquema User.
  • managedObjectAttributeName - Uma expressão de política que define o valor a ser mapeado para o atributo do usuário. Isso pode ter valores como $(assertion.firstname) para se referir a um atributo de asserção chamado "firstname", ou pode ser uma literal de string estática ou uma função.

Observação: os nomes de atributos de asserção SAML fazem distinção entre maiúsculas e minúsculas. 

"attributeMappings":[
{
"idcsAttributeName": "userName",
"managedObjectAttributeName": "$(assertion.mail)"
},
{
"idcsAttributeName": "name.givenName",
"managedObjectAttributeName": "$(assertion.firstname)"
},
{
"idcsAttributeName": "name.familyName", 
"managedObjectAttributeName": "$(assertion.lastname)" 
}, 
{ 
"idcsAttributeName": "emails[primary eq true and type eq \"work\"].value", 
"managedObjectAttributeName": "$(assertion.mail)" 
}, 
{ 
 "idcsAttributeName": "urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:isFederatedUser", 
"managedObjectAttributeName": "#toBoolean(\"false\")"
}, 
{
"idcsAttributeName":
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:Organization",
"managedObjectAttributeName": "ACME Corporation"}, 
{ 
"idcsAttributeName": "externalId", 
"managedObjectAttributeName":
"#concat(\"ACME/\",$(assertion.fed.nameidvalue))" 
}
],
refResourceType

O nome do recurso que está usando/tem uma referência a esse atributo mapeado (sempre IdentityProvider no caso do Provisionamento JIT SAML, não atualize).

 
"refResourceType": "IdentityProvider",
idcsResourceType

O tipo do recurso do domínio de identidades para o qual estamos mapeando (sempre User no caso do Provisionamento JIT SAML, não atualize).

 
"idcsResourceType": "User",
direction

Direção do mapeamento, com relação ao recurso do domínio de identidades em questão (sempre inbound no caso do Provisionamento JIT SAML, não atualize).

 
"direction": "inbound",
refResourceID

O ID do recurso IdentityProvider que tem uma referência a esse recurso MappedAttribute (definido na criação, não atualizar).

 
"refResourceID": "<IDP Resource ID>",

Para atualizar os mapeamentos de atributo, primeiro você deve identificar o recurso MappedAttributes correto para seu IdP. Isso pode ser feito recuperando o recurso IdentityProvider e observando o atributo $ref da propriedade jitUserProvAttributes.

Por exemplo, você pode ter um recurso MappedAttributes, como https://<domainURL>/admin/v1/MappedAttributes/6533d475754845a8b0e971c48b87edda, que seria PATCH para atualizar sua propriedade attributeMappings.

Payload PATCH de Amostra para MappedAttributes


{
 "schemas": [
     "urn:ietf:params:scim:api:messages:2.0:PatchOp"
 ],    "Operations": [
     {
         "op": "replace",
         "path": "attributeMappings",
         "value": [
             {
                 "managedObjectAttributeName": "$(assertion.mail)",
                 "idcsAttributeName": "userName"
             },
             {
                 "managedObjectAttributeName": "$(assertion.firstname)",
                 "idcsAttributeName": "name.givenName"
             },
             {
                 "managedObjectAttributeName": "$(assertion.lastname)",
                 "idcsAttributeName": "name.familyName"
             },
             {
                 "managedObjectAttributeName": "$(assertion.mail)",
                 "idcsAttributeName": "emails[primary eq true and type eq \"work\"].value"
             }
         ]
     }
 ]
}

Uso de Mapeamento de Atributo de Provisionamento JIT SAML e Comportamento de Runtime

Se os valores de userName, name.givenName e name.familyName não estiverem presentes, haverá um erro no runtime, pois esses atributos são marcados como obrigatórios no esquema User. O mesmo se aplica ao endereço de e-mail principal, a menos que o tenant tenha sido configurado para tornar isso opcional.

No runtime, se qualquer valor de atributo de asserção não puder ser convertido em um tipo de dados que possa ser designado ao atributo do usuário para o qual ele está mapeado, haverá um erro e o SSO falhará.

Se vários mapeamentos de atributo forem configurados visando o mesmo atributo de usuário dos domínios de identidades, eles serão avaliados e executados na ordem da posição e somente o resultado do último mapeamento será retido.

Um atributo de asserção de entrada que não contém valores resultará na remoção do valor do atributo de usuário dos domínios de identidades mapeados correspondentes, se jitUserProvAttributeUpdateEnabled for true.

Os atributos de asserção SAML Emissor e Assunto NameID são suportados, mesmo que não apareçam no AttributeStatement. Elas podem ser mapeadas usando estas expressões reservadas:
  • ${assertion.fed.issuerid)
  • $(assertion.fed.nameidvalue)
Alguns atributos de esquema de usuário/conta de domínios de identidades não são permitidos para uso no Provisionamento JIT SAML:
  • Atributos confidenciais - ou seja, atributos marcados como "idcsSensitive: hash" ou "idcsSensitive: encrypt" no esquema
  • Atributos marcados como "idcsInternal: true" no esquema
  • Atributos que são readOnly
  • Todos os atributos que o User Sync não permite

Quando um usuário for criado usando o Provisionamento JIT SAML, os atributos a seguir serão definidos. Esses atributos não são configuráveis:

  • bypassNotification : true - Por exemplo, um e-mail de ativação de conta não será enviado ao usuário recém-criado.
  • syncedFromApp - Uma referência ao recurso do Provedor de Identidades correspondente ao emissor da asserção SAML de entrada.
Quando um usuário é criado usando o Provisionamento JIT SAML, o atributo isFederatedUser é definido como true por padrão. Esse comportamento pode ser alterado definindo o atributo isFederatedUser como false na configuração attributeMappings do Provisionamento JIT SAML.
Observação

Esse comportamento padrão (isFederatedUser = true) só se aplica à criação do usuário, não à atualização do usuário; a configuração attributeMappings se aplica à criação do usuário e à atualização do usuário.

Perguntas Frequentes

P: É obrigatório que os grupos estejam presentes nos domínios de identidades para atualizar a associação do grupo durante o Provisionamento JIT SAML?

R: Sim. Os grupos precisam ser sincronizados ou criados manualmente nos domínios de identidades antes que a associação do grupo seja atualizada. O Provisionamento JIT SAML não criará grupos em tempo real.

P: Posso mapear um literal no mapeamento de atributos? Por exemplo, quero mapear isFederatedUser = true durante a criação do usuário?

R: Sim.

P: Suportamos atributos de vários valores no mapeamento de atributos? Em caso afirmativo, aplicamos patch ao payload ou fazemos uma substituição?

R: Sim. Todos os valores do atributo de usuário do domínio de identidades são substituídos pelo resultado líquido do mapeamento do atributo Provisionamento JIT SAML.

P: Se um usuário for removido de um grupo no IdP, como trataremos isso? E se esse grupo for designado manualmente em domínios de identidades? Podemos configurar o comportamento de substituição versus patch?

A: A atribuição de grupo usando a atualização de Provisionamento JIT SAML pode ser configurada para ter o comportamento Mesclar ou Substituir, para as atribuições de grupo do usuário em geral. Por exemplo, se a atualização estiver configurada para Substituir, todas as designações de grupo manuais que não aparecerem na asserção IdP serão removidas.

P: Podemos configurar o Provisionamento JIT SAML para ocorrer somente durante a criação do usuário, mas não para atualizar o usuário posteriormente?

R: Sim. Se jitUserProvCreateUserEnabled for verdadeiro e jitUserProvAttributeUpdateEnabled for falso, o Provisionamento JIT SAML criará usuários se eles estiverem ausentes, mas não os atualizará em log-ins subsequentes.