Detalhes do serviço da API REST de PAM

  • Artigo

As secções seguintes abordam os detalhes da API REST de Gestão de Acesso Privilegiado (PAM) do Microsoft Identity Manager (MIM).

Cabeçalhos de pedido HTTP

Os pedidos HTTP enviados para a API devem incluir os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho Description
Autorização Obrigatório. O conteúdo depende do método de autenticação, que é configurável e pode ser baseado em WIA (Autenticação Integrada do Windows) ou ADFS.
Content-Type Necessário se o pedido tiver um corpo. Tem de estar definido como application/json.
Comprimento do Conteúdo Necessário se o pedido tiver um corpo.
Cookie O cookie da sessão. Pode ser necessário consoante o método de autenticação.

Cabeçalhos de resposta HTTP

As respostas HTTP devem incluir os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho Description
Content-Type A API devolve application/jsonsempre .
Comprimento do Conteúdo O comprimento do corpo do pedido, se estiver presente, em bytes.

Controlo de versões

A versão atual da API é 1. A versão da API pode ser especificada através de um parâmetro de consulta no URL do pedido, como no exemplo seguinte: http://localhost:8086/api/pamresources/pamrequests?v=1 se a versão não for especificada no pedido, o pedido é executado na versão lançada mais recentemente da API.

Segurança

O acesso à API requer Autenticação Integrada do Windows (IWA). Isto deve ser configurado manualmente no IIS antes da instalação do Microsoft Identity Manager (MIM).

O HTTPS (TLS) é suportado, mas deve ser configurado manualmente no IIS. Para obter informações, consulte: Implementar Secure Sockets Layer (SSL) para o Portal do FIM no Passo 9: Executar Tarefas Pós-Instalação do FIM 2010 R2 no Guia do Laboratório de Teste do FIM 2010 R2.

Pode gerar um novo certificado de servidor SSL ao executar o seguinte comando na Linha de Comandos do Visual Studio:

Makecert -r -pe -n CN="test.cwap.com" -b 05/10/2014 -e 12/22/2048 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localmachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12

O comando cria um certificado autoassinado que pode ser utilizado para testar uma aplicação Web que utiliza SSL num servidor Web onde o URL é test.cwap.com. O OID definido pela opção -eku identifica o certificado como um certificado de servidor SSL. O certificado é armazenado no meu arquivo e está disponível ao nível do computador. Pode exportar o certificado a partir do snap-in Certificados no mmc.exe.

Acesso entre Domínios (CORS)

O CORS é suportado, mas deve ser configurado manualmente no IIS. Adicione os seguintes elementos ao ficheiro de web.config da API implementado para configurar a API para permitir chamadas entre domínios:

<system.webServer>       
    <httpProtocol> 
        <customHeaders> 
            <add name="Access-Control-Allow-Credentials" value="true"  /> 
            <add name="Access-Control-Allow-Headers" value="content-type" /> 
            <add name="Access-Control-Allow-Origin" value="http://<hostname>:8090" /> 
        </customHeaders> 
    </httpProtocol> 
</system.webServer>

Processamento de erros

A API devolve respostas de erro HTTP para indicar condições de erro. Os erros são compatíveis com OData. A tabela seguinte mostra os códigos de erro que podem ser devolvidos a um cliente:

Código de estado de HTTP Descrição
401 Não autorizado
403 Proibido
408 Tempo Limite do Pedido
500 Erro de Servidor Interno
503 Serviço Indisponível

Filtragem

Os pedidos da API REST de PAM podem incluir filtros para especificar as propriedades que devem ser incluídas na resposta. A sintaxe do filtro baseia-se em expressões OData.

Os filtros podem especificar qualquer uma das propriedades de Pedidos de PAM, Funções de PAM. ou Pedidos de PAM Pendentes. Por exemplo: ExpirationTime, DisplayName ou qualquer outra propriedade válida de um Pedido de PAM, Função de PAM ou Pedido Pendente.

A API suporta os seguintes operadores em expressões de filtro: And, Equal, NotEqual, GreaterThan, LessThan, GreaterThenOrEqueal e LessThanOrEqual.

Os seguintes pedidos de exemplo incluem filtros:

  • Este pedido devolve todos os Pedidos de PAM entre datas específicas: http://localhost:8086/api/pamresources/pamrequests?$filter=ExpirationTime gt datetime'2015-01-09T08:26:49.721Z' and ExpirationTime lt datetime'2015-02-10T08:26:49.722Z'

  • Este pedido devolve a Função Pam com o nome a apresentar "Acesso a Ficheiros SQL": http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'