Ajoutez l’authentification à votre application web Go

Ce guide vous montrera comment intégrer Logto dans votre application web Go.

astuce

La démonstration suivante est construite sur le Gin Web Framework. Vous pouvez également intégrer Logto dans d'autres frameworks en suivant les mêmes étapes.
Le projet d'exemple Go est disponible sur notre dépôt Go SDK.

Prérequis

Un compte Logto Cloud ou un Logto auto-hébergé.
Une application web traditionnelle Logto créée.

Installation

Exécutez dans le répertoire racine du projet :

go get github.com/logto-io/go

Ajoutez le package github.com/logto-io/go/client à votre code d'application :

main.go
// main.go
package main

import (
	"github.com/gin-gonic/gin"
	// Add dependency
	"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")
}

Intégration

Créer un stockage de session

Dans les applications web traditionnelles, les informations d'Authentification (Authentication) de l'utilisateur sont stockées dans la session utilisateur.

Le SDK Logto fournit une interface Storage, vous pouvez implémenter un adaptateur Storage basé sur votre framework web afin que le SDK Logto puisse stocker les informations d'Authentification (Authentication) de l'utilisateur dans la session.

remarque

Nous ne recommandons PAS d'utiliser des sessions basées sur les cookies, car les informations d'Authentification (Authentication) de l'utilisateur stockées par Logto peuvent dépasser la limite de taille des cookies. Dans cet exemple, nous utilisons des sessions basées sur la mémoire. Vous pouvez utiliser Redis, MongoDB et d'autres technologies en production pour stocker les sessions selon vos besoins.

Le type Storage dans le SDK Logto est le suivant :

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

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

Nous utilisons le middleware github.com/gin-contrib/sessions comme exemple pour démontrer ce processus.

Appliquez le middleware à l'application, afin que nous puissions obtenir la session utilisateur par le contexte de la requête utilisateur dans le gestionnaire de route :

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()

	// Nous utilisons une session basée sur la mémoire dans cet exemple
	store := memstore.NewStore([]byte("your session secret"))
	router.Use(sessions.Sessions("logto-session", store))

	router.GET("/", func(ctx *gin.Context) {
		// Obtenir la session utilisateur
		session := sessions.Default(ctx)
		// ...
		ctx.String(200, "Hello Logto!")
	})
	router.Run(":3000")
}

Créez un fichier session_storage.go, définissez un SessionStorage et implémentez les interfaces Storage du SDK Logto :

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()
}

Maintenant, dans le gestionnaire de route, vous pouvez créer un stockage de session pour Logto :

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

Initialiser LogtoClient

Tout d'abord, créez une configuration Logto :

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

astuce

Vous pouvez trouver et copier le "Secret de l'application" depuis la page des détails de l'application dans la Console d'administration :

Ensuite, vous pouvez créer un LogtoClient pour chaque requête utilisateur avec la configuration Logto ci-dessus :

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

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

		// Utiliser Logto pour contrôler le contenu de la page d'accueil
		authState := "Vous n'êtes pas connecté à ce site. :("

		if logtoClient.IsAuthenticated() {
			authState = "Vous êtes connecté à ce site ! :)"
		}

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

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

	// ...
}

Configurer votre application

Avant de plonger dans les détails, voici un aperçu rapide de l'Expérience utilisateur. Le processus de connexion peut être simplifié comme suit :

Votre application lance la méthode de connexion.
L'utilisateur est redirigé vers la page de connexion Logto. Pour les applications natives, le navigateur système est ouvert.
L'utilisateur se connecte et est redirigé vers votre application (configurée comme l'URI de redirection).

Concernant la connexion basée sur la redirection

Ce processus d'authentification (Authentication) suit le protocole OpenID Connect (OIDC), et Logto applique des mesures de sécurité strictes pour protéger la connexion utilisateur.
Si vous avez plusieurs applications, vous pouvez utiliser le même fournisseur d’identité (Logto). Une fois que l'utilisateur se connecte à une application, Logto complétera automatiquement le processus de connexion lorsque l'utilisateur accède à une autre application.

Pour en savoir plus sur la logique et les avantages de la connexion basée sur la redirection, consultez Expérience de connexion Logto expliquée.

remarque

Dans les extraits de code suivants, nous supposons que votre application fonctionne sur http://localhost:3000/.

Configurer les URIs de redirection

Passez à la page des détails de l'application de Logto Console. Ajoutez une URI de redirection http://localhost:3000/callback.

Tout comme pour la connexion, les utilisateurs doivent être redirigés vers Logto pour se déconnecter de la session partagée. Une fois terminé, il serait idéal de rediriger l'utilisateur vers votre site web. Par exemple, ajoutez http://localhost:3000/ comme section d'URI de redirection après déconnexion.

Ensuite, cliquez sur "Enregistrer" pour sauvegarder les modifications.

Gérer la redirection

Lorsque l'utilisateur se connecte avec succès sur la page de connexion Logto, Logto redirigera l'utilisateur vers l'URI de redirection.

Étant donné que l'URI de redirection est http://localhost:3000/callback, nous ajoutons la route /callback pour gérer le rappel après la connexion.

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

	// Ajouter une route pour gérer les requêtes de rappel de connexion
	router.GET("/callback", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// La requête de rappel de connexion est gérée par Logto
		err := logtoClient.HandleSignInCallback(ctx.Request)
		if err != nil {
			ctx.String(http.StatusInternalServerError, err.Error())
			return
		}

		// Aller à la page spécifiée par le développeur.
		// Cet exemple ramène l'utilisateur à la page d'accueil.
		ctx.Redirect(http.StatusTemporaryRedirect, "/")
	})

	// ...
}

Implémenter la route de connexion

Après avoir configuré l'URI de redirection, nous ajoutons une route sign-in pour gérer la requête d’authentification (Authentication) et ajoutons également un lien de connexion sur la page d'accueil :

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

	// Ajouter un lien pour effectuer une requête d’authentification (Authentication) sur la page d'accueil
	router.GET("/", func(ctx *gin.Context) {
		// ...
		homePage := `<h1>Hello Logto</h1>` +
			"<div>" + authState + "</div>" +
			// Ajouter un lien
			`<div><a href="/sign-in">Sign In</a></div>`

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

	// Ajouter une route pour gérer les requêtes d’authentification (Authentication)
	router.GET("/sign-in", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// La requête d’authentification (Authentication) est gérée par Logto.
		// L'utilisateur sera redirigé vers l'URI de redirection une fois connecté.
		signInUri, err := logtoClient.SignIn("http://localhost:3000/callback")
		if err != nil {
			ctx.String(http.StatusInternalServerError, err.Error())
			return
		}

		// Rediriger l'utilisateur vers la page de connexion Logto.
		ctx.Redirect(http.StatusTemporaryRedirect, signInUri)
	})

	// ...
}

Maintenant, lorsque votre utilisateur visite http://localhost:3000/sign-in, il sera redirigé vers la page de connexion Logto.

Implémenter la route de déconnexion

Similaire au flux de connexion, lorsque l'utilisateur se déconnecte, Logto redirigera l'utilisateur vers l'URI de redirection post-déconnexion.

Ajoutons maintenant la route sign-out pour gérer la requête de déconnexion et ajoutons également un lien de déconnexion sur la page d'accueil :

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

	// Ajoutez un lien pour effectuer une requête de déconnexion sur la page d'accueil
	router.GET("/", func(ctx *gin.Context) {
		// ...
		homePage := `<h1>Bonjour Logto</h1>` +
			"<div>" + authState + "</div>" +
			`<div><a href="/sign-in">Se connecter</a></div>` +
			// Ajouter un lien
			`<div><a href="/sign-out">Se déconnecter</a></div>`

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

	// Ajoutez une route pour gérer les requêtes de déconnexion
	router.GET("/sign-out", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// La requête de déconnexion est gérée par Logto.
		// L'utilisateur sera redirigé vers l'URI de redirection post-déconnexion une fois déconnecté.
		signOutUri, signOutErr := logtoClient.SignOut("http://localhost:3000")

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

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

	// ...
}

Après que l'utilisateur ait effectué une requête de déconnexion, Logto effacera toutes les informations d'authentification de l'utilisateur dans la session.

Point de contrôle : Testez votre application

Maintenant, vous pouvez tester votre application :

Exécutez votre application, vous verrez le bouton de connexion.
Cliquez sur le bouton de connexion, le SDK initiera le processus de connexion et vous redirigera vers la page de connexion Logto.
Après vous être connecté, vous serez redirigé vers votre application et verrez le bouton de déconnexion.
Cliquez sur le bouton de déconnexion pour effacer le stockage local et vous déconnecter.

Obtenir des informations sur l'utilisateur

Afficher les informations de l'utilisateur

Pour afficher les informations de l'utilisateur, vous pouvez utiliser la méthode client.GetIdTokenClaims. Par exemple, ajoutez une route :

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)
    })
}

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par client.GetIdTokenClaims(). Cela est dû au fait que OAuth 2.0 et OpenID Connect (OIDC) sont conçus pour suivre le principe du moindre privilège (PoLP), et Logto est construit sur ces normes.

Par défaut, des revendications limitées sont retournées. Si vous avez besoin de plus d'informations, vous pouvez demander des portées supplémentaires pour accéder à plus de revendications.

info

Une "revendication" est une assertion faite à propos d'un sujet ; une "portée" est un groupe de revendications. Dans le cas actuel, une revendication est une information sur l'utilisateur.

Voici un exemple non normatif de la relation portée - revendication :

astuce

La revendication "sub" signifie "sujet", qui est l'identifiant unique de l'utilisateur (c'est-à-dire l'ID utilisateur).

Le SDK Logto demandera toujours trois portées : openid, profile et offline_access.

Pour demander des Portées supplémentaires, vous pouvez passer les Portées à l'objet LogtoConfig. Par exemple :

main.go
logtoConfig := &client.LogtoConfig{
  // ...other configs
  Scopes: []string{"email", "phone"},
}

Ensuite, vous pouvez accéder aux Revendications supplémentaires dans la valeur de retour de client.GetIdTokenClaims() :

idTokenClaims, error := client.GetIdTokenClaims()
// Now you can access additional claims `claims.email`, `claims.phone`, etc.

Revendications nécessitant des requêtes réseau

Pour éviter de surcharger le jeton d’identifiant (ID token), certaines revendications nécessitent des requêtes réseau pour être récupérées. Par exemple, la revendication custom_data n'est pas incluse dans l'objet utilisateur même si elle est demandée dans les portées. Pour accéder à ces revendications, vous pouvez utiliser la méthode client.FetchUserInfo() :

userInfo, error := client.FetchUserInfo()
// Now you can access the claim `userInfo.custom_data`

Cette méthode récupérera les informations de l'utilisateur en faisant une requête à l' point de terminaison userinfo. Pour en savoir plus sur les portées et revendications disponibles, consultez la section Portées et revendications.

Portées et Revendications

Logto utilise les conventions de portées et revendications OIDC pour définir les Portées et Revendications pour récupérer les informations utilisateur à partir du Jeton d’identifiant et du point de terminaison OIDC userinfo. Les termes "Portée" et "Revendication" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).

Voici la liste des Portées (Scopes) prises en charge et les Revendications (Claims) correspondantes :

openid

Nom de la revendication	Type	Description	Besoin d'userinfo ?
sub	`string`	L'identifiant unique de l'utilisateur	Non

profile

Nom de la revendication	Type	Description	Besoin d'userinfo ?
name	`string`	Le nom complet de l'utilisateur	Non
username	`string`	Le nom d'utilisateur de l'utilisateur	Non
picture	`string`	URL de la photo de profil de l'utilisateur final. Cette URL DOIT faire référence à un fichier image (par exemple, un fichier image PNG, JPEG ou GIF), plutôt qu'à une page Web contenant une image. Notez que cette URL DOIT spécifiquement référencer une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, plutôt qu'une photo arbitraire prise par l'utilisateur final.	Non
created_at	`number`	Heure à laquelle l'utilisateur final a été créé. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).	Non
updated_at	`number`	Heure à laquelle les informations de l'utilisateur final ont été mises à jour pour la dernière fois. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).	Non

D'autres revendications standard incluent family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, et locale seront également incluses dans la portée profile sans avoir besoin de demander le point de terminaison userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront renvoyées que lorsque leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus renverront null si les valeurs sont vides.

remarque

Contrairement aux revendications standard, les revendications created_at et updated_at utilisent des millisecondes au lieu de secondes.

email

Nom de la revendication	Type	Description	Besoin d'userinfo ?
email	`string`	L'adresse e-mail de l'utilisateur	Non
email_verified	`boolean`	Si l'adresse e-mail a été vérifiée	Non

phone

Nom de la revendication	Type	Description	Besoin d'userinfo ?
phone_number	`string`	Le numéro de téléphone de l'utilisateur	Non
phone_number_verified	`boolean`	Si le numéro de téléphone a été vérifié	Non

address

Veuillez vous référer à OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.

custom_data

Nom de la revendication	Type	Description	Besoin d'userinfo ?
custom_data	`object`	Les données personnalisées de l'utilisateur	Oui

identities

Nom de la revendication	Type	Description	Besoin d'userinfo ?
identities	`object`	Les identités liées de l'utilisateur	Oui
sso_identities	`array`	Les identités SSO liées de l'utilisateur	Oui

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Besoin d'userinfo ?
organizations	`string[]`	Les identifiants d'organisation auxquels l'utilisateur appartient	Non
organization_data	`object[]`	Les données d'organisation auxquelles l'utilisateur appartient	Oui

urn:logto:scope:organization_roles

Nom de la revendication	Type	Description	Besoin d'userinfo ?
organization_roles	`string[]`	Les rôles d'organisation auxquels l'utilisateur appartient avec le format `<organization_id>:<role_name>`	Non

En considérant la performance et la taille des données, si "Besoin d'userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le Jeton d’identifiant (ID token), mais sera renvoyée dans la réponse du point de terminaison userinfo.

Ressources API et organisations

Nous vous recommandons de lire d'abord 🔐 Contrôle d’accès basé sur les rôles (RBAC) pour comprendre les concepts de base de Logto RBAC et comment configurer correctement les ressources API.

Configurer le client Logto

Une fois que vous avez configuré les ressources API, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

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

Chaque ressource API a ses propres permissions (portées).

Par exemple, la ressource https://shopping.your-app.com/api a les permissions shopping:read et shopping:write, et la ressource https://store.your-app.com/api a les permissions store:read et store:write.

Pour demander ces permissions, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

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"},
}

Vous pouvez remarquer que les portées sont définies séparément des ressources API. Cela est dû au fait que les Indicateurs de ressource pour OAuth 2.0 spécifient que les portées finales pour la requête seront le produit cartésien de toutes les portées de tous les services cibles.

Ainsi, dans le cas ci-dessus, les portées peuvent être simplifiées à partir de la définition dans Logto, les deux ressources API peuvent avoir les portées read et write sans le préfixe. Ensuite, dans la configuration de Logto :

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

Pour chaque ressource API, il demandera à la fois les portées read et write.

remarque

Il est acceptable de demander des portées qui ne sont pas définies dans les ressources API. Par exemple, vous pouvez demander la portée email même si les ressources API n'ont pas la portée email disponible. Les portées non disponibles seront ignorées en toute sécurité.

Après une connexion réussie, Logto émettra les portées appropriées aux ressources API en fonction des rôles de l'utilisateur.

Récupérer le jeton d’accès pour la ressource API

Pour récupérer le jeton d’accès pour une ressource API spécifique, vous pouvez utiliser la méthode GetAccessToken :

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

Cette méthode renverra un jeton d’accès JWT qui peut être utilisé pour accéder à la ressource API lorsque l’utilisateur a les Permissions associées. Si le jeton d’accès mis en cache actuel a expiré, cette méthode essaiera automatiquement d’utiliser un jeton de rafraîchissement pour obtenir un nouveau jeton d’accès.

Récupérer les jetons d’organisation

Si l'Organisation est nouvelle pour vous, veuillez lire 🏢 Organisations (Multi-tenancy) pour commencer.

Vous devez ajouter la portée core.UserScopeOrganizations lors de la configuration du client Logto :

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

Une fois l'utilisateur connecté, vous pouvez récupérer le jeton d’organisation pour l'utilisateur :

// Remplacez le paramètre par un ID d’organisation valide.
// Les ID d’organisations valides pour l’utilisateur peuvent être trouvés dans la revendication de jeton d’identifiant `organizations`.
accessToken, error := logtoClient.GetOrganizationToken("organization-id")

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

Ressources API d’organisation

Pour récupérer un jeton d’accès pour une ressource API dans une organisation, vous pouvez utiliser la méthode getAccessToken avec à la fois la ressource API et l’ID de l’organisation comme paramètres :

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

Lectures complémentaires

Flux utilisateur final : flux d'authentification, flux de compte et flux d'organisation Configurer les connecteurs Protéger votre API

Prérequis​

Installation​

Intégration​

Créer un stockage de session​

Initialiser LogtoClient​

Configurer votre application​

Configurer les URIs de redirection​

Gérer la redirection​

Implémenter la route de connexion​

Implémenter la route de déconnexion​

Point de contrôle : Testez votre application​

Obtenir des informations sur l'utilisateur​

Afficher les informations de l'utilisateur​

Demander des revendications supplémentaires​

Revendications nécessitant des requêtes réseau​

Portées et Revendications​

Ressources API et organisations​

Configurer le client Logto​

Récupérer le jeton d’accès pour la ressource API​

Récupérer les jetons d’organisation​

Ressources API d’organisation​

Lectures complémentaires​

Prérequis

Installation

Intégration

Créer un stockage de session

Initialiser LogtoClient

Configurer votre application

Configurer les URIs de redirection

Gérer la redirection

Implémenter la route de connexion

Implémenter la route de déconnexion

Point de contrôle : Testez votre application

Obtenir des informations sur l'utilisateur

Afficher les informations de l'utilisateur

Demander des revendications supplémentaires

Revendications nécessitant des requêtes réseau

Portées et Revendications

Ressources API et organisations

Configurer le client Logto

Récupérer le jeton d’accès pour la ressource API

Récupérer les jetons d’organisation

Ressources API d’organisation

Lectures complémentaires