Adicionar autenticação ao seu aplicativo web Go

Este guia mostrará como integrar o Logto ao seu aplicativo web Go.

dica

A demonstração a seguir é construída com base no Gin Web Framework. Você também pode integrar o Logto em outros frameworks seguindo os mesmos passos.
O projeto de exemplo em Go está disponível em nosso repositório Go SDK.

Pré-requisitos

Uma conta Logto Cloud ou um Logto auto-hospedado.
Um aplicativo web tradicional Logto criado.

Instalação

Execute no diretório raiz do projeto:

go get github.com/logto-io/go

Adicione o pacote github.com/logto-io/go/client ao código do seu aplicativo:

main.go
// main.go
package main

import (
	"github.com/gin-gonic/gin"
	// Adicionar dependência
	"github.com/logto-io/go/client"
)

func main() {
	router := gin.Default()
	router.GET("/", func(c *gin.Context) {
		c.String(200, "Hello Logto!")
	})
	router.Run(":3000")
}

Integração

Criar um armazenamento de sessão

Em aplicativos web tradicionais, as informações de autenticação do usuário serão armazenadas na sessão do usuário.

O Logto SDK fornece uma interface Storage, você pode implementar um adaptador Storage com base no seu framework web para que o Logto SDK possa armazenar informações de autenticação do usuário na sessão.

nota

NÃO recomendamos o uso de sessões baseadas em cookies, pois as informações de autenticação do usuário armazenadas pelo Logto podem exceder o limite de tamanho do cookie. Neste exemplo, usamos sessões baseadas em memória. Você pode usar Redis, MongoDB e outras tecnologias em produção para armazenar sessões conforme necessário.

O tipo Storage no Logto SDK é o seguinte:

github.com/logto-io/client/storage.go
package client

type Storage interface {
	GetItem(key string) string
	SetItem(key, value string)
}

Usamos o middleware github.com/gin-contrib/sessions como exemplo para demonstrar esse processo.

Aplique o middleware ao aplicativo, para que possamos obter a sessão do usuário pelo contexto da solicitação do usuário no manipulador de rotas:

main.go
package main

import (
	"github.com/gin-contrib/sessions"
	"github.com/gin-contrib/sessions/memstore"
	"github.com/gin-gonic/gin"
	"github.com/logto-io/go/client"
)

func main() {
	router := gin.Default()

	// Usamos sessão baseada em memória neste exemplo
	store := memstore.NewStore([]byte("seu segredo de sessão"))
	router.Use(sessions.Sessions("logto-session", store))

	router.GET("/", func(ctx *gin.Context) {
		// Obter sessão do usuário
		session := sessions.Default(ctx)
		// ...
		ctx.String(200, "Olá Logto!")
	})
	router.Run(":3000")
}

Crie um arquivo session_storage.go, defina um SessionStorage e implemente as interfaces Storage do Logto SDK:

session_storage.go
package main

import (
	"github.com/gin-contrib/sessions"
)

type SessionStorage struct {
	session sessions.Session
}

func (storage *SessionStorage) GetItem(key string) string {
	value := storage.session.Get(key)
	if value == nil {
		return ""
	}
	return value.(string)
}

func (storage *SessionStorage) SetItem(key, value string) {
	storage.session.Set(key, value)
	storage.session.Save()
}

Agora, no manipulador de rotas, você pode criar um armazenamento de sessão para o Logto:

session := sessions.Default(ctx)
sessionStorage := &SessionStorage{session: session}

Iniciar LogtoClient

Primeiro, crie uma configuração Logto:

main.go
func main() {
	// ...
	logtoConfig := &client.LogtoConfig{
		Endpoint:  "<your-logto-endpoint>", // Ex.: http://localhost:3001
		AppId:     "<your-application-id>",
		AppSecret: "<your-application-secret>",
	}
	// ...
}

dica

Você pode encontrar e copiar o "App Secret" na página de detalhes do aplicativo no Admin Console:

Em seguida, você pode criar um LogtoClient para cada solicitação de usuário com a configuração Logto acima:

main.go
func main() {
	// ...

	router.GET("/", func(ctx *gin.Context) {
		// Criar LogtoClient
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// Usar Logto para controlar o conteúdo da página inicial
		authState := "Você não está logado neste site. :("

		if logtoClient.IsAuthenticated() {
			authState = "Você está logado neste site! :)"
		}

		homePage := `<h1>Olá Logto</h1>` +
			"<div>" + authState + "</div>"

		ctx.Data(http.StatusOK, "text/html; charset=utf-8", []byte(homePage))
	})

	// ...
}

Configurar seu aplicativo

Antes de mergulharmos nos detalhes, aqui está uma visão geral rápida da experiência do usuário final. O processo de login pode ser simplificado da seguinte forma:

Seu aplicativo invoca o método de login.
O usuário é redirecionado para a página de login do Logto. Para aplicativos nativos, o navegador do sistema é aberto.
O usuário faz login e é redirecionado de volta para o seu aplicativo (configurado como o URI de redirecionamento).

Sobre o login baseado em redirecionamento

Este processo de autenticação segue o protocolo OpenID Connect (OIDC), e o Logto aplica medidas de segurança rigorosas para proteger o login do usuário.
Se você tiver vários aplicativos, pode usar o mesmo provedor de identidade (Logto). Uma vez que o usuário faz login em um aplicativo, o Logto completará automaticamente o processo de login quando o usuário acessar outro aplicativo.

Para saber mais sobre a lógica e os benefícios do login baseado em redirecionamento, veja Experiência de login do Logto explicada.

nota

Nos trechos de código a seguir, assumimos que seu aplicativo está sendo executado em http://localhost:3000/.

Configurar URIs de redirecionamento

Vá para a página de detalhes do aplicativo no Logto Console. Adicione um URI de redirecionamento http://localhost:3000/callback.

URI de redirecionamento no Logto Console

Assim como no login, os usuários devem ser redirecionados para o Logto para sair da sessão compartilhada. Uma vez concluído, seria ótimo redirecionar o usuário de volta para o seu site. Por exemplo, adicione http://localhost:3000/ como a seção de URI de redirecionamento pós logout.

Em seguida, clique em "Salvar" para salvar as alterações.

Lidar com redirecionamento

Quando o usuário faz login com sucesso na página de login do Logto, o Logto redirecionará o usuário para o URI de redirecionamento.

Como o URI de redirecionamento é http://localhost:3000/callback, adicionamos a rota /callback para lidar com o callback após o login.

main.go
func main() {
	// ...

	// Adiciona uma rota para lidar com solicitações de callback de login
	router.GET("/callback", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// A solicitação de callback de login é tratada pelo Logto
		err := logtoClient.HandleSignInCallback(ctx.Request)
		if err != nil {
			ctx.String(http.StatusInternalServerError, err.Error())
			return
		}

		// Redireciona para a página especificada pelo desenvolvedor.
		// Este exemplo leva o usuário de volta à página inicial.
		ctx.Redirect(http.StatusTemporaryRedirect, "/")
	})

	// ...
}

Após o URI de redirecionamento ser configurado, adicionamos uma rota sign-in para lidar com a solicitação de login e também adicionamos um link de login na página inicial:

main.go
func main() {
	// ...

	// Adiciona um link para realizar uma solicitação de login na página inicial
	router.GET("/", func(ctx *gin.Context) {
		// ...
		homePage := `<h1>Hello Logto</h1>` +
			"<div>" + authState + "</div>" +
			// Adiciona link
			`<div><a href="/sign-in">Sign In</a></div>`

		ctx.Data(http.StatusOK, "text/html; charset=utf-8", []byte(homePage))
	})

	// Adiciona uma rota para lidar com solicitações de login
	router.GET("/sign-in", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// A solicitação de login é tratada pelo Logto.
		// O usuário será redirecionado para o URI de redirecionamento ao fazer login.
		signInUri, err := logtoClient.SignIn("http://localhost:3000/callback")
		if err != nil {
			ctx.String(http.StatusInternalServerError, err.Error())
			return
		}

		// Redireciona o usuário para a página de login do Logto.
		ctx.Redirect(http.StatusTemporaryRedirect, signInUri)
	})

	// ...
}

Agora, quando seu usuário visitar http://localhost:3000/sign-in, ele será redirecionado para a página de login do Logto.

Implementar rota de logout

Semelhante ao fluxo de login, quando o usuário faz logout, o Logto redirecionará o usuário para o URI de redirecionamento pós-logout.

Agora, vamos adicionar a rota sign-out para lidar com a solicitação de logout e também adicionar um link de logout na página inicial:

main.go
func main() {
	// ...

	// Adicionar um link para realizar uma solicitação de logout na página inicial
	router.GET("/", func(ctx *gin.Context) {
		// ...
		homePage := `<h1>Hello Logto</h1>` +
			"<div>" + authState + "</div>" +
			`<div><a href="/sign-in">Sign In</a></div>` +
			// Adicionar link
			`<div><a href="/sign-out">Sign Out</a></div>`

		ctx.Data(http.StatusOK, "text/html; charset=utf-8", []byte(homePage))
	})

	// Adicionar uma rota para lidar com solicitações de logout
	router.GET("/sign-out", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// A solicitação de logout é tratada pelo Logto.
		// O usuário será redirecionado para o URI de Redirecionamento Pós-Logout ao sair.
		signOutUri, signOutErr := logtoClient.SignOut("http://localhost:3000")

		if signOutErr != nil {
			ctx.String(http.StatusOK, signOutErr.Error())
			return
		}

		ctx.Redirect(http.StatusTemporaryRedirect, signOutUri)
	})

	// ...
}

Após o usuário fazer uma solicitação de logout, o Logto limpará todas as informações de autenticação do usuário na sessão.

Ponto de verificação: Teste seu aplicativo

Agora, você pode testar seu aplicativo:

Execute seu aplicativo, você verá o botão de login.
Clique no botão de login, o SDK iniciará o processo de login e redirecionará você para a página de login do Logto.
Após fazer login, você será redirecionado de volta para o seu aplicativo e verá o botão de logout.
Clique no botão de logout para limpar o armazenamento local e sair.

Obter informações do usuário

Exibir informações do usuário

Para exibir as informações do usuário, você pode usar o método client.GetIdTokenClaims. Por exemplo, adicione uma rota:

main.go
func main() {
    //...

    router.GET("/user-id-token-claims", func(ctx *gin.Context) {
      session := sessions.Default(ctx)
      logtoClient := client.NewLogtoClient(logtoConfig, &SessionStorage{session: session})

      idTokenClaims, err := logtoClient.GetIdTokenClaims()

      if err != nil {
        ctx.String(http.StatusOK, err.Error())
      }

      ctx.JSON(http.StatusOK, idTokenClaims)
    })
}

Solicitar reivindicações adicionais

Você pode perceber que algumas informações do usuário estão faltando no objeto retornado de client.GetIdTokenClaims(). Isso ocorre porque OAuth 2.0 e OpenID Connect (OIDC) são projetados para seguir o princípio do menor privilégio (PoLP), e o Logto é construído com base nesses padrões.

Por padrão, reivindicações limitadas são retornadas. Se você precisar de mais informações, pode solicitar escopos adicionais para acessar mais reivindicações.

info

Uma "reivindicação (Claim)" é uma afirmação feita sobre um sujeito; um "escopo (Scope)" é um grupo de reivindicações. No caso atual, uma reivindicação é uma informação sobre o usuário.

Aqui está um exemplo não normativo da relação escopo - reivindicação:

dica

A reivindicação "sub" significa "sujeito (Subject)", que é o identificador único do usuário (ou seja, ID do usuário).

O Logto SDK sempre solicitará três escopos: openid, profile e offline_access.

Para solicitar escopos adicionais, você pode passá-los para o objeto LogtoConfig. Por exemplo:

main.go
logtoConfig := &client.LogtoConfig{
  // ...outras configurações
  Scopes: []string{"email", "phone"},
}

Então você pode acessar as reivindicações adicionais no valor de retorno de client.GetIdTokenClaims():

idTokenClaims, error := client.GetIdTokenClaims()
// Agora você pode acessar as reivindicações adicionais `claims.email`, `claims.phone`, etc.

Reivindicações que precisam de solicitações de rede

Para evitar o inchaço do Token de ID (ID token), algumas reivindicações requerem solicitações de rede para serem buscadas. Por exemplo, a reivindicação custom_data não está incluída no objeto do usuário, mesmo que seja solicitada nos escopos. Para acessar essas reivindicações, você pode usar o método client.FetchUserInfo():

userInfo, error := client.FetchUserInfo()
// Agora você pode acessar a reivindicação `userInfo.custom_data`

Este método buscará as informações do usuário solicitando ao endpoint userinfo. Para saber mais sobre os escopos e reivindicações disponíveis, veja a seção Escopos e reivindicações.

Escopos e reivindicações

Logto usa as convenções de escopos e reivindicações do OIDC para definir os escopos e reivindicações para recuperar informações do usuário do Token de ID e do endpoint userinfo do OIDC. Tanto "escopo" quanto "reivindicação" são termos das especificações OAuth 2.0 e OpenID Connect (OIDC).

Aqui está a lista de Escopos (Scopes) suportados e as Reivindicações (Claims) correspondentes:

openid

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
sub	`string`	O identificador único do usuário	Não

profile

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
name	`string`	O nome completo do usuário	Não
username	`string`	O nome de usuário do usuário	Não
picture	`string`	URL da foto de perfil do Usuário Final. Este URL DEVE referir-se a um arquivo de imagem (por exemplo, um arquivo de imagem PNG, JPEG ou GIF), em vez de uma página da Web contendo uma imagem. Note que este URL DEVE referenciar especificamente uma foto de perfil do Usuário Final adequada para exibição ao descrever o Usuário Final, em vez de uma foto arbitrária tirada pelo Usuário Final.	Não
created_at	`number`	Hora em que o Usuário Final foi criado. O tempo é representado como o número de milissegundos desde a época Unix (1970-01-01T00:00:00Z).	Não
updated_at	`number`	Hora em que as informações do Usuário Final foram atualizadas pela última vez. O tempo é representado como o número de milissegundos desde a época Unix (1970-01-01T00:00:00Z).	Não

Outras reivindicações padrão incluem family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo e locale também serão incluídas no escopo profile sem a necessidade de solicitar o endpoint userinfo. Uma diferença em relação às reivindicações acima é que essas reivindicações só serão retornadas quando seus valores não estiverem vazios, enquanto as reivindicações acima retornarão null se os valores estiverem vazios.

nota

Ao contrário das reivindicações padrão, as reivindicações created_at e updated_at estão usando milissegundos em vez de segundos.

email

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
email	`string`	O endereço de email do usuário	Não
email_verified	`boolean`	Se o endereço de email foi verificado	Não

phone

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
phone_number	`string`	O número de telefone do usuário	Não
phone_number_verified	`boolean`	Se o número de telefone foi verificado	Não

address

Por favor, consulte o OpenID Connect Core 1.0 para os detalhes da reivindicação de endereço.

custom_data

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
custom_data	`object`	Os dados personalizados do usuário	Sim

identities

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
identities	`object`	As identidades vinculadas do usuário	Sim
sso_identities	`array`	As identidades SSO vinculadas do usuário	Sim

urn:logto:scope:organizations

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
organizations	`string[]`	Os IDs das organizações às quais o usuário pertence	Não
organization_data	`object[]`	Os dados das organizações às quais o usuário pertence	Sim

urn:logto:scope:organization_roles

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
organization_roles	`string[]`	Os papéis da organização aos quais o usuário pertence com o formato `<organization_id>:<role_name>`	Não

Considerando o desempenho e o tamanho dos dados, se "Precisa de userinfo?" for "Sim", isso significa que a reivindicação não aparecerá no Token de ID, mas será retornada na resposta do endpoint userinfo.

Recursos de API e organizações

Recomendamos ler 🔐 Controle de Acesso Baseado em Papel (RBAC) primeiro para entender os conceitos básicos do RBAC do Logto e como configurar corretamente os recursos de API.

Configurar cliente Logto

Depois de configurar os recursos de API, você pode adicioná-los ao configurar o Logto em seu aplicativo:

logtoConfig := &client.LogtoConfig{
    // ...outras configurações
    Resources: []string{"https://shopping.your-app.com/api", "https://store.your-app.com/api"},
}

Cada recurso de API tem suas próprias permissões (escopos).

Por exemplo, o recurso https://shopping.your-app.com/api tem as permissões shopping:read e shopping:write, e o recurso https://store.your-app.com/api tem as permissões store:read e store:write.

Para solicitar essas permissões, você pode adicioná-las ao configurar o Logto em seu aplicativo:

logtoConfig := &client.LogtoConfig{
    // ...other configs
    Scopes:    []string{"shopping:read", "shopping:write", "store:read", "store:write"},
    Resources: []string{"https://shopping.your-app.com/api", "https://store.your-app.com/api"},
}

Você pode notar que os escopos são definidos separadamente dos recursos de API. Isso ocorre porque Resource Indicators for OAuth 2.0 especifica que os escopos finais para a solicitação serão o produto cartesiano de todos os escopos em todos os serviços de destino.

Assim, no caso acima, os escopos podem ser simplificados a partir da definição no Logto, ambos os recursos de API podem ter escopos read e write sem o prefixo. Então, na configuração do Logto:

logtoConfig := &client.LogtoConfig{
    // ...outras configurações
    Scopes:    []string{"read", "write"},
    Resources: []string{"https://shopping.your-app.com/api", "https://store.your-app.com/api"},
}

Para cada recurso de API, ele solicitará os escopos read e write.

nota

Não há problema em solicitar escopos que não estão definidos nos recursos de API. Por exemplo, você pode solicitar o escopo email mesmo que os recursos de API não tenham o escopo email disponível. Escopos indisponíveis serão ignorados com segurança.

Após o login bem-sucedido, o Logto emitirá os escopos apropriados para os recursos de API de acordo com os papéis do usuário.

Buscar token de acesso para o recurso de API

Para buscar o token de acesso para um recurso de API específico, você pode usar o método GetAccessToken:

accessToken, error := logtoClient.GetAccessToken("https://shopping.your-app.com/api")

Este método retornará um token de acesso JWT que pode ser usado para acessar o recurso de API quando o usuário tiver as permissões relacionadas. Se o token de acesso em cache atual tiver expirado, este método tentará automaticamente usar um token de atualização para obter um novo token de acesso.

Buscar tokens de organização

Se organização é um conceito novo para você, por favor, leia 🏢 Organizações (Multi-tenancy) para começar.

Você precisa adicionar o escopo core.UserScopeOrganizations ao configurar o cliente Logto:

logtoConfig := &client.LogtoConfig{
    // ...other configs
    Scopes: []string{core.UserScopeOrganizations},
}

Uma vez que o usuário esteja autenticado, você pode buscar o token de organização para o usuário:

// Substitua o parâmetro por um ID de organização válido.
// IDs de organização válidos para o usuário podem ser encontrados na reivindicação do token de ID `organizations`.
accessToken, error := logtoClient.GetOrganizationToken("organization-id")

// ou
accessTokenClaims, error := logtoClient.GetOrganizationTokenClaims("organization-id")

Recursos de API da organização (Organization API resources)

Para buscar um token de acesso para um recurso de API em uma organização, você pode usar o método getAccessToken com o recurso de API e o ID da organização como parâmetros:

accessToken, error := client.GetAccessToken(
  'https://shopping.your-app.com/api',
  organizationId
);

Leituras adicionais

Fluxos do usuário final: fluxos de autenticação, fluxos de conta e fluxos de organização Configurar conectores Proteger sua API

Pré-requisitos​

Instalação​

Integração​

Criar um armazenamento de sessão​

Iniciar LogtoClient​

Configurar seu aplicativo​

Configurar URIs de redirecionamento​

Lidar com redirecionamento​

Implementar rota de login​

Implementar rota de logout​

Ponto de verificação: Teste seu aplicativo​

Obter informações do usuário​

Exibir informações do usuário​

Solicitar reivindicações adicionais​

Reivindicações que precisam de solicitações de rede​

Escopos e reivindicações​

Recursos de API e organizações​

Configurar cliente Logto​

Buscar token de acesso para o recurso de API​

Buscar tokens de organização​

Recursos de API da organização (Organization API resources)​

Leituras adicionais​

Pré-requisitos

Instalação

Integração

Criar um armazenamento de sessão

Iniciar LogtoClient

Configurar seu aplicativo

Configurar URIs de redirecionamento

Lidar com redirecionamento

Implementar rota de login

Implementar rota de logout

Ponto de verificação: Teste seu aplicativo

Obter informações do usuário

Exibir informações do usuário

Solicitar reivindicações adicionais

Reivindicações que precisam de solicitações de rede

Escopos e reivindicações

Recursos de API e organizações

Configurar cliente Logto

Buscar token de acesso para o recurso de API

Buscar tokens de organização

Recursos de API da organização (Organization API resources)

Leituras adicionais