Detalhes do serviço PAM REST API

As seções a seguir discutem detalhes da API REST do Microsoft Identity Manager (MIM) Privileged Access Management (PAM).

Cabeçalhos de solicitação HTTP

As solicitações HTTP enviadas para a API devem incluir os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho	Descrição
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.
Tipo de conteúdo	Obrigatório se o pedido tiver um corpo. Deve ser definido como application/json.
Tamanho do conteúdo	Obrigatório se o pedido tiver um corpo.
Biscoitos	O cookie de sessão. Pode ser necessário dependendo do 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	Descrição
Tipo de conteúdo	A API sempre retorna application/json.
Tamanho do conteúdo	O comprimento do corpo da solicitação, se presente, em bytes.

Versionamento

A versão atual da API é 1. A versão da API pode ser especificada por meio de um parâmetro de consulta na URL da solicitação, como no exemplo a seguir: http://localhost:8086/api/pamresources/pamrequests?v=1 Se a versão não for especificada na solicitação, a solicitação será executada em relação à versão lançada mais recentemente da API.

Segurança

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

HTTPS (TLS) é suportado, mas deve ser configurado manualmente no IIS. Para obter informações, consulte: Implementar SSL (Secure Sockets Layer) para o Portal FIM na Etapa 9: Executar tarefas pós-instalação do FIM 2010 R2 no Guia do laboratório de teste do FIM 2010 R2.

Você pode gerar um novo certificado de servidor SSL executando o seguinte comando no prompt de comando 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 usado para testar um aplicativo Web que usa SSL em um servidor Web onde a URL é test.cwap.com. O OID definido pela opção identifica o -eku certificado como um certificado de servidor SSL. O certificado é armazenado na minha loja e está disponível no nível da máquina. Você pode exportar o certificado do snap-in de Certificados no mmc.exe.

Acesso entre domínios (CORS)

O CORS é suportado, mas deve ser configurado manualmente no IIS. Adicione os seguintes elementos ao arquivo de web.config da API implantada 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> 

Tratamento de erros

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

Código de estado de HTTP	Descrição
401	Não autorizado
403	Proibido
408	Tempo de Espera Excedido
500	Erro interno do servidor
503	Serviço Indisponível

Filtragem

As solicitações PAM REST API podem incluir filtros para especificar as propriedades que devem ser incluídas na resposta. A sintaxe do filtro é baseada em expressões OData.

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

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

As seguintes solicitações de exemplo incluem filtros:

• Esta solicitação retorna todas as solicitações 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'

• Esta solicitação retorna a função Pam com o nome de exibição "Acesso ao arquivo SQL": http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'