Como autenticar usuários com o Go

Aplicativos em execução em plataformas gerenciadas pelo Google Cloud, como o App Engine podem evitar o gerenciamento de autenticação de usuários e de sessão usando o Identity-Aware Proxy (IAP) para controlar o acesso. O IAP não só controla o acesso ao aplicativo como também fornece informações sobre os usuários autenticados, incluindo o endereço de e-mail e um identificador permanente para o aplicativo na forma de novos cabeçalhos HTTP.

Objetivos

  • Exigir que os usuários do seu aplicativo do App Engine se autentiquem usando o IAP.

  • Acessar as identidades dos usuários no aplicativo para exibir o endereço de e-mail autenticado do usuário atual.

Custos

Neste tutorial, usamos os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Antes de começar

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Instale e inicialize o SDK do Cloud..
  4. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  5. Instale e inicialize o SDK do Cloud..
  6. Prepare seu ambiente para desenvolvedores.

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 um módulo Go e os módulos de que ele depende.

    module github.com/GoogleCloudPlatform/golang-samples/getting-started/authenticating-users
    
    go 1.11
    
    require (
    	cloud.google.com/go v0.97.0
    	github.com/golang-jwt/jwt v3.2.2+incompatible
    )
    
  • 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: %v", err)
    	}
    
    	projectID, err := metadata.ProjectID()
    	if err != nil {
    		return "", fmt.Errorf("metadata.ProjectID: %v", 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: %v", err)
    	}
    
    	var certs map[string]string
    	dec := json.NewDecoder(resp.Body)
    	if err := dec.Decode(&certs); err != nil {
    		return nil, fmt.Errorf("Decode: %v", 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 Cloud, acesse a página do Identity-Aware Proxy.

    Acesse a página do Identity-Aware Proxy

  6. Para atualizar a página, clique em Atualizar . 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 Cloud, acesse a página do Identity-Aware Proxy.

    Acesse a página do Identity-Aware Proxy

  2. Marque a caixa de seleção do 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 puder autenticar poderá acessar o app. Se você quiser restringir o acesso ainda mais, adicione 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 .

  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.

Opção Vantagens Desvantagens
Autenticação do aplicativo
  • O app pode ser executado em qualquer plataforma, com ou sem conexão à Internet
  • Os usuários não precisam usar nenhum outro serviço para gerenciar a autenticação
  • O aplicativo precisa gerenciar as credenciais do usuário com segurança e proteger contra divulgação
  • O aplicativo precisa manter os dados da sessão dos usuários conectados
  • O aplicativo precisa fornecer o registro de usuários, alterações de senha e recuperação de senha
OAuth2
  • O aplicativo pode ser executado em qualquer plataforma conectada à Internet, incluindo uma estação de trabalho do desenvolvedor
  • O aplicativo não precisa de registro de usuários, alterações de senha ou funções de recuperação de senha.
  • O risco de divulgação de informações do usuário é delegado a outro serviço
  • Novas medidas de segurança de login são processadas fora do aplicativo
  • Os usuários precisam se registrar no serviço de identidade
  • O aplicativo precisa manter os dados da sessão dos usuários conectados
IAP
  • O aplicativo não precisa de códigos para gerenciar usuários, a autenticação ou o estado da sessão
  • O app não tem credenciais de usuário que possam ser violadas
  • O aplicativo só pode ser executado em plataformas compatíveis com o serviço. Especificamente, determinados serviços do Google Cloud compatíveis com o IAP, como o App Engine.

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.

Fluxo 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 saber mais, consulte Como autenticar como usuário final.

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

Fluxo do OAuth 2

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.

Fluxo do IAP

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.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

  1. No Console do Cloud, acesse a página Gerenciar recursos:

    Acessar "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.