Usar o fluxo de concessão implícito do OAuth 2.0 no seu portal
Observação
Desde o dia 12 de outubro de 2022, os portais do Power Apps passaram a ser Power Pages. Mais Informações: O Microsoft Power Pages já está disponível para todos (blog)
Em breve, migraremos e mesclaremos a documentação dos portais do Power Apps com a documentação do Power Pages.
Este recurso permite que um cliente faça chamadas do cliente para APIs externas e proteja-as usando o fluxo de concessão implícita do OAuth. Ele fornece um ponto de extremidade para obter tokens de acesso seguro. Esses tokens conterão informações de identidade do usuário a serem usadas por APIs externas para autorização seguindo o fluxo de concessão implícita do OAuth 2.0. As informações de identidade de um usuário conectado são passadas de maneira segura para as chamadas AJAX externas, o que ajuda os desenvolvedores a passar o contexto de autenticação e também ajudará os usuários a proteger suas APIs.
O fluxo de concessão implícita do OAuth 2.0 oferece suporte a pontos de extremidade do token que um cliente pode chamar para obter um token de ID.
Certificados personalizados
O uso do certificado padrão para o fluxo de concessão implícita do OAuth 2.0 está preterido. Você precisará usar um certificado personalizado ao usar o ponto de extremidade do OAuth 2.0. Use o centro de administração do Power Platform para carregar o certificado personalizado. Depois de carregar o certificado personalizado, você precisará atualizar as configurações do site como abaixo:
Acesse configurações do portal e selecione Configurações do Site.
Para criar uma configuração, selecione Novo.
Para editar uma configuração existente, selecione a configuração do site listada na grade.
Especifique valores:
- Nome: CustomCertificates/ImplicitGrantflow
- Site: o site associado
- Valor: copie a impressão digital do certificado personalizado carregado na tela Gerenciar certificado personalizado e cole-a aqui. O valor indicará qual certificado será usado para o fluxo de concessão implícita.
Selecione Salvar e Fechar.
Detalhes do ponto de extremidade do token
Você também pode obter um token fazendo uma solicitação post para o ponto de extremidade do /token. A URL para o ponto de extremidade do token é: <portal_url>/_services/auth/token. O ponto de extremidade do token é compatível com os seguintes parâmetros:
| Parâmetro | Obrigatório? | Descrição |
|---|---|---|
| client_id | Não | Uma cadeia que é passada ao fazer uma chamada para o ponto de extremidade de autorização. Você deve garantir que a ID do cliente seja registrada no portal. Caso contrário, um erro será exibido. A ID do cliente é adicionada às declarações no token como parâmetros aud e appid e pode ser usada pelos clientes para validar se o token retornado é para o aplicativo.O comprimento máximo é de 36 caracteres. Somente caracteres alfanuméricos e hífen são compatíveis. |
| redirect_uri | Não | A URL do portal onde as respostas de autenticação podem ser enviadas e recebidas. Ela deve ser registrada para a client_id específica usada na chamada e deve ser exatamente o mesmo valor registrado. |
| estado | Não | Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma cadeia de qualquer conteúdo que você queira usar. Geralmente, um valor exclusivo gerado aleatoriamente é usado para evitar ataques de falsificação de solicitação entre sites. O comprimento máximo é de 20 caracteres. |
| nonce | Não | Um valor de cadeia enviado pelo cliente incluído no token de ID resultante como uma reivindicação. O cliente pode verificar esse valor para atenuar os ataques de repetição de token. O tamanho máximo é de 20 caracteres. |
| response_type | Não | Este parâmetro oferece suporte apenas a token como valor, permitindo que seu aplicativo receba imediatamente um token de acesso do ponto de extremidade de autorização, sem fazer uma segunda solicitação a esse ponto de extremidade. |
Observação
Mesmo que os parâmetros client_id, redirect_uri, state e nonce sejam opcionais, recomenda-se usá-los para garantir que suas integrações sejam seguras.
Resposta bem-sucedida
O ponto de extremidade de token retorna estado e expires_in como cabeçalhos de resposta e token no corpo do formulário.
Resposta de erro
O erro em um ponto de extremidade de token é retornado como um documento JSON com os seguintes valores:
- ID do Erro: identificador exclusivo do erro.
- Mensagem de erro: uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação.
- ID da Correlação: um GUID usado para fins de depuração. Se você tiver habilitado o log de diagnóstico, a ID de correlação estará presente nos logs de erro do servidor.
- Timestamp: data e hora em que o erro é gerado.
A mensagem de erro é exibida no idioma padrão do usuário conectado. Se o usuário não estiver conectado, uma página de entrada será exibida para que o usuário se conecte. Por exemplo, uma resposta de erro é assim:
{"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" }
Detalhes do ponto de extremidade de autorização
Observação
O ponto de extremidade de autorização foi preterido. Use a solicitação POST do ponto de extremidade do token para obter o token de ID.]
A URL para o ponto de extremidade de autorização é: <portal_url>/_services/auth/authorize. O ponto de extremidade de autorização é compatível com os seguintes parâmetros:
| Parâmetro | Obrigatório? | Descrição |
|---|---|---|
| client_id | Sim | Uma cadeia que é passada ao fazer uma chamada para o ponto de extremidade de autorização. Você deve garantir que a ID do cliente seja registrada no portal. Caso contrário, um erro será exibido. A ID do cliente é adicionada às declarações no token como parâmetros aud e appid e pode ser usada pelos clientes para validar se o token retornado é para o aplicativo.O comprimento máximo é de 36 caracteres. Somente caracteres alfanuméricos e hífens são compatíveis. |
| redirect_uri | Sim | A URL do portal onde as respostas de autenticação podem ser enviadas e recebidas. Ela deve ser registrada para a client_id específica usada na chamada e deve ser exatamente o mesmo valor registrado. |
| estado | Não | Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma cadeia de qualquer conteúdo que você queira usar. Geralmente, um valor exclusivo gerado aleatoriamente é usado para evitar ataques de falsificação de solicitação entre sites. O comprimento máximo é de 20 caracteres. |
| nonce | Não | Um valor de cadeia enviado pelo cliente incluído no token de ID resultante como uma reivindicação. O cliente pode verificar esse valor para atenuar os ataques de repetição de token. O tamanho máximo é de 20 caracteres. |
| response_type | Não | Este parâmetro oferece suporte apenas a token como valor, permitindo que seu aplicativo receba imediatamente um token de acesso do ponto de extremidade de autorização, sem fazer uma segunda solicitação a esse ponto de extremidade. |
Resposta bem-sucedida
O ponto de extremidade de autorização retorna os seguintes valores na URL de resposta como um fragmento:
- token: o token é retornado como um JSON Web Token (JWT) assinado digitalmente pela chave privada do portal.
- estado: se um parâmetro de estado for incluído na solicitação, o mesmo valor deverá aparecer na resposta. O aplicativo deve verificar se os valores de estado na solicitação e na resposta são idênticos.
- expires_in: o período em que o token de acesso é válido (em segundos).
Por exemplo, uma resposta bem-sucedida é a seguinte:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Resposta de erro
O erro no ponto de extremidade de autorização é retornado como um documento JSON com os seguintes valores:
- ID do Erro: identificador exclusivo do erro.
- Mensagem de erro: uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação.
- ID da Correlação: um GUID usado para fins de depuração. Se você tiver habilitado o log de diagnóstico, a ID de correlação estará presente nos logs de erro do servidor.
- Timestamp: data e hora em que o erro é gerado.
A mensagem de erro é exibida no idioma padrão do usuário conectado. Se o usuário não estiver conectado, a página de entrada será exibida para que o usuário se conecte. Por exemplo, uma resposta de erro é assim:
{"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 token de ID
Apenas obter um token de ID não é suficiente para autenticar o usuário; você também deve validar a assinatura do token e verificar as declarações nele com base nos requisitos do seu aplicativo. O ponto de extremidade de token público fornece a chave pública do portal, que pode ser usada para validar a assinatura do token fornecido pelo portal. A URL para o ponto de extremidade de token público é: <portal_url>/_services/auth/publickey.
Ativar ou desativar o fluxo de concessão implícito
Por padrão, o fluxo de concessão implícito está habilitado. Se você quiser desativar o fluxo de concessão implícita, defina o valor da configuração do site Connector/ImplicitGrantFlowEnabled como Falso.
Se essa configuração do site não estiver disponível no seu portal, você deverá criar uma nova configuração do site com o valor apropriado.
Configurar validade de token
Por padrão, o token é válido por 15 minutos. Se você quiser alterar a validade do token, defina o valor da configuração do site ImplicitGrantFlow/TokenExpirationTime como o valor necessário. O valor deve ser especificado em segundos. O valor máximo pode ser de 1 hora e o valor mínimo deve ser de 1 minuto. Se um valor incorreto for especificado (por exemplo, caracteres alfanuméricos), o valor padrão de 15 minutos será usado. Se você especificar um valor maior que o valor máximo ou menor que o valor mínimo, os valores máximo e mínimo serão usados, respectivamente, por padrão.
Por exemplo, para definir a validade do token para 30 minutos, defina o valor da configuração do site ImplicitGrantFlow/TokenExpirationTime como 1800. Para definir a validade do token para 1 hora, defina o valor da configuração do site ImplicitGrantFlow/TokenExpirationTime como 3600.
Registrar a ID do cliente para o fluxo de concessão implícito
Você deve registrar a ID do cliente com o portal para o qual esse fluxo é permitido. Para registrar uma ID de cliente, você deve criar as seguintes configurações do site:
| Configuração do site | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | Os valores de ID do cliente válidos permitidos para esse portal. Os valores devem ser separados por um ponto-e-vírgula e podem conter caracteres alfanuméricos e hífens. O comprimento máximo é de 36 caracteres. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Os URIs de redirecionamento válidos permitidos para uma ID de cliente específica. Os valores devem ser separados por um ponto-e-vírgula. A URL fornecida deve ser de uma página da Web válida do portal. |
Código de exemplo
Você pode usar o seguinte código de exemplo a seguir para começar a usar a concessão implícita do OAuth 2.0 com APIs dos portais do Power Apps.
Use o token OAuth do Portal com uma API Web externa
Este exemplo é um projeto baseado em ASP.NET e é usado para validar o token de ID emitido pelos portais do Power Apps. O exemplo completo pode ser encontrado aqui: Usar o token OAuth do Portal com uma API Web externa.
Exemplo de ponto de extremidade do token
Este exemplo mostra como usar a função getAuthenticationToken para buscar um token de ID usando o ponto de extremidade do token nos portais do Power Apps. O exemplo pode ser encontrado aqui: Exemplo do ponto de extremidade do token.
Observação
Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)
A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de