Configuración de cuentas de invitados ISE con API REST

Introducción

Este documento describe cómo utilizar la función API de transferencia de estado representacional (REST) para realizar tareas relacionadas con invitados en Identity Services Engine (ISE). La API de invitado de Cisco es un conjunto de operaciones basado en REST que proporcionan acceso seguro HTTPS y autenticado para administrar usuarios invitados de Cisco. Con la API, se pueden crear, leer, actualizar, eliminar y buscar usuarios invitados.

Prerequisites

Requirements

Cisco recomienda que tenga conocimiento de estos temas:

• ISE
• Servicios RESTful externos
• Clientes REST como insomnio, RESTED, etc.

Componentes Utilizados

La información que contiene este documento se basa en las siguientes versiones de software y hardware.

• Cisco ISE, versión 2.6
• Cliente REST de insomnio v7.1.1

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. Si tiene una red en vivo, asegúrese de entender el posible impacto de cualquier comando.

Nota: El procedimiento es similar o idéntico para otras versiones de ISE. Puede utilizar estos pasos en todas las versiones 2.x del software ISE a menos que se indique lo contrario.

Antecedentes

Para utilizar la API, la autenticación de patrocinador y los servicios RESTful (ERS) externos habilitados deben configurarse en ISE. ERS admite la autenticación básica y se ejecuta sobre el puerto 9060. Las credenciales de autenticación están cifradas y forman parte del encabezado de solicitud. ERS requiere que el administrador de ISE asigne privilegios especiales a un usuario para realizar operaciones.

El documento cubrirá estos pasos de configuración:

1. Habilitar ERS en ISE

2. Configuración de una cuenta de administrador y de patrocinador para ERS

3. Crear una cuenta de invitado

4. Leer, actualizar, eliminar datos de invitados

Configurar

Habilitar ERS en ISE

Para utilizar la función REST API en ISE, ERS debe estar habilitado.

Vaya a Administration > System > Settings > ERS settings > Enable ERS for read/write como se muestra en la imagen.

Toda la información relacionada con ERS está disponible como Kit de desarrollo de software (SDK) en el puerto HTTPS 9060 de ISE. Se puede acceder a esto después de habilitar ERS e iniciar sesión con una cuenta de administrador con los privilegios de "ERS-Admin" o "ERS-Operator".

Configuración de la cuenta de administrador y patrocinador para ERS

Para utilizar ERS, ISE requiere una cuenta de administrador que tenga los privilegios de ERS-Admin o ERS-operador asignados. Es necesario crear cuentas de administrador y agregarlas a los grupos respectivos. Alternativamente, el acceso ERS también funciona para la cuenta Super-Admin.

Para utilizar las API para las funciones de invitado, el administrador de ERS requiere datos sin procesar de los portales como la ID del portal, los grupos de identidad de invitados, etc. Sin embargo, para leer/crear/actualizar o eliminar cualquier dato de invitado, se requiere una cuenta de patrocinador con el acceso de ERS habilitado.

• A los efectos de este documento, se utiliza una cuenta de usuario interna de ISE como patrocinador.
• Vaya a Administration > Identity Management > Identities y agregue un usuario de acceso a la red como se muestra en la imagen.

• Esta cuenta de usuario debe agregarse a uno de los grupos de patrocinadores.
• La cuenta de ejemplo se asigna al grupo de patrocinadores predeterminado denominado ALL_ACCOUNTS. 
• Para permitir el acceso de ERS para este grupo patrocinado, vaya a Centros de trabajo > Acceso de invitado > Portal y componentes > Grupos de patrocinadores y abra el grupo de patrocinadores asignado.
• Active la opción: Acceda a las cuentas de invitados de Cisco ISE mediante la interfaz programática (API REST de invitado), como se muestra en la imagen.

Crear una cuenta de invitado

Para crear una cuenta de invitado a través de la API, es necesario que la llamada de la API se realice a ISE como patrocinador y a través de un portal patrocinado que reconoce.

Paso 1. Para obtener los ID de portal de todos los portales del patrocinador preconfigurados en ISE, utilice cualquier cliente REST con la información proporcionada aquí:

Método	GET
URL	https://<ISE-IP>:9060/ers/config/padportal
Credenciales	Usar credenciales de administrador ERS
Encabezados	Tipo de contenido: application/xml Aceptar: application/xml

Resultado esperado:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:searchResult total="1"
xmlns:ns5="ers.ise.cisco.com"
xmlns:ers-v2="ers-v2"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="v2.ers.ise.cisco.com">
<ns3:resources>
<ns5:resource description="Default portal used by sponsors to create and manage accounts for authorized visitors to securely access the network" 
id="274a95f0-2e58-11e9-98fb-0050568775a3" name="Sponsor Portal (default)">
<link rel="self" href="https://10.127.197.186:9060/ers/config/sponsorportal/274a95f0-2e58-11e9-98fb-0050568775a3" type="application/xml"/>
</ns5:resource>
</ns3:resources>
</ns3:searchResult>

El valor de interés es la ID del portal del patrocinador que se pretende utilizar para crear usuarios invitados. El ID es "274a95f0-2e58-11e9-98fb-0050568775a3" en este ejemplo.

Paso 2. Utilice esta llamada API para crear una cuenta de invitado. El valor de portalID aquí es el que se obtiene del Paso 1.

Método	POST
URL	https://<ISE-IP>:9060/ers/config/guestuser/
Credenciales	Usar credenciales de cuenta de patrocinador
Encabezados	Tipo de contenido: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml Aceptar: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Cuerpo	<?xml version="1.0" encoding="UTF-8"?> <ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com"> <customFields> </customFields> <guestAccessInfo> <fromDate>25/04/2020 18:55</fromDate> <location>Delhi</location> <toDate>28/04/2020 19:55</toDate> <validDays>3</validDays> </guestAccessInfo> <guestInfo> <company>Cisco</company> <emailAddress>abcd@cisco.com</emailAddress> <firstName>Juan</firstName> <lastName>Hacer</lastName> <notificationLanguage>Inglés</notificationLanguage> <password>9618</password> <phoneNumber>999998877</phoneNumber> <smsServiceProvider>Predeterminado global</smsServiceProvider> <userName>johndoe</userName> </guestInfo> <guestType>Contratista (valor predeterminado)</guestType> <personaVisitada>abcd3@cisco.com</personaVisitada> <portalId>274a95f0-2e58-11e9-98fb-0050568775a3</portalId> <reasonForVisite>Visitar a Bob desde Contabilización</reasonForVisite> </ns2:usuario invitado>

Nota: El contenido del cuerpo que se muestra aquí se puede utilizar como plantilla (disponible también en SDK). Asegúrese de que el valor fromDate, toDate corresponde a un valor válidoDays. La ubicación, el tipo de invitado y otros valores deben ser válidos en relación con el ISE utilizado; sólo entonces la llamada se realizará correctamente.

Nota: Las credenciales utilizadas cuando realiza esta llamada deben ser una cuenta de patrocinador válida asignada a un grupo de patrocinadores. Las credenciales de administrador ERS aquí no funcionarán. Consulte la sección anterior de esta guía para obtener más detalles.

Resultado esperado:

Navegue hasta GUI de ISE > Informe de invitado maestro para verificar si se creó la cuenta:

Nota: No hay opción para especificar una combinación personalizada de nombre de usuario y contraseña por cuenta de invitado desde un portal de patrocinadores. Este método API se puede utilizar para cumplir ese requisito.

Leer, actualizar, eliminar datos de invitado

A continuación se muestran algunas llamadas de API de ejemplo para realizar varias acciones en los datos de invitado. Todas las opciones disponibles y sus formatos están disponibles en el SDK.

• Obtener detalles de la cuenta de usuario invitado por nombre:

Método	GET
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
Credenciales	Usar credenciales de cuenta de patrocinador
Encabezados	Tipo de contenido: application/xml Aceptar: application/xml

Resultado esperado:

200 OK

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns4:guestuser id="3b967932-86f8-11ea-aafe-72889dc971d1" name="johndoe"
xmlns:ers="ers.ise.cisco.com"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns4="identity.ers.ise.cisco.com">
<link rel="self" href="https://10.127.197.186:9060/ers/config/guestuser/name/johndoe" type="application/xml"/>
<customFields/>
<guestAccessInfo>
<fromDate>04/25/2020 18:55</fromDate>
<location>Delhi</location>
<toDate>04/28/2020 19:55</toDate>
<validDays>3</validDays>
</guestAccessInfo>
<guestInfo>
<company>Cisco</company>
<creationTime>04/25/2020 18:55</creationTime>
<emailAddress>abcd@cisco.com</emailAddress>
<enabled>false</enabled>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<password>9618</password>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>Global Default</smsServiceProvider>
<userName>johndoe</userName>
</guestInfo>
<guestType>Contractor (default)</guestType>
<personBeingVisited>abcd3@cisco.com</personBeingVisited>
<reasonForVisit>Visiting Bob from Accounting</reasonForVisit>
<sponsorUserId>1f7627f0-86f8-11ea-aafe-72889dc971d1</sponsorUserId>
<sponsorUserName>Sponsor_ERS</sponsorUserName>
<status>AWAITING_INITIAL_LOGIN</status>
</ns4:guestuser>

• Restablecer una contraseña de usuario invitado:

Esto requiere primero obtener el ID de invitado de la llamada y después utilizarlo en esta API. El ID de usuario invitado es "3b967932-86f8-11ea-aafe-72889dc971d1" en este ejemplo.

Método	PUT
URL	https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id}
Credenciales	Usar credenciales de cuenta de patrocinador
Encabezados	Tipo de contenido: application/xml Aceptar: application/xml

Este método no permite especificar la nueva contraseña. ISE devolverá el resultado con la nueva contraseña generada automáticamente.

Salida esperada:

200 OK

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:operationResult
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="ers.ise.cisco.com">
<attributesList>
<attribute name="password" value="2557"/>
</attributesList>
</ns3:operationResult>

•  Eliminar una cuenta de invitado por nombre:

Método	ELIMINAR
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
Credenciales	Usar credenciales de cuenta de patrocinador
Encabezados	Tipo de contenido: application/xml Aceptar: application/xml

Salida esperada:

Verificación

Actualmente, no hay un procedimiento de verificación disponible para esta configuración.

Troubleshoot

En esta sección se brinda información que puede utilizar para resolver problemas en su configuración.

Algunos errores comunes y sus posibles causas:

• Error al crear una cuenta de invitado:

     401 Unauthorized

     <message type="ERROR" code="CRUD operation exception">
    <title>Sponsor does not have permission to access REST Apis</title>
     </message>

Corregir: Esto significa que la cuenta del patrocinador utilizada para hacer la cuenta del invitado se asigna a un grupo de patrocinadores donde el acceso ERS no está habilitado. Edite el grupo de patrocinadores que corresponda a esto y habilite Access Cisco ISE Guest account con el uso de la interfaz programática (API REST de invitado).

   400 Bad Request

   <message type="ERROR" code="CRUD operation exception">
    <title>Creating GuestUser failed due to com.cisco.cpm.guestaccess.validation.GuestAccessValidationException: Portal not found for portal session e1fc15a7-a170-4d6a-b02c-0ab7b0bc54ff</title>

Corregir: El ID de portal introducido en la llamada no existe en ISE o es incorrecto. Desde la llamada 'Get' para el portal del patrocinador, busque la ID del portal correcta del portal.

• Códigos de respuesta API y sus posibles significados:

      200 (OK): Indica que la API REST llevó a cabo correctamente la acción deseada.

      201 (Creado): Indica que se ha creado un recurso dentro de una colección.

      204 (sin contenido): Esto suele enviarse como respuesta a las solicitudes PUT, POST o DELETE.

     400 (solicitud incorrecta): Código de error genérico para problemas como sintaxis de solicitud mal formada, parámetros no válidos, etc. Lea los detalles del mensaje si están disponibles para comprender la causa.

     401 (no autorizado): Esto indica que la acción se llevó a cabo con credenciales erróneas, no hay credenciales o la cuenta no está autorizada para realizar esta acción.

     500(Error interno del servidor): Indica un problema en el lado del servidor. Los registros de ISE pueden ayudar a comprender la causa.

Para obtener más detalles sobre el uso de la API REST para ISE, refiérase a la API REST de invitado.