Utilize o fluxo de concessão implícita do OAuth 2.0 no portal
Nota
A partir de 12 de outubro de 2022, os portais do Power Apps passam a ser Power Pages. Mais informações: O Microsoft Power Pages está agora em disponibilidade geral (blogue)
Em breve, vamos migrar e unir a documentação dos portais do Power Apps com a documentação do Power Pages.
Esta caraterística permite que um cliente faça chamadas do lado do cliente para APIs externas e protegê-las utilizando o fluxo de concessão implícita do OAuth. Fornece uma ponto final para obter tokens de acesso seguro. Estes tokens irão conter informações de identidade do utilizador a serem utilizadas por APIs externas para autorização de acordo com o fluxo de concessão implícito do OAuth 2.0. As informações de identidade de um utilizador com sessão iniciada são transmitidas de forma segura para chamadas AJAX externas, o que ajuda os programadores a transmitir contexto de autenticação e também ajudará os utilizadores a proteger as suas APIs.
O fluxo de concessão implícita do OAuth 2.0 suporta pontos finais de token que um cliente pode contactar para obter um token de ID.
Certificados personalizados
A utilização do certificado predefinido para o fluxo de concessão implícita de OAuth 2.0, está preterida. Terá de utilizar um certificado personalizado durante a utilização do ponto final de OAuth 2.0. Utilize o centro de administração do Power Platform para carregar o certificado personalizado. Depois de carregar o certificado personalizado, necessita de atualizar as definições do site, como abaixo:
Aceda às definições do portal e selecione Definições do Site.
Para criar uma nova definição, selecione Novo.
Para editar uma definição existente, selecione a definição do site listada na grelha.
Especificar valores:
- Nome: CustomCertificates/ImplicitGrantflow
- Site: o site associado
- Valor: copie o thumbprint do certificado personalizado carregado a partir do ecrã Gerir certificado personalizado e cole-o aqui. O valor indicará qual o certificado que será utilizado para o fluxo de concessão implícita.
Selecione Guardar e Fechar.
Detalhes de ponto final de token
Também pode obter um token efetuando um pedido POST ao ponto final /token. O URL para o ponto final do token é: <portal_url>/_services/auth/token. O ponto final do token suporta os seguintes parâmetros:
| Parâmetro | Necessário? | Descrição |
|---|---|---|
| client_id | Não | Uma cadeia que é transmitida ao fazer uma chamada para o ponto final de autorizar. Certifique-se de que o ID do cliente ID está registado no portal. Caso contrário, é apresentado um erro. O ID do cliente é adicionado nas declarações no token como parâmetro aud e appid e pode ser utilizado por clientes para validar que o token devolvido é para a sua aplicação.O comprimento máximo é de 36 carateres. Apenas carateres alfanuméricos e hífens são suportados. |
| redirect_uri | Não | URL do portal para onde as respostas de autenticação podem ser enviadas e recebidas. Tem de ser registado para o determinado client_id utilizado na chamada e deverá ter exatamente o mesmo valor registado. |
| state | Não | Um valor incluído no pedido que também é devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretende utilizar. Normalmente, um valor exclusivo gerado aleatoriamente é utilizado para impedir ataques de falsificação de pedido entre sites. O comprimento máximo é de 20 carateres. |
| nonce | Não | Um valor de cadeia enviado pelo cliente que está incluído no token de ID resultante como uma declaração. O cliente, em seguida, pode verificar este valor para mitigar ataques de reprodução de token. O comprimento máximo é de 20 carateres. |
| response_type | Não | Este parâmetro suporta apenas token como um valor, permitindo que a aplicação receba imediatamente um token de acesso do ponto final de autorizar sem fazer um segundo pedido ao ponto final de autorizar. |
Nota
Apesar dos parâmetros client_id, redirect_uri, state e nonce serem opcionais, é recomendável que os utilize para garantir que as integrações ficam seguras.
Resposta com êxito
O ponto final do token devolve state e expires_in como cabeçalhos de resposta, e o token no corpo do formulário.
Resposta de erro
O erro no ponto final do token é devolvido como um documento JSON com os seguintes valores:
- ID de erro: identificador exclusivo do erro.
- Mensagem de erro: uma mensagem de erro específica que pode ajudá-lo identificar a causa de um erro de autenticação.
- ID de correlação: um GUID que é utilizado para fins de depuração. Se ativou o registo de diagnóstico, o ID de correlação estaria presente nos registos de erro do servidor.
- Carimbo de data/hora: data e hora em que o erro é gerado.
A mensagem de erro é apresentada no idioma predefinido do utilizador com sessão iniciada. Se o utilizador não tem sessão iniciada, é apresentada uma página de início de sessão para que o utilizador inicie sessão. Por exemplo, uma resposta de erro tem o seguinte aspeto:
{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }
Autorizar detalhes de ponto final
Nota
O ponto final de autorizar foi preterido. Utilizar pedido POST de ponto final de Token para obter token de ID.]
O URL para autorizar o ponto final é: <portal_url>/_services/auth/authorize. O ponto final de autorização suporta os seguintes parâmetros:
| Parâmetro | Necessário? | Descrição |
|---|---|---|
| client_id | Sim | Uma cadeia que é transmitida ao fazer uma chamada para o ponto final de autorizar. Certifique-se de que o ID do cliente ID está registado no portal. Caso contrário, é apresentado um erro. O ID do cliente é adicionado nas declarações no token como parâmetro aud e appid e pode ser utilizado por clientes para validar que o token devolvido é para a sua aplicação.O comprimento máximo é de 36 carateres. Apenas carateres alfanuméricos e hífens são suportados. |
| redirect_uri | Sim | URL do portal para onde as respostas de autenticação podem ser enviadas e recebidas. Tem de ser registado para o determinado client_id utilizado na chamada e deverá ter exatamente o mesmo valor registado. |
| state | Não | Um valor incluído no pedido que também é devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretende utilizar. Normalmente, um valor exclusivo gerado aleatoriamente é utilizado para impedir ataques de falsificação de pedido entre sites. O comprimento máximo é de 20 carateres. |
| nonce | Não | Um valor de cadeia enviado pelo cliente que está incluído no token de ID resultante como uma declaração. O cliente, em seguida, pode verificar este valor para mitigar ataques de reprodução de token. O comprimento máximo é de 20 carateres. |
| response_type | Não | Este parâmetro suporta apenas token como um valor, o que permite que a aplicação receba imediatamente um token de acesso do ponto final de autorizar sem fazer um segundo pedido ao ponto final de autorizar. |
Resposta com êxito
O ponto final de autorizar devolve os seguintes valores no URL de resposta como um fragmento:
- token: token é devolvido como um Token Web JSON (JWT) assinado digitalmente pela chave privada do portal.
- state: se um parâmetro de estado está incluído no pedido, o mesmo valor deverá aparecer na resposta. A aplicação deve verificar se os valores de estado no pedido e resposta são idênticos.
- expires_in: o período de tempo que o token de acesso é válido (em segundos).
Por exemplo, uma resposta com êxito tem o seguinte aspeto:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Resposta de erro
O erro no ponto final de autorizar é devolvido como um documento JSON com os seguintes valores:
- ID de erro: identificador exclusivo do erro.
- Mensagem de erro: uma mensagem de erro específica que pode ajudá-lo identificar a causa de um erro de autenticação.
- ID de correlação: um GUID que é utilizado para fins de depuração. Se ativou o registo de diagnóstico, o ID de correlação estaria presente nos registos de erro do servidor.
- Carimbo de data/hora: data e hora em que o erro é gerado.
A mensagem de erro é apresentada no idioma predefinido do utilizador com sessão iniciada. Se o utilizador não tem sessão iniciada, é apresentada a página de início de sessão para que o utilizador inicie sessão. Por exemplo, uma resposta de erro tem o seguinte aspeto:
{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }
Validar o ID do token
Não é suficiente obter um token de ID para autenticar o utilizador; tem também de validar a assinatura do token e verificar as declarações no token com base nos requisitos da sua aplicação. O ponto final do token público fornece a chave pública do portal, a qual pode ser utilizada para validar a assinatura do token fornecida através do portal. O URL para o ponto final do token público é: <portal_url>/_services/auth/publickey.
Ativar ou desativar o fluxo de concessão implícita
Por predefinição, o fluxo de concessão implícita está ativado. Se pretender desativar o fluxo de concessão implícita, defina o valor do site Connector/ImplicitGrantFlowEnabled para False.
Se esta definição de site não está disponível no seu portal, tem de criar uma nova definição de site com o valor adequado.
Configurar a validade do token
Por predefinição, o token é válido por 15 minutos. Se pretender alterar a validade do token, defina o valor da definição do site ImplicitGrantFlow/TokenExpirationTime para o valor necessário. O valor tem de ser especificado em segundos. O valor máximo pode ser 1 hora e o valor mínimo tem de ser 1 minuto. Se for especificado um valor incorreto (por exemplo, carateres alfanuméricos), o valor predefinido de 15 minutos é utilizado. Se especificar um valor superior ao valor máximo ou inferior ao valor mínimo, os valores mínimos e máximo são utilizados respetivamente, por predefinição.
Por exemplo, para definir a validade do token como 30 minutos, defina o valor da definição do site ImplicitGrantFlow/TokenExpirationTime para 1800. Para definir a validade do token como 1 hora, defina o valor da definição do site ImplicitGrantFlow/TokenExpirationTime para 3600.
Registar ID do cliente para fluxo de concessão implícita
Tem de registar o ID do cliente com o portal para o qual este fluxo tem permissão. Para registar um ID de cliente, tem de criar as seguintes definições do site:
| Definição do local | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | Os valores de ID do cliente válidos que têm permissão para este portal. Os valores devem ser separados por um ponto e vírgula e podem conter carateres alfanuméricos e hífens. O comprimento máximo é de 36 carateres. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Os URIs de redirecionamento válidos que têm permissão para um ID de cliente específico. Os valores têm de ser separados por um ponto e vírgula. O URL fornecido tem de ser de uma página Web válida do portal. |
Código de exemplo
Pode utilizar o seguinte código de exemplo para começar a utilizar o OAuth 2.0 de Concessão Implícita com APIs dos portais Power Apps.
Utilizar o token OAuth do Portal com uma API Web externa
Este exemplo é um projeto baseado em ASP.NET e é utilizado para validar o token de ID emitido pelos portais Power Apps. O exemplo completo pode ser encontrado aqui: Utilizar o token de OAuth do Portal com uma API Web externa.
Exemplo de Ponto final de token
Este exemplo mostra como pode utilizar a função getAuthenticationToken para obter um token de ID utilizando o ponto final de Token nos portais Power Apps. O exemplo pode ser encontrado aqui: Exemplo de Ponto Final de Token.
Nota
Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)
O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).