Como autenticar usuários com o Go

Como configurar o projeto

1. Na janela de terminal, clone o repositório do app de amostra em sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

2. Acesse o diretório que contém o código de amostra:

   cd golang-samples/getting-started/authenticating-users

Contexto

Neste tutorial, o IAP é usado para autenticar usuários. Essa é apenas uma das várias abordagens possíveis. Para saber mais sobre os vários métodos de autenticação de usuários, consulte a seção Conceitos de autenticação.

O aplicativo Hello user-email-address

Neste tutorial, é usado um app Hello World do App Engine mínimo com um recurso atípico: em vez de "Hello world", ele exibe "Hello user-email-address", em que user-email-address é o endereço de e-mail do usuário autenticado.

Essa funcionalidade é possível por meio da análise das informações autenticadas que o IAP adiciona a cada solicitação da Web que passa no aplicativo. Há três novos cabeçalhos de solicitação adicionados a cada solicitação da Web que chega ao app. Os dois primeiros cabeçalhos são strings de texto simples que podem ser usadas para identificar o usuário. O terceiro cabeçalho é um objeto assinado criptograficamente com as mesmas informações.

• X-Goog-Authenticated-User-Email: o endereço de e-mail do usuário o identifica. Não armazene informações pessoais se o aplicativo puder evitar isso. Esse aplicativo não armazena dados. Ele apenas os retorna ao usuário.

• X-Goog-Authenticated-User-Id: esse ID de usuário atribuído pelo Google não mostra informações pessoais, mas permite que um aplicativo saiba que o usuário conectado é o mesmo que se conectou anteriormente.

• X-Goog-Iap-Jwt-Assertion: é possível configurar aplicativos do Google Cloud para aceitar solicitações da web de outros apps na nuvem ignorando o IAP, além de solicitações da web via Internet. Se um aplicativo for configurado dessa forma, é possível que essas solicitações tenham cabeçalhos forjados. Em vez de usar um dos cabeçalhos de texto simples mencionados anteriormente, é possível usar e verificar esse cabeçalho assinado por criptografia para confirmar se as informações foram fornecidas pelo Google. O endereço de e-mail do usuário e um ID de usuário permanente estão disponíveis como parte do cabeçalho assinado.

Se você tiver certeza de que o aplicativo está configurado para que apenas solicitações da Web via Internet possam acessá-lo e que não seja possível desativar o serviço do IAP, apenas uma linha de código será necessária para recuperar um ID de usuário único:

userID := r.Header.Get("X-Goog-Authenticated-User-ID")

No entanto, um aplicativo resiliente está preparado para erros, como uma configuração inesperada ou problemas ambientais. Assim, recomendamos criar uma função que use e verifique o cabeçalho criptograficamente assinado. A assinatura do cabeçalho não pode ser forjada. Quando verificada, ela pode ser usada para retornar a identificação.

Noções básicas sobre o código

Esta seção explica como o código funciona. Se você quiser executar o aplicativo, avance para a seção Implantar o aplicativo.

• O arquivo go.mod define Módulo Go e dos módulos de que depende.

  module github.com/GoogleCloudPlatform/golang-samples/getting-started/authenticating-users
  
  go 1.21
  
  require (
  	cloud.google.com/go/compute/metadata v0.5.0
  	github.com/golang-jwt/jwt v3.2.2+incompatible
  )
  
  require golang.org/x/sys v0.22.0 // indirect
  

• O arquivo app.yaml informa ao App Engine o ambiente de linguagem que seu código requer.

  runtime: go112

• O aplicativo inicia a importar pacotes e definir um main função. A função main registra um gerenciador de índice e inicia um servidor HTTP.

  
  // The authenticating-users program is a sample web server application that
  // extracts and verifies user identity data passed to it via Identity-Aware
  // Proxy.
  package main
  
  import (
  	"encoding/json"
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"time"
  
  	"cloud.google.com/go/compute/metadata"
  	"github.com/golang-jwt/jwt"
  )
  
  // app holds the Cloud IAP certificates and audience field for this app, which
  // are needed to verify authentication headers set by Cloud IAP.
  type app struct {
  	certs map[string]string
  	aud   string
  }
  
  func main() {
  	a, err := newApp()
  	if err != nil {
  		log.Fatal(err)
  	}
  
  	http.HandleFunc("/", a.index)
  
  	port := os.Getenv("PORT")
  	if port == "" {
  		port = "8080"
  		log.Printf("Defaulting to port %s", port)
  	}
  
  	log.Printf("Listening on port %s", port)
  	if err := http.ListenAndServe(":"+port, nil); err != nil {
  		log.Fatal(err)
  	}
  }
  
  // newApp creates a new app, returning an error if either the Cloud IAP
  // certificates or the app's audience field cannot be obtained.
  func newApp() (*app, error) {
  	certs, err := certificates()
  	if err != nil {
  		return nil, err
  	}
  
  	aud, err := audience()
  	if err != nil {
  		return nil, err
  	}
  
  	a := &app{
  		certs: certs,
  		aud:   aud,
  	}
  	return a, nil
  }
  

• A função index recebe o valor do cabeçalho da declaração do JWT que o IAP adicionou na solicitação recebida e chama uma função validateAssertion para validar esse valor assinado criptograficamente. O endereço de e-mail é usado em uma resposta da Web mínima.

  
  // index responds to requests with our greeting.
  func (a *app) index(w http.ResponseWriter, r *http.Request) {
  	if r.URL.Path != "/" {
  		http.NotFound(w, r)
  		return
  	}
  
  	assertion := r.Header.Get("X-Goog-IAP-JWT-Assertion")
  	if assertion == "" {
  		fmt.Fprintln(w, "No Cloud IAP header found.")
  		return
  	}
  	email, _, err := validateAssertion(assertion, a.certs, a.aud)
  	if err != nil {
  		log.Println(err)
  		fmt.Fprintln(w, "Could not validate assertion. Check app logs.")
  		return
  	}
  
  	fmt.Fprintf(w, "Hello %s\n", email)
  }
  

• A função validateAssertion valida a declaração que foi assinada corretamente e retorna o endereço de e-mail associado e o ID do usuário.

  Para validar uma declaração do JWT, é preciso conhecer os certificados de chave pública da entidade que assinou a declaração (neste caso, o Google) e o público a que ela se destina. No caso de um aplicativo do App Engine, o público é uma string com informações de identificação de um projeto do Google Cloud. A função validateAssertion recebe os certificados da função certs e da string de público da função audience.

  
  // validateAssertion validates assertion was signed by Google and returns the
  // associated email and userID.
  func validateAssertion(assertion string, certs map[string]string, aud string) (email string, userID string, err error) {
  	token, err := jwt.Parse(assertion, func(token *jwt.Token) (interface{}, error) {
  		keyID := token.Header["kid"].(string)
  
  		_, ok := token.Method.(*jwt.SigningMethodECDSA)
  		if !ok {
  			return nil, fmt.Errorf("unexpected signing method: %q", token.Header["alg"])
  		}
  
  		cert := certs[keyID]
  		return jwt.ParseECPublicKeyFromPEM([]byte(cert))
  	})
  
  	if err != nil {
  		return "", "", err
  	}
  
  	claims, ok := token.Claims.(jwt.MapClaims)
  	if !ok {
  		return "", "", fmt.Errorf("could not extract claims (%T): %+v", token.Claims, token.Claims)
  	}
  
  	if claims["aud"].(string) != aud {
  		return "", "", fmt.Errorf("mismatched audience. aud field %q does not match %q", claims["aud"], aud)
  	}
  	return claims["email"].(string), claims["sub"].(string), nil
  }
  

• Você pode procurar o ID numérico e o nome do projeto do Google Cloud e colocá-los no código-fonte, mas a função audience faz isso consultando o serviço de metadados padrão disponibilizado para cada aplicativo do App Engine. Como o serviço de metadados é externo ao código do aplicativo, esse resultado é salvo em uma variável global que é retornada sem a necessidade de procurar metadados nas chamadas subsequentes.

  O serviço de metadados do App Engine, assim como serviços de metadados semelhantes de outros serviços do Google Cloud Computing, tem a aparência de um site e recebe consultas padrão da web. No entanto, o serviço de metadados não é um site externo, mas um recurso interno que retorna informações solicitadas sobre o aplicativo em execução. Por isso, é seguro usar http em vez de solicitações https. O serviço de metadados é usado para obter os identificadores atuais do Google Cloud necessários para definir o público-alvo da declaração do JWT.

  
  // audience returns the expected audience value for this service.
  func audience() (string, error) {
  	projectNumber, err := metadata.NumericProjectID()
  	if err != nil {
  		return "", fmt.Errorf("metadata.NumericProjectID: %w", err)
  	}
  
  	projectID, err := metadata.ProjectID()
  	if err != nil {
  		return "", fmt.Errorf("metadata.ProjectID: %w", err)
  	}
  
  	return "/projects/" + projectNumber + "/apps/" + projectID, nil
  }
  

• A verificação de uma assinatura digital requer o certificado de chave pública do signatário. O Google fornece um site que retorna todos os certificados de chave pública usados atualmente. Esses resultados são armazenados em cache para caso sejam necessários novamente na mesma instância do aplicativo.

  
  // certificates returns Cloud IAP's cryptographic public keys.
  func certificates() (map[string]string, error) {
  	const url = "https://www.gstatic.com/iap/verify/public_key"
  	client := http.Client{
  		Timeout: 5 * time.Second,
  	}
  	resp, err := client.Get(url)
  	if err != nil {
  		return nil, fmt.Errorf("Get: %w", err)
  	}
  
  	var certs map[string]string
  	dec := json.NewDecoder(resp.Body)
  	if err := dec.Decode(&certs); err != nil {
  		return nil, fmt.Errorf("Decode: %w", err)
  	}
  
  	return certs, nil
  }
  

Como implantar o app

Agora é possível implantar o aplicativo e permitir que o IAP solicite a autenticação dos usuários para que eles possam acessar o aplicativo.

1. Na janela do terminal, acesse o diretório que contém o arquivo app.yaml e implante o aplicativo no App Engine:

   gcloud app deploy
   

2. Quando solicitado, selecione uma região próxima.

3. Quando receber uma mensagem perguntando se quer continuar com a operação de implantação, insira Y.

   Em alguns minutos, seu app está ativo na Internet.

4. Ver o aplicativo:

   gcloud app browse
   

   Na saída, copie web-site-url, o endereço da Web do aplicativo.

5. Em uma janela do navegador, cole web-site-url para abrir o aplicativo.

   Como você ainda não está usando o IAP, nenhum e-mail será exibido. Portanto, nenhuma informação de usuário será enviada para o aplicativo.

Ativar o IAP

Agora que existe uma instância do App Engine, é possível protegê-la com o IAP:

1. No console do Google Cloud, acesse a página Identity-Aware Proxy.

   Acesse a página do Identity-Aware Proxy

2. Como essa é a primeira vez que você ativa uma opção de autenticação para o projeto, você verá uma mensagem para configurar a tela de consentimento do OAuth antes de usar o IAP.

   Clique em Configurar tela de consentimento.

3. Na guia Tela de consentimento OAuth da página Credenciais, preencha os seguintes campos:

   • Se a sua conta estiver em uma organização no Google Workspace, selecione Externo e clique em Criar. A princípio, o app só estará disponível para os usuários que você permitir explicitamente.

   • No campo Nome do aplicativo, digite IAP Example.

   • No campo E-mail para suporte, digite seu endereço de e-mail.

   • No campo Domínio autorizado, digite a parte do nome do host do URL do aplicativo, por exemplo, iap-example-999999.uc.r.appspot.com. Pressione a tecla Enter depois de inserir o nome do host no campo.

   • No campo Link da página inicial do aplicativo, insira o URL do seu aplicativo. Por exemplo, https://iap-example-999999.uc.r.appspot.com/.

   • No campo Linha da política de privacidade do aplicativo, use o mesmo URL do link da página inicial para fins de teste.

4. Clique em Salvar. Quando for solicitado que você crie credenciais, feche a janela.

5. No console do Google Cloud, acesse a página Identity-Aware Proxy.

   Acessar a página do Identity-Aware Proxy

6. Para atualizar a página, clique em Atualizar refresh. A página exibe uma lista de recursos que são possíveis proteger.

7. Na coluna IAP, clique para ativar o IAP para o aplicativo.

8. No seu navegador, acesse web-site-url novamente.

9. Em vez da página da Web, há uma tela de login para autenticação. Ao fazer login, seu acesso será negado, porque o IAP não tem uma lista de usuários para permitir o acesso ao aplicativo.

Adicionar usuários autorizados ao aplicativo

1. No console do Google Cloud, acesse a página "Identity-Aware Proxy".

   Acessar a página do Identity-Aware Proxy

2. Marque a caixa de seleção correspondente ao aplicativo do App Engine e clique em Adicionar principal.

3. Insira allAuthenticatedUsers e selecione o papel Cloud IAP/Usuário do app da Web protegido pelo IAP.

4. Clique em Save.

Agora qualquer usuário que o Google possa autenticar poderá acessar o aplicativo. Se quiser, restrinja o acesso adicionando apenas uma ou mais pessoas ou grupos como principais:

• Qualquer endereço de e-mail do Gmail ou do Google Workspace

• Um endereço de e-mail de Grupo do Google

• Um nome de domínio do Google Workspace

Acessar o aplicativo

1. No seu navegador, acesse web-site-url.

2. Para atualizar a página, clique em Atualizar refresh.

3. Na tela de login, faça login com suas credenciais do Google.

   Será exibida uma página "Hello user-email-address" com seu endereço de e-mail.

   Se você ainda vir a mesma página de antes, talvez o navegador não esteja atualizando totalmente as novas solicitações, agora que você ativou o IAP. Feche todas as janelas do navegador, volte a abri-las e tente novamente.

Conceitos de autenticação

Existem várias formas de um aplicativo autenticar seus usuários e restringir o acesso somente a usuários autorizados. Veja nas seções a seguir os métodos de autenticação comuns, em nível de esforço decrescente para o aplicativo.

Autenticação gerenciada pelo aplicativo

Com esse método, o aplicativo gerencia cada aspecto da autenticação de usuários por conta própria. O aplicativo precisa manter o próprio banco de dados de credenciais e gerenciar sessões de usuários, além de fornecer funções para gerenciar contas e senhas, verificar credenciais e emitir, verificar e atualizar sessões de usuário com cada login autenticado. O diagrama a seguir ilustra o método de autenticação gerenciado pelo aplicativo.

Conforme mostrado no diagrama, depois que o usuário faz login, o aplicativo cria e mantém informações sobre a sessão do usuário. Quando o usuário faz uma solicitação ao aplicativo, nela, devem estar incluídas informações da sessão que o aplicativo é responsável por verificar.

A principal vantagem dessa abordagem é que ela é autossuficiente e está sob controle do aplicativo. O app não precisa estar disponível na Internet. A principal desvantagem é que agora o aplicativo é responsável por fornecer todos os recursos de gerenciamento de contas e por proteger todos os dados confidenciais das credenciais.

Autenticação externa com OAuth2

Uma boa alternativa para gerenciar tudo no aplicativo é usar um serviço de identidade externo, como o Google, que lida com todas as informações e funcionalidades da conta do usuário e é responsável por proteger credenciais confidenciais. Quando um usuário tenta fazer login no aplicativo, a solicitação é redirecionada ao serviço de identidade, que o autentica e redireciona a solicitação de volta ao aplicativo com as informações de autenticação necessárias. Para mais informações, consulte Usar o OAuth 2.0 para aplicativos de servidor da Web

O diagrama a seguir ilustra a autenticação externa com o método OAuth2.

O fluxo no diagrama começa quando o usuário envia uma solicitação para acessar o aplicativo. Em vez de responder diretamente, o aplicativo redireciona o navegador do usuário para a plataforma de identidade do Google, que exibe uma página de login no Google. Após o login, o navegador do usuário é direcionado de volta para o aplicativo. Essa solicitação inclui informações que o aplicativo pode usar para procurar informações sobre o usuário agora autenticado, e o aplicativo agora responde ao usuário.

Esse método tem muitas vantagens para o aplicativo. Ele delega todos os recursos e riscos de gerenciamento da conta ao serviço externo, o que pode melhorar o login e a segurança da conta sem precisar alterar o app. No entanto, como mostrado no diagrama anterior, o aplicativo precisa ter acesso à Internet para usar esse método. Além disso, o app é responsável por gerenciar as sessões depois que o usuário é autenticado.

Identity-Aware Proxy

A terceira abordagem discutida neste tutorial é usar o IAP para gerenciar todas as autenticações e as sessões com qualquer alteração no aplicativo. O IAP intercepta todas as solicitações da Web para o app, bloqueia todas que não foram autenticadas e transmite outros dados de identidade de usuário adicionados a cada solicitação.

O gerenciamento da solicitação é mostrado no diagrama a seguir.

Solicitações de usuários são interceptadas pelo IAP, que bloqueia solicitações não autenticadas. As solicitações autenticadas são transmitidas ao aplicativo, desde que o usuário autenticado esteja na lista de usuários permitidos. As solicitações transmitidas por meio do IAP têm cabeçalhos adicionados que identificam o usuário que fez a solicitação.

O aplicativo não precisa mais lidar com informações de conta ou sessão do usuário. Qualquer operação que precise de um identificador exclusivo do usuário pode consegui-lo diretamente de cada solicitação da Web recebida. No entanto, esse método só pode ser usado para serviços de computação compatíveis com o IAP, como o App Engine e os balanceadores de carga. Não é possível usar o IAP em uma máquina de desenvolvimento local.