Enviar atributos personalizados de Azure AD como notificaciones SAML de Twilio Flex

Las propiedades de la extensión Azure AD solo se pueden utilizar como notificaciones SAML de aplicación empresarial a través de una política de asignación de notificaciones creada mediante la API de Graph o PowerShell. La interfaz del portal de Azure AD no admite la adición de propiedades de extensión como notificaciones. En esta guía, se utiliza la API de Graph para guiarte por el proceso de creación de una propiedad de extensión Azure AD, una política de asignación de notificaciones y el envío de la propiedad como un atributo personalizado para los usuarios de Flex.

Abrir Graph Explorer de Microsoft

1. Abre e inicia sesión en el portal Azure.
2. En una pestaña independiente, abre la API de Graph Explorer de Microsoft, haz clic en “Sign in to Graph Explorer” (Iniciar sesión en el Explorador de gráficos) y selecciona la cuenta de administrador de Azure que deseas utilizar para Graph Explorer.

   

3. Asegúrate de aceptar los siguientes requisitos de permisos:

   

Recopilar ID de apoyo

Necesitaremos recuperar algunos ID para utilizarlos en los siguientes pasos: tu ID de entidad principal de servicio y tu ID de entidad de aplicación. Haz clic en la pestaña correspondiente para obtener instrucciones detalladas.

Crear propiedad de extensión de Azure AD

En esta sección, vamos a crear una propiedad extendida (personalizada) para la aplicación empresarial, la cuas después podemos rellenar para nuestros usuarios de Flex de destino.

Ejecuta la siguiente consulta de Graph Explorer. Asegúrate de hacer esto:

• En el campo URL, reemplaza <Application_Entity_ID> con el ID de entidad de aplicación que anotaste anteriormente.
• Haz clic en la pestaña Request body (Cuerpo de solicitud) para agregar el JSON en el campo Request body. Reemplaza <Property_Name> con el nombre que deseas utilizar para la extensión.

Solicitud de ejemplo

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"]
}

Haz clic en Run query (Ejecutar consulta) y, en la respuesta JSON, copia y pega el valor “name” de la nueva propiedad de extensión como referencia en pasos posteriores. Tendrá el formato “extension_<App_ID>_<Property_Name>”.

Respuesta de ejemplo

{
    "@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"
    ]
}

Rellenar propiedad de extensión en el usuario de Azure AD

Ahora que hemos creado una propiedad de extensión, agreguémosla a un usuario.

Ejecuta la siguiente consulta de Graph Explorer. Asegúrate de hacer esto:

• En el campo URL, puedes ingresar el ID de usuario o el nombre principal de usuario (UPN). Reemplaza <ID | UserPrincipalName> con el ID de objeto o el UPN del usuario de Azure AD que deseas actualizar.
• Haz clic en la pestaña Request body (Cuerpo de solicitud) para agregar el JSON en el campo Request body.
  • Reemplaza <extension_<App_ID>_<Property_Name> con el nombre de la propiedad de extensión creada en el paso anterior.
  • Reemplaza “My Custom Value” (Mi valor personalizado) por el valor que deseas asignar a esta propiedad.

Solicitud de ejemplo

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"
}

Haz clic en Run query (Ejecutar consulta).

Respuesta de ejemplo

204 {}

Para confirmar que el usuario se actualizó correctamente, ejecuta la siguiente consulta.

Solicitud de ejemplo

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

En la respuesta JSON, deberías poder ver la nueva propiedad de extensión y el valor asignado en las propiedades del usuario.

Respuesta de ejemplo

{
  "@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": []
}

Crear una política de asignación de notificaciones

Ahora podemos crear nuestra política de asignación de notificaciones. Para obtener un ejemplo de definición de notificacion y un tutorial de sus propiedades de configuración clave, consulta “Definición de política de notificaciones de ejemplo”.

Ejecuta la siguiente consulta de Graph Explorer. Asegúrate de hacer esto:

• Haz clic en la pestaña Request body (Cuerpo de solicitud) e ingresa el JSON en el campo Request body. Realiza los siguientes cambios:
  • Reemplaza <Claim_Policy_Name> por el nombre que deseas utilizar para esta política.
  • Reemplaza el ejemplo JSON minimizado y corregido con la definición de la política de afirmaciones. En la definición, asegúrate de hacer esto:
    • Actualiza “ExtensionID” y “SamlClaimType” con tus valores.
    • Minifica y corrige el archivo JSON. Hay varias herramientas útiles en línea para minificar el JSON y corregirlo.

Solicitud de ejemplo

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
}

Haz clic en Run query (Ejecutar consulta). En la respuesta JSON, copia el valor de “id” de la política de asignación de notificaciones y pégalo en algún lugar que puedas consultar.

Respuesta de ejemplo

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
}

Asignar política de asignación de notificaciones a la aplicación

Finalmente podemos asignar la política de asignación de notificaciones que acabamos de crear a tu aplicación empresarial.

Ejecuta la siguiente consulta de Graph Explorer. Asegúrate de hacer esto:

• Reemplaza <Service_Principal_Entity_ID> por la ID de entidad principal de servicio recuperado anteriormente en la sección “Recopilar ID de apoyo”.
• Haz clic en la pestaña Request body (Cuerpo de solicitud) para agregar el JSON en el campo Request body.
  • Reemplaza <Claims_Mapping_Policy_ID> por el ID que anotaste anteriormente.

Solicitud de ejemplo

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>"
}

• Haz clic en Run query (Ejecutar consulta) y, en la respuesta JSON, busca el objeto de matriz cuyo valor “appDisplayName” coincida con el nombre de la aplicación empresarial.
• Copia el valor de “id” y pégalo en algún lugar que puedas consultar.

Respuesta de ejemplo

204 {}

Probar la nueva política de asignación de notificaciones

Una vez completadas todas las secciones anteriores, estarás listo para iniciar sesión en Flex y probar la nueva política de asignación de notificaciones.

1. Ve a la página de configuración Flex Console Single Sign-On (Inicio de sesión único en consola Flex).
2. Cuando te redirijan a Azure AD para fines de autenticación, inicia sesión con la cuenta de usuario de AD a la que asignaste la propiedad de extensión anteriormente en esta guía.
3. Después de iniciar sesión y una vez que se cargue la Flex UI (interfaz de usuario de Flex), comprueba los atributos de trabajador de TaskRouter en la consola de Twilio (TaskRouter -> Workspace [Espacio de trabajo] -> Workers [Trabajadores]).

   Si ves todos los atributos esperados que has definido en la política de asignación de notificaciones, significa que configuraste correctamente las notificaciones personalizadas.

   Si falta algún atributo, examina la carga útil de respuesta SAML después de autenticarte en Azure AD. Asegúrate de que todos los atributos están incluidos y tienen valores, y de que el parámetro “Name” (Nombre) sea correcto para cada uno de ellos.

   Como se explica en la guía de SSO de Azure AD de Twilio Flex, si el parámetro “Name” de un atributo incluye el espacio de nombres, este se ignorará. Vuelve a comprobar la definición de la política de asignación de notificaciones y asegúrate de que el campo “SamlClaimType” está definido sin un espacio de nombres para cada notificación que desees capturar como atributo de trabajador de TaskRouter.

Desasignar una política de asignación de notificaciones de la aplicación

Si ya no necesitas o deseas enviar propiedades de extensión personalizadas como notificaciones SAML y deseas administrar notificaciones en el portal de Azure AD, o bien deseas asignar una política de asignación de notificaciones distinta a la aplicación empresarial, deberás anular la asignación de la actual política de asignación de notificaciones de la aplicación.

Ejecuta la siguiente consulta de Graph Explorer. Asegúrate de hacer esto:

• En el campo URL, reemplaza <Service_Principal_Entity_ID> por la ID de entidad principal de servicio recuperado anteriormente en la sección “Recopilar ID de apoyo”.

Solicitud de ejemplo

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

Haz clic en Run query (Ejecutar consulta).

Respuesta de ejemplo

204 {}

Para comprobar que no haya políticas de asignación de notificaciones asignadas a tu aplicación, ejecuta la siguiente consulta con el mismo ID de entidad principal de servicio.

Solicitud de ejemplo

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

En la respuesta JSON, la propiedad “value” (valor) debería mostrar ahora un arreglo vacío.

Ejemplo de definición de política de notificaciones

Para el objeto JSON de definición de notificación en “Crear una política de asignación de notificaciones”, veamos un ejemplo de definición y algunas propiedades clave de configuración.

Echemos un vistazo a las propiedades clave en la definición de ejemplo: