Detalhes do serviço da API REST do PAM

Artigo
09/14/2023

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

Cabeçalhos de solicitação HTTP

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

parâmetro	Descrição
Autorização	Obrigatórios. 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 a solicitação tiver um corpo. Deve ser definido como `application/json`.
Content-Length	Obrigatório se a solicitação tiver um corpo.
Cookie	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 (essa lista não é exaustiva):

parâmetro	Descrição
Tipo de conteúdo	A API sempre retorna `application/json`.
Content-Length	O comprimento do corpo da solicitação, se presente, em bytes.

Controle de versão

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 mostra o 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 IWA (autenticação integrada do Windows). Isso deve ser configurado manualmente no IIS antes da instalação do MIM (Microsoft Identity Manager).

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

Você pode gerar um novo certificado do servidor SSL executando o seguinte comando ao 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 em que a URL é test.cwap.com. O OID definido pela opção -eku identifica o certificado como um certificado de servidor SSL. O certificado é armazenado em meu repositório e está disponível no nível do computador. Você pode exportar o certificado do snap-in Certificados no mmc.exe.

CORS (acesso entre domínios)

Há suporte para CORS, mas deve ser configurado manualmente no IIS. Adicione os seguintes elementos ao arquivo web.config da API implantado 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 de HTTP para indicar as 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 status HTTP	Descrição
401	Não Autorizado
403	Proibido
408	Tempo Limite da Solicitação
500	Erro interno do servidor
503	Serviço indisponível

Filtragem

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

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

A API dá suporte aos operadores a seguir nas expressões de filtro: And, Equal, NotEqual, GreaterThan, LessThan, GreaterThenOrEqueal e LessThanOrEqual.

As solicitações de exemplo a seguir incluem filtros:

Essa solicitação retorna todas as solicitações do 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'
Essa solicitação retorna a Função do PAM com o nome de exibição "Acesso a arquivo SQL": http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'

Compartilhar via