Passar atributos personalizados do Azure AD como declarações de SAML do Twilio Flex

As propriedades de extensão do Azure AD só podem ser usadas como declarações SAML do aplicativo empresarial pela Política de mapeamento de declarações criada usando a API Graph ou o PowerShell. A interface do portal do Azure AD não é compatível com a adição de propriedades de extensão como declarações. Este guia usa a API Graph para orientar você no processo para criar uma propriedade de extensão do Azure AD, uma política de mapeamento de declarações e passar a propriedade como um atributo personalizado para os usuários do Flex.

Abrir o Microsoft Graph Explorer

1. Abra e faça login no Azure portal (Portal do Azure).
2. Em uma guia separada, abra o Microsoft Graph API Explorer, clique em "Sign in to Graph Explorer" (Faça login no Graph Explorer) e selecione a conta de administrador do Azure a ser usada no Graph Explorer.

   

3. Certifique‐se de concordar com os seguintes requisitos de permissões:

   

Coletar IDs de suporte

Precisaremos recuperar alguns IDs para usar nas próximas etapas: seu Service principal entity ID (ID da entidade principal do serviço) e seu Application entity ID (ID da entidade do aplicativo). Clique na respectiva guia para obter as instruções detalhadas.

Criar propriedade de extensão do Azure AD

Nesta seção, criaremos uma propriedade estendida (personalizada) para o aplicativo empresarial que podemos preencher para nossos usuários do Flex de destino.

Execute a seguinte consulta do Graph Explorer. Certifique‐se de:

• No campo URL, substitua <Application_Entity_ID> pelo ID da entidade do aplicativo que você anotou anteriormente.
• Clique na guia Request body (Corpo da solicitação) para adicionar o JSON no campo Request body (Corpo da solicitação). Substitua<Property_Name> pelo nome que deseja usar para a extensão.

Exemplo de solicitação

HTTP method: POST
API version: v1.0
Endpoint URL: https://graph.microsoft.com/v1.0/applications/<Application_Entity_ID>/extensionProperties
Request body: 
{
    "name": "<Property_Name>",
    "dataType": "String",
    "targetObjects": ["User"]
}

Clique em Run query (Executar consulta) e, na resposta JSON, copie e cole o valor "name" da nova propriedade de extensão para referência em etapas posteriores. Ela estará no formato "extension_<App_ID>_<Property_Name>".

Exemplo de resposta

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications('xxx')/extensionProperties/$entity",
    "id": "xxx",
    "deletedDateTime": null,
    "appDisplayName": "Twilio Flex testing",
    "dataType": "String",
    "isSyncedFromOnPremises": false,
    "name": "extension_xxx_language",
    "targetObjects": [
        "User"
    ]
}

Preencher a propriedade de extensão no usuário do Azure AD

Agora que criamos uma propriedade de extensão, vamos adicioná‐la a um usuário.

Execute a seguinte consulta do Graph Explorer. Certifique‐se de:

• No campo URL, você pode passar o ID do usuário ou o nome do usuário principal (UPN). Substitua <ID | UserPrincipalName> pelo ID do objeto ou pelo UPN do usuário do Azure AD que você deseja atualizar.
• Clique na guia Request body (Corpo da solicitação) para adicionar o JSON no campo Request body (Corpo da solicitação).
  • Substitua <extension_<App_ID>_<Property_Name> pelo nome da propriedade de extensão criada na etapa anterior.
  • Substitua "My Custom Value" pelo valor que deseja atribuir a esta propriedade.

Exemplo de solicitação

HTTP method: PATCH
API version: v1.0
Endpoint URL: https://graph.microsoft.com/v1.0/users/<ID | UserPrincipalName>
Request body: 
{
"extension_<App_ID>_<Property_Name>": "My Custom Value"
}

Clique em Run query (Executar consulta).

Exemplo de resposta

204 {}

Para confirmar que o usuário foi atualizado com sucesso, execute a seguinte consulta.

Exemplo de solicitação

HTTP method: GET
API version: beta
Endpoint URL: https://graph.microsoft.com/beta/users/<ID | UserPrincipalName>

Na resposta JSON, você deve ver a nova propriedade de extensão e o valor atribuído nas propriedades do usuário.

Exemplo de resposta

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
  "id": "xxxx",
  "deletedDateTime": null,
  "accountEnabled": true,
  "ageGroup": null,
  "businessPhones": [],
  "city": null,
  "createdDateTime": "2021-11-19T06:55:28Z",
  "creationType": null,
  "companyName": null,
  "consentProvidedForMinor": null,
  "country": null,
  "department": null,
  "displayName": "Test User",
  "employeeId": null,
  "employeeHireDate": null,
  "employeeType": null,
  "faxNumber": null,
  "givenName": "Test",
  "imAddresses": [],
  "infoCatalogs": [],
  "isManagementRestricted": null,
  "isResourceAccount": null,
  "jobTitle": null,
  "legalAgeGroupClassification": null,
  "mail": null,
  "mailNickname": "testuser",
  "mobilePhone": null,
  "onPremisesDistinguishedName": null,
  "officeLocation": null,
  "onPremisesDomainName": null,
  "onPremisesImmutableId": null,
  "onPremisesLastSyncDateTime": null,
  "onPremisesSecurityIdentifier": null,
  "onPremisesSamAccountName": null,
  "onPremisesSyncEnabled": null,
  "onPremisesUserPrincipalName": null,
  "otherMails": [],
  "passwordPolicies": null,
  "postalCode": null,
  "preferredDataLocation": null,
  "preferredLanguage": null,
  "proxyAddresses": [],
  "refreshTokensValidFromDateTime": "2021-11-24T19:10:02Z",
  "showInAddressList": null,
  "signInSessionsValidFromDateTime": "2021-11-24T19:10:02Z",
  "state": null,
  "streetAddress": null,
  "surname": "User",
  "usageLocation": null,
  "userPrincipalName": "testuser@admintwilio.onmicrosoft.com",
  "externalUserState": null,
  "externalUserStateChangeDateTime": null,
  "userType": "Member",
  "extension_xxx_language": "Russian",
  "employeeOrgData": null,
  "passwordProfile": null,
  "assignedLicenses": [],
  "assignedPlans": [],
  "deviceKeys": [],
  "identities": [
      {
          "signInType": "userPrincipalName",
          "issuer": "admintwilio.onmicrosoft.com",
          "issuerAssignedId": "testuser@admintwilio.onmicrosoft.com"
      }
  ],
  "onPremisesExtensionAttributes": {
      "extensionAttribute1": null,
      "extensionAttribute2": null,
      "extensionAttribute3": null,
      "extensionAttribute4": null,
      "extensionAttribute5": null,
      "extensionAttribute6": null,
      "extensionAttribute7": null,
      "extensionAttribute8": null,
      "extensionAttribute9": null,
      "extensionAttribute10": null,
      "extensionAttribute11": null,
      "extensionAttribute12": null,
      "extensionAttribute13": null,
      "extensionAttribute14": null,
      "extensionAttribute15": null
  },
  "onPremisesProvisioningErrors": [],
  "provisionedPlans": []
}

Criar uma Política de mapeamento de declarações

Agora podemos criar nossa política de mapeamento de declarações. Para obter um exemplo de definição de declaração e um passo a passo das principais propriedades de configuração, consulte "Exemplo de definição de política de declarações".

Execute a seguinte consulta do Graph Explorer. Certifique‐se de:

• Clique na guia Request body (Corpo da solicitação) e insira o JSON no campo Request body (Corpo da solicitação). Faça as seguintes alterações:
  • Substitua o <Claim_Policy_Name> pelo nome que deseja usar para esta política.
  • Substitua o exemplo de JSON com escape e minimizado pela definição da política de declarações. Em sua definição, certifique‐se de:
    • Atualizar "ExtensionID" e "SamlClaimType" com seus valores.
    • Minimize e escape o JSON. Há várias ferramentas online úteis para minimizar e escapar o JSON.

Exemplo de solicitação

HTTP method: POST
API version: v1.0
Endpoint URL: https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies
Request body: 
{
    "definition": [
        "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\":\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier\"},{\"Source\":\"user\",\"ID\":\"displayname\",\"SamlClaimType\":\"full_name\"},{\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\":\"roles\"},{\"Source\":\"user\",\"ID\":\"mail\",\"SamlClaimType\":\"email\"},{\"Source\":\"user\",\"ExtensionID\":\"extension_<App_ID>_<Property_Name>\",\"SamlClaimType\":\"<Claim_Attribute_Name>\"}]}}"
    ],
    "displayName": "<Claim_Policy_Name>",
    "isOrganizationDefault": false
}

Clique em Run query (Executar consulta). Na resposta JSON, copie o valor de "id" da política de mapeamento de declarações e cole‐o em algum lugar que você possa referenciá‐lo.

Exemplo de resposta

201 Created
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/claimsMappingPolicies/$entity",
    "id": "xxx",
    "deletedDateTime": null,
    "definition": [
        "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\":\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier\"},{\"Source\":\"user\",\"ID\":\"displayname\",\"SamlClaimType\":\"full_name\"},{\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\":\"roles\"},{\"Source\":\"user\",\"ID\":\"mail\",\"SamlClaimType\":\"email\"},{\"Source\":\"user\",\"ExtensionID\":\"extension_xxx_exampleproperty\",\"SamlClaimType\":\"exampleclaimattribute\"}]}}"
    ],
    "displayName": "Example Claim Policy Name",
    "isOrganizationDefault": false
}

Atribuir Política de mapeamento de declarações ao aplicativo

Por fim, podemos atribuir a Política de mapeamento de declarações que acabamos de criar ao seu aplicativo empresarial.

Execute a seguinte consulta do Graph Explorer. Certifique‐se de:

• Substitua <Service_Principal_Entity_ID> por seu Service Principal Entity ID (ID da entidade principal do serviço) recuperado anteriormente na seção "Coletar IDs de suporte".
• Clique na guia Request body (Corpo da solicitação) para adicionar o JSON no campo Request body (Corpo da solicitação).
  • Substitua <Claims_Mapping_Policy_ID> pelo ID que você anotou anteriormente.

Exemplo de solicitação

HTTP method: POST
API version: v1.0
Endpoint URL: https://graph.microsoft.com/v1.0/servicePrincipals/<Service_Principal_Entity_ID>/claimsMappingPolicies/$ref
Request body:
{
    "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<Claims_Mapping_Policy_ID>"
}

• Clique em Run query (Executar consulta) e, na resposta JSON, procure o objeto de matriz cujo valor "appDisplayName" corresponda ao nome do aplicativo empresarial.
• Copie o valor de "id" e cole em qualquer lugar que possa referenciá‐lo.

Exemplo de resposta

204 {}

Testar nova Política de mapeamento de declarações

Com todas as seções acima concluídas, agora você está pronto para fazer login no Flex e testar a nova política de mapeamento de declarações.

1. Navegue até a página de configurações Single Sign-On do Console Flex.
2. Quando redirecionado para o Azure AD para autenticação, faça login com a conta de usuário do AD à qual você atribuiu a propriedade de extensão anteriormente neste guia.
3. Depois de fazer login e de o Flex UI (IU do Flex) ter sido carregada, verifique os atributos do trabalhador do TaskRouter no Console da Twilio (TaskRouter -> Workspace -> Workers).

   Se você estiver vendo todos os atributos esperados definidos na Política de mapeamento de declarações, você configurou com êxito suas declarações personalizadas.

   Se algum atributo estiver faltando, examine o payload da resposta SAML após a autenticação no Azure AD. Certifique‐se de que todos os atributos estejam incluídos e que eles tenham valores e que o parâmetro "Name" esteja correto para cada um deles.

   Como explicado no Guia do SSO do Twilio Flex Azure AD, se o parâmetro "Name" em um atributo incluir o namespace, ele será ignorado. Verifique novamente a definição da Política de mapeamento de declarações e certifique‐se de que o "SamlClaimType" esteja definido sem um namespace para cada solicitação que você deseja capturar como um atributo do trabalhador do TaskRouter.

Cancelar a atribuição da Política de mapeamento de declarações do aplicativo

Se você não precisa mais ou deseja passar as propriedades de extensão personalizadas como declarações SAML e deseja gerenciar as declarações no portal Azure AD, ou você deseja atribuir uma Política de mapeamento de declarações diferente ao seu aplicativo empresarial, será necessário cancelar a atribuição da Política de mapeamento de declarações atual do aplicativo.

Execute a seguinte consulta do Graph Explorer. Certifique‐se de:

• No campo URL, substitua <Service_Principal_Entity_ID> por seu Service Principal Entity ID (ID da entidade principal do serviço) recuperado anteriormente na seção "Coletar IDs de suporte".

Exemplo de solicitação

HTTP method: DELETE
API version: v1.0
Endpoint URL: https://graph.microsoft.com/v1.0/servicePrincipals/<Service_Principal_Entity_ID>/claimsMappingPolicies/<Claims_Mapping_Policy_ID>/$ref

Clique em Run query (Executar consulta).

Exemplo de resposta

204 {}

Para verificar se não há Políticas de mapeamento de declarações atribuídas ao seu aplicativo, execute a seguinte consulta usando o mesmo Service Principal Entity ID (ID da entidade principal do serviço).

Exemplo de solicitação

HTTP method: GET
API version: 1.0
Endpoint URL: https://graph.microsoft.com/v1.0/servicePrincipals/<Service_Principal_Entity_ID>/claimsMappingPolicies

Na resposta JSON, a propriedade "value" agora deve mostrar uma matriz vazia.

Exemplo de definição de Política de declarações

Para o objeto JSON de definição de solicitação em "Criar uma política de mapeamento de declarações", vamos analisar uma definição de exemplo e algumas propriedades de configuração de chave.

Vamos dar uma olhada nas principais propriedades na definição de exemplo: