Configurar contas de convidado ISE com API REST

Introduction

Este documento descreve como usar o recurso API de Transferência de Estado Representacional (REST) para executar tarefas relacionadas a convidados no Identity Services Engine (ISE). A API de convidado da Cisco é um conjunto de operações baseado em REST que fornece HTTPS seguro e acesso autenticado para gerenciar usuários convidados da Cisco. Com a API, é possível criar, ler, atualizar, excluir e pesquisar usuários convidados.

Prerequisites

Requirements

A Cisco recomenda que você conheça estes tópicos:

• ISE
• Serviços RESTful externos
• Clientes REST como Insônia, RESTED etc.

Componentes Utilizados

As informações neste documento são baseadas nestas versões de software e hardware:

• Cisco ISE, versão 2.6
• Insônia cliente REST 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. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Note: O procedimento é semelhante ou idêntico para outras versões do ISE. Você pode usar estas etapas em todas as versões 2.x do software ISE, a menos que declarado de outra forma.

Informações de Apoio

Para usar a API, o External RESTful Services (ERS) está habilitado e a autenticação do patrocinador precisa ser configurada no ISE. O ERS suporta autenticação básica e é executado na porta 9060. As credenciais de autenticação são criptografadas e fazem parte do cabeçalho da solicitação. O ERS exige que o administrador do ISE atribua privilégios especiais a um usuário para executar operações.

O documento abordará estas etapas de configuração:

1. Ativar ERS no ISE

2. Configurar conta de administrador e patrocinador para ERS

3. Criar uma conta de convidado

4. Ler, atualizar, excluir dados de convidado

Configurar

Ativar ERS no ISE

Para usar o recurso de API REST no ISE, o ERS deve estar ativado.

Navegue até Administration > System > Settings > ERS settings > Enable ERS for read/write conforme mostrado na imagem.

Todas as informações relacionadas ao ERS estão disponíveis como um Software Development Kit (SDK) na porta HTTPS 9060 do ISE. Isso pode ser acessado depois que você habilitar ERS e fazer login com uma conta admin com os privilégios de "ERS-Admin" ou "ERS-Operator".

Configurar conta de administrador e patrocinador para ERS

Para usar ERS, o ISE requer uma conta de administrador que tenha os privilégios de ERS-Admin ou ERS-operator atribuídos a ele. As contas administrativas precisam ser criadas e adicionadas aos respectivos grupos. Como alternativa, o acesso ERS também funciona para a conta Super-Admin.

Para usar APIs para recursos de convidados, o administrador ERS requer dados brutos dos portais, como o ID do portal, grupos de identidade de convidado etc. No entanto, para ler/criar/atualizar ou excluir dados de convidado, é necessária uma conta de patrocinador com acesso ERS ativado.

• Para o propósito deste documento, uma conta de usuário interna do ISE é usada como patrocinador.
• Navegue até Administration > Identity Management > Identities e adicione um usuário de acesso à rede como mostrado na imagem.

• Essa conta de usuário deve ser adicionada a um dos grupos de patrocinadores.
• A conta de exemplo é mapeada para o grupo patrocinador padrão chamado ALL_ACCOUNTS. 
• Para permitir o acesso de ERS para esse grupo patrocinado, vá para Centros de Trabalho > Acesso para Convidado > Portal & Components > Grupos de Patrocinadores e abra o grupo de patrocinadores designado.
• Ative a opção: Acesse as contas de convidado do Cisco ISE com o uso da interface programática (API REST de convidado) como mostrado na imagem.

Criar uma conta de convidado

Para criar uma conta de convidado por meio da API, é necessário que a chamada da API seja feita para o ISE como um patrocinador e por meio de um portal patrocinado que ele reconhece.

Etapa 1. Para buscar as IDs do portal de todos os portais patrocinadores pré-configurados no ISE, use qualquer cliente REST com as informações fornecidas aqui:

Método	GET
URL	https://<ISE-IP>:9060/ers/config/esponsorportal
Credenciais	Usar credenciais ERS Admin
Cabeçalhos	Tipo de conteúdo: aplicativo/xml Aceitar: aplicativo/xml

Saída esperada:

<?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>

O valor do interesse é a ID do portal do patrocinador que deve ser usada para criar usuários convidados. O ID é "274a95f0-2e58-11e9-98fb-005056877a3" neste exemplo.

Etapa 2. Use esta chamada de API para criar uma conta de convidado. O valor do ID do portal aqui é o obtido na Etapa 1.

Método	POST
URL	https://<ISE-IP>:9060/ers/config/guestuser/
Credenciais	Usar credenciais de conta do patrocinador
Cabeçalhos	Tipo de conteúdo: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml Aceitar: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Corpo	<?xml version="1.0" encoding="UTF-8"?> <ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com"> <Campos personalizados> </customFields> <guestAccessInfo> <fromDate>25/04/2020 18:55</fromDate> <location>Deli</location> <toDate>28/04/2020 19:55</toDate> <validDays>3</validDays> </guestAccessInfo> <guestInfo> <empresa>Cisco</empresa> <emailAddress>abcd@cisco.com</emailAddress> <firstName>John</firstName> <lastName>Doe</lastName> <notificationLanguage>Inglês</notificationLanguage> <password>9618</password> <phoneNumber>999998877</phoneNumber> <smsServiceProvider>Padrão global</smsServiceProvider> <userName>johndoe</userName> </guestInfo> <guestType>Contratante (padrão)</guestType> <pessoaSendoVisitada>abcd3@cisco.com</pessoaSendoVisitada> <portalId>274a95f0-2e58-11e9-98fb-0050568775a3</portalId> <reasonForVisit>Visitando Bob a partir de Accounting</reasonForVisit> </ns2:guestuser>

Note: O conteúdo do corpo mostrado aqui pode ser usado como um modelo (disponível também no SDK). Certifique-se de que FromDate, toDate correspondem a validDays. O local, o tipo de convidado e outros valores devem ser válidos em referência ao ISE usado, somente então a chamada será bem-sucedida.

Note: As credenciais usadas ao fazer esta chamada devem ser uma conta de patrocinador válida mapeada para um grupo de patrocinadores. As credenciais de administrador ERS aqui não funcionarão. Consulte a seção anterior deste guia para obter mais detalhes.

Saída esperada:

Navegue até GUI do ISE > Master GuestReport para verificar se a conta foi criada:

Note: Não há opção para especificar uma combinação personalizada de nome de usuário e senha por conta de convidado em um portal do patrocinador. Esse método de API pode ser usado para atender a esse requisito.

Ler, Atualizar, Excluir Dados de Convidado

Aqui estão alguns exemplos de chamadas à API para executar várias ações em dados de convidados. Todas as opções disponíveis e seus formatos estão disponíveis no SDK.

• Obter detalhes da conta de usuário convidado por nome:

Método	GET
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
Credenciais	Usar credenciais de conta do patrocinador
Cabeçalhos	Tipo de conteúdo: aplicativo/xml Aceitar: aplicativo/xml

Saída esperada:

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>

• Redefinir uma senha de usuário convidado:

É necessário primeiro buscar a ID do convidado da chamada e usá-la nesta API. A ID do usuário do convidado é "3b967932-86f8-11ea-aafe-72889dc971d1" neste exemplo.

Método	PUT
URL	https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id}
Credenciais	Usar credenciais de conta do patrocinador
Cabeçalhos	Tipo de conteúdo: aplicativo/xml Aceitar: aplicativo/xml

Este método não permite especificar a nova senha. O ISE retornará a saída com a nova senha autogerada.

Saída 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>

•  Excluir uma conta de convidado por nome:

Método	DELETE
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
Credenciais	Usar credenciais de conta do patrocinador
Cabeçalhos	Tipo de conteúdo: aplicativo/xml Aceitar: aplicativo/xml

Saída esperada:

Verificar

No momento, não há procedimento de verificação disponível para esta configuração.

Troubleshoot

Esta seção disponibiliza informações para a solução de problemas de configuração.

Alguns erros comuns e suas possíveis causas:

• Falha na criação de uma conta de convidado com erro:

     401 Unauthorized

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

Reparar: Isso significa que a conta de patrocinador usada para fazer com que a conta de convidado seja mapeada para um grupo de patrocinadores em que o acesso ERS não está ativado. Edite o grupo de patrocinadores que corresponde a isso e habilite as contas de convidado do Access Cisco ISE com o uso da interface programática (API REST de convidado).

   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>

Reparar: A ID do portal inserida na chamada não existe no ISE ou está incorreta. A partir da chamada 'Obter' para o portal do patrocinador, busque a ID do portal correta do portal.

• Códigos de resposta de API e seus possíveis significados:

      200 (OK): Indica que a API REST executou com êxito a ação desejada.

      201 (Criado): Indica que um recurso foi criado dentro de uma coleção.

      204 (Sem Conteúdo): Geralmente, isso é enviado como resposta a solicitações PUT, POST ou DELETE.

     400 (solicitação incorreta): Código de erro genérico para problemas como sintaxe de solicitação mal formada, parâmetros inválidos etc. Leia os detalhes da mensagem se disponíveis para entender a causa.

     401(Não autorizado): Isso indica que a ação foi realizada com credenciais incorretas, sem credenciais ou que a conta não está autorizada a executar esta ação.

     500(Erro interno do servidor): Indica um problema no lado do servidor. Os registros no ISE podem ajudar a entender a causa.

Para obter mais detalhes sobre o uso de API REST para ISE, consulte API REST de convidado.