Autenticação personalizada em Aplicativos Web Estáticos do Azure

Artigo
01/10/2024

Os Aplicativos Web Estáticos do Azure fornecem autenticação gerenciada que usa registros de provedor gerenciados pelo Azure. Para permitir mais flexibilidade sobre o registro, você pode substituir os padrões por um registro personalizado.

A autenticação personalizada também permite configurar provedores personalizados que suportam o OpenID Connect. Esta configuração permite o registo de múltiplos fornecedores externos.
O uso de registros personalizados desativa todos os provedores pré-configurados.

Nota

A autenticação personalizada só está disponível no plano Static Web Apps Standard do Azure.

Configurar um provedor de identidade personalizado

Os provedores de identidade personalizados são configurados na auth seção do arquivo de configuração.

Para evitar colocar segredos no controle do código-fonte, a configuração examina as configurações do aplicativo para obter um nome correspondente no arquivo de configuração. Você também pode optar por armazenar seus segredos no Cofre da Chave do Azure.

Para criar o registro, comece criando as seguintes configurações do aplicativo:

Nome da Definição	Valor
`AZURE_CLIENT_ID`	A ID do aplicativo (cliente) para o registro do aplicativo Microsoft Entra.
`AZURE_CLIENT_SECRET`	O segredo do cliente para o registro do aplicativo Microsoft Entra.

Em seguida, use o exemplo a seguir para configurar o provedor no arquivo de configuração.

Os provedores do Microsoft Entra estão disponíveis em duas versões diferentes. A versão 1 define explicitamente o userDetailsClaim, que permite que a carga retorne informações do usuário. Por outro lado, a versão 2 retorna informações do openIdIssuer usuário por padrão e é designada por v2.0 na URL.

Microsoft Entra Versão 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET"
        }
      }
    }
  }
}

Certifique-se de substituir <TENANT_ID> por sua ID de locatário do Microsoft Entra.

Microsoft Entra Versão 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET"
        }
      }
    }
  }
}

Certifique-se de substituir <TENANT_ID> por sua ID de locatário do Microsoft Entra.

Para obter mais informações sobre como configurar o Microsoft Entra ID, consulte a documentação de Autenticação/Autorização do Serviço de Aplicativo sobre como usar um registro existente.

Para configurar quais contas podem entrar, consulte Modificar as contas suportadas por um aplicativo e Restringir seu aplicativo Microsoft Entra a um conjunto de usuários em um locatário do Microsoft Entra.

Nota

Enquanto a seção de configuração para o Microsoft Entra ID é azureActiveDirectory, a plataforma aliases isso nos aad URLs para login, logout e limpeza de informações do usuário. Consulte a seção de autenticação e autorização para obter mais informações.

Para criar o registro, comece criando as seguintes configurações do aplicativo:

Nome da Definição	Valor
`APPLE_CLIENT_ID`	O ID do cliente Apple.
`APPLE_CLIENT_SECRET`	O segredo do cliente Apple.

Em seguida, use o exemplo a seguir para configurar o provedor no arquivo de configuração.

{
  "auth": {
    "identityProviders": {
      "apple": {
        "registration": {
          "clientIdSettingName": "APPLE_CLIENT_ID",
          "clientSecretSettingName": "APPLE_CLIENT_SECRET"
        }
      }
    }
  }
}

Para obter mais informações sobre como configurar a Apple como um provedor de autenticação, consulte a documentação de Autenticação/Autorização do Serviço de Aplicativo.

Para criar o registro, comece criando as seguintes configurações do aplicativo:

Nome da Definição	Valor
`FACEBOOK_APP_ID`	O ID do aplicativo do Facebook.
`FACEBOOK_APP_SECRET`	O segredo do aplicativo do Facebook.

Em seguida, use o exemplo a seguir para configurar o provedor no arquivo de configuração.

{
  "auth": {
    "identityProviders": {
      "facebook": {
        "registration": {
          "appIdSettingName": "FACEBOOK_APP_ID",
          "appSecretSettingName": "FACEBOOK_APP_SECRET"
        }
      }
    }
  }
}

Para obter mais informações sobre como configurar o Facebook como um provedor de autenticação, consulte a documentação de Autenticação/Autorização do Serviço de Aplicativo.

Para criar o registro, comece criando as seguintes configurações do aplicativo:

Nome da Definição	Valor
`GITHUB_CLIENT_ID`	O ID do cliente GitHub.
`GITHUB_CLIENT_SECRET`	O segredo do cliente GitHub.

Em seguida, use o exemplo a seguir para configurar o provedor no arquivo de configuração.

{
  "auth": {
    "identityProviders": {
      "github": {
        "registration": {
          "clientIdSettingName": "GITHUB_CLIENT_ID",
          "clientSecretSettingName": "GITHUB_CLIENT_SECRET"
        }
      }
    }
  }
}

Para criar o registro, comece criando as seguintes configurações do aplicativo:

Nome da Definição	Valor
`GOOGLE_CLIENT_ID`	O ID do cliente do Google.
`GOOGLE_CLIENT_SECRET`	O segredo do cliente Google.

Em seguida, use o exemplo a seguir para configurar o provedor no arquivo de configuração.

{
  "auth": {
    "identityProviders": {
      "google": {
        "registration": {
          "clientIdSettingName": "GOOGLE_CLIENT_ID",
          "clientSecretSettingName": "GOOGLE_CLIENT_SECRET"
        }
      }
    }
  }
}

Para obter mais informações sobre como configurar o Google como um provedor de autenticação, consulte a documentação de Autenticação/Autorização do Serviço de Aplicativo.

Para criar o registro, comece criando as seguintes configurações do aplicativo:

Nome da Definição	Valor
`TWITTER_CONSUMER_KEY`	A chave do consumidor do Twitter.
`TWITTER_CONSUMER_SECRET`	O segredo do consumidor do Twitter.

Em seguida, use o exemplo a seguir para configurar o provedor no arquivo de configuração.

{
  "auth": {
    "identityProviders": {
      "twitter": {
        "registration": {
          "consumerKeySettingName": "TWITTER_CONSUMER_KEY",
          "consumerSecretSettingName": "TWITTER_CONSUMER_SECRET"
        }
      }
    }
  }
}

Para obter mais informações sobre como configurar o Twitter como um provedor de autenticação, consulte a documentação de Autenticação/Autorização do Serviço de Aplicativo.

Você pode configurar os Aplicativos Web Estáticos do Azure para usar um provedor de autenticação personalizado que siga a especificação OpenID Connect (OIDC). As etapas a seguir são necessárias para usar um provedor OIDC personalizado.

Um ou mais provedores OIDC são permitidos.
Cada provedor deve ter um nome exclusivo na configuração.
Apenas um provedor pode servir como destino de redirecionamento padrão.

Registre seu aplicativo com o provedor de identidade

É necessário registrar os detalhes do seu aplicativo com um provedor de identidade. Verifique com o provedor as etapas necessárias para gerar uma ID de cliente e segredo de cliente para seu aplicativo.

Depois que o aplicativo for registrado com o provedor de identidade, crie os seguintes segredos de aplicativo nas configurações do aplicativo do Static Web App:

Nome da Definição	Valor
`MY_PROVIDER_CLIENT_ID`	A ID do cliente gerada pelo provedor de autenticação para seu aplicativo Web estático.
`MY_PROVIDER_CLIENT_SECRET`	O segredo do cliente gerado pelo registro personalizado do provedor de autenticação para seu aplicativo Web estático.

Se você registrar provedores adicionais, cada um precisará de um ID de cliente associado e armazenamento secreto do cliente nas configurações do aplicativo.

Importante

Os segredos de aplicativo são credenciais de segurança confidenciais. Não compartilhe esse segredo com ninguém, distribua-o dentro de um aplicativo cliente ou faça check-in no controle do código-fonte.

Depois de ter as credenciais de registro, use as etapas a seguir para criar um registro personalizado.

Você precisa dos metadados do OpenID Connect para o provedor. Essas informações geralmente são expostas por meio de um documento de metadados de configuração, que é o URL do emissor do provedor sufixo com /.well-known/openid-configuration. Reúna este URL de configuração.

Adicione uma auth seção do arquivo de configuração com um bloco de configuração para os provedores OIDC e sua definição de provedor.

{
  "auth": {
    "identityProviders": {
      "customOpenIdConnectProviders": {
        "myProvider": {
          "registration": {
            "clientIdSettingName": "MY_PROVIDER_CLIENT_ID",
            "clientCredential": {
              "clientSecretSettingName": "MY_PROVIDER_CLIENT_SECRET"
            },
            "openIdConnectConfiguration": {
              "wellKnownOpenIdConfiguration": "https://<PROVIDER_ISSUER_URL>/.well-known/openid-configuration"
            }
          },
          "login": {
            "nameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
            "scopes": [],
            "loginParameterNames": []
          }
        }
      }
    }
  }
}

O nome do provedor, neste exemplo, myProvider é o identificador exclusivo usado pelos Aplicativos Web Estáticos do Azure.
Certifique-se de substituir <PROVIDER_ISSUER_URL> pelo caminho para a URL do Emissor do provedor.
O login objeto permite que você forneça valores para: escopos personalizados, parâmetros de login ou declarações personalizadas.

Retornos de chamada de autenticação

Os provedores de identidade exigem uma URL de redirecionamento para concluir a solicitação de login ou logout. A maioria dos provedores exige que você adicione as URLs de retorno de chamada a uma lista de permissões. Os seguintes pontos de extremidade estão disponíveis como destinos de redirecionamento.

Tipo	Padrão de URL
Iniciar Sessão	`https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback`
Fim de Sessão	`https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback`

Se você estiver usando o Microsoft Entra ID, use aad como o valor para o <PROVIDER_NAME_IN_CONFIG> espaço reservado.

Nota

Essas URLs são fornecidas pelos Aplicativos Web Estáticos do Azure para receber a resposta do provedor de autenticação, você não precisa criar páginas nessas rotas.

Para usar um provedor de identidade personalizado, use os seguintes padrões de URL.

Ação	Padrão
Iniciar Sessão	`/.auth/login/<PROVIDER_NAME_IN_CONFIG>`
Fim de Sessão	`/.auth/logout`
Detalhes do utilizador	`/.auth/me`
Limpar detalhes do usuário	`/.auth/purge/<PROVIDER_NAME_IN_CONFIG>`

Se você estiver usando o Microsoft Entra ID, use aad como o valor para o <PROVIDER_NAME_IN_CONFIG> espaço reservado.

Gerir funções

Cada usuário que acessa um aplicativo Web estático pertence a uma ou mais funções. Há duas funções internas às quais os usuários podem pertencer:

anônimo: Todos os usuários pertencem automaticamente à função anônima .
autenticado: todos os usuários que estão conectados pertencem à função autenticada .

Além das funções internas, você pode atribuir funções personalizadas aos usuários e fazer referência a elas no arquivo staticwebapp.config.json .

Convites
Função (pré-visualização)

Adicionar um usuário a uma função

Para adicionar um usuário a uma função, você gera convites que permitem associar usuários a funções específicas. As funções são definidas e mantidas no arquivo staticwebapp.config.json .

Criar um convite

Os convites são específicos para provedores de autorização individuais, portanto, considere as necessidades do seu aplicativo ao selecionar quais provedores oferecer suporte. Alguns provedores expõem o endereço de e-mail de um usuário, enquanto outros fornecem apenas o nome de usuário do site.

Provedor de autorização	Expõe
Microsoft Entra ID	endereço de e-mail
GitHub	nome de utilizador
Twitter	nome de utilizador

Siga as etapas a seguir para criar um convite.

Vá para um recurso de Aplicativos Web Estáticos no portal do Azure.
Em Configurações, selecione Gerenciamento de Funções.
Selecione Convidar.
Selecione um provedor de autorização na lista de opções.
Adicione o nome de usuário ou endereço de e-mail do destinatário na caixa Detalhes do convidado.
- Para GitHub e Twitter, digite o nome de usuário. Para todos os outros, insira o endereço de e-mail do destinatário.
Selecione o domínio do seu site estático no menu suspenso Domínio .
- O domínio selecionado é o domínio que aparece no convite. Se você tiver um domínio personalizado associado ao seu site, escolha o domínio personalizado.
Adicione uma lista separada por vírgulas de nomes de função na caixa Função .
Introduza o número máximo de horas que pretende que o convite permaneça válido.
- O limite máximo possível é de 168 horas, ou seja, sete dias.
Selecione Gerar.
Copie o link da caixa Convidar link .
Envie o link de convite por e-mail para o usuário ao qual você está concedendo acesso.

Quando o usuário seleciona o link no convite, ele é solicitado a entrar com a conta correspondente. Depois de entrar com êxito, o usuário é associado às funções selecionadas.

Atenção

Verifique se as regras de rota não entram em conflito com os provedores de autenticação selecionados. Bloquear um provedor com uma regra de rota impede que os usuários aceitem convites.

Atualizar as atribuições de funções

Vá para um recurso de Aplicativos Web Estáticos no portal do Azure.
Em Configurações, selecione Gerenciamento de Funções.
Selecione o usuário na lista.
Edite a lista de funções na caixa Função .
Selecione Atualizar.

Remover utilizador

Vá para um recurso de Aplicativos Web Estáticos no portal do Azure.
Em Configurações, selecione Gerenciamento de Funções.
Localize o usuário na lista.
Marque a caixa de seleção na linha do usuário.
Selecione Eliminar.

Ao remover um usuário, lembre-se dos seguintes itens:

Remover um usuário invalida suas permissões.
A propagação mundial pode demorar alguns minutos.
Se o usuário for adicionado novamente ao aplicativo, as userId alterações.

Em vez de usar o sistema de convites interno, você pode usar uma função sem servidor para atribuir funções programaticamente aos usuários quando eles entrarem.

Para atribuir funções personalizadas em uma função, você pode definir uma função de API que é chamada automaticamente após cada vez que um usuário se autentica com êxito com um provedor de identidade. A função é passada as informações do usuário do provedor. Ele deve retornar uma lista de funções personalizadas atribuídas ao usuário.

Exemplos de usos desta função incluem:

Consultar um banco de dados para determinar quais funções um usuário deve ser atribuído
Chame a API do Microsoft Graph para determinar as funções de um usuário com base em sua associação ao grupo do Ative Directory
Determinar as funções de um usuário com base nas declarações retornadas pelo provedor de identidade

Nota

A capacidade de atribuir funções por meio de uma função só está disponível quando a autenticação personalizada é configurada.

Quando esse recurso é habilitado, todas as funções atribuídas por meio do sistema de convites interno são ignoradas.

Configurar uma função para atribuir funções

Para configurar os Aplicativos Web Estáticos para usar uma função de API como a função de atribuição de função, adicione uma rolesSource propriedade à auth seção do arquivo de configuração do seu aplicativo. O valor da rolesSource propriedade é o caminho para a função API.

{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      // ...
    }
  }
}

Nota

Uma vez configurada, a função de atribuição de função não pode mais ser acessada por solicitações HTTP externas.

Criar uma função para atribuir funções

Depois de definir a rolesSource propriedade na configuração do aplicativo, adicione uma função de API no aplicativo Web estático no caminho especificado. Você pode usar um aplicativo de função gerenciado ou trazer seu próprio aplicativo de função.

Cada vez que um usuário se autentica com êxito com um provedor de identidade, o método POST chama a função especificada. A função passa um objeto JSON no corpo da solicitação que contém as informações do usuário do provedor. Para alguns provedores de identidade, as informações do usuário também incluem um accessToken que a função pode usar para fazer chamadas de API usando a identidade do usuário.

Consulte o seguinte exemplo de carga útil do Microsoft Entra ID:

{
  "identityProvider": "aad",
  "userId": "72137ad3-ae00-42b5-8d54-aacb38576d76",
  "userDetails": "ellen@contoso.com",
  "claims": [
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
          "val": "Contoso"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
          "val": "Ellen"
      },
      {
          "typ": "name",
          "val": "Ellen Contoso"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier",
          "val": "7da753ff-1c8e-4b5e-affe-d89e5a57fe2f"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          "val": "72137ad3-ae00-42b5-8d54-aacb38576d76"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/tenantid",
          "val": "3856f5f5-4bae-464a-9044-b72dc2dcde26"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "ver",
          "val": "1.0"
      }
  ],
  "accessToken": "eyJ0eXAiOiJKV..."
}

A função pode usar as informações do usuário para determinar quais funções atribuir ao usuário. Ele deve retornar uma resposta HTTP 200 com um corpo JSON contendo uma lista de nomes de função personalizados para atribuir ao usuário.

Por exemplo, para atribuir o usuário às Reader funções e Contributor , retorne a seguinte resposta:

{
  "roles": [
    "Reader",
    "Contributor"
  ]
}

Se você não quiser atribuir outras funções ao usuário, retorne uma matriz vazia roles .

Para saber mais, consulte Tutorial: Atribuir funções personalizadas com uma função e Microsoft Graph.

Próximos passos

Definir funções de usuário programaticamente

Autenticação personalizada em Aplicativos Web Estáticos do Azure

Configurar um provedor de identidade personalizado

Microsoft Entra Versão 1

Microsoft Entra Versão 2

Retornos de chamada de autenticação

Login, logout e detalhes do usuário

Gerir funções

Adicionar um usuário a uma função

Criar um convite

Atualizar as atribuições de funções

Remover utilizador

Próximos passos

Recursos adicionais