# Créer son propre layer Dans ce tutoriel, nous verrons comment implémenter un layer personnalisé qui permettra d'ajouter une authentification de type [`Basic Auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) à un proxy. ## Prérequis Avoir un environnement de développement local fonctionnel. Voir tutoriel ["Démarrer avec les sources"](./getting-started-with-sources.md). ## Étapes ### Préparer la structure de base du nouveau layer Une implémetation d'un layer se compose majoritairement de 3 éléments: - Une structure qui implémente une ou plusieurs interfaces (`director.MiddlewareLayer`, `director.RequestTransformerLayer` et/ou `director.ResponseTransformerLayer`); - Un schéma au format [JSON Schema](http://json-schema.org/) qui permettra de valider les "options" de notre layer; - Un fichier d'amorçage qui permettra à Bouncer de référencer notre nouveau layer. 1. Créer le répertoire du `package` Go qui contiendra le code de votre layer. Celui ci s'appelera `basicauth`: ``` mkdir -p internal/proxy/director/layer/basicauth ``` 2. Créer la structure de base du layer: ```go // Fichier internal/proxy/director/layer/basicauth/basicauth.go package basicauth import ( proxy "forge.cadoles.com/Cadoles/go-proxy" "forge.cadoles.com/cadoles/bouncer/internal/proxy/director" "forge.cadoles.com/cadoles/bouncer/internal/store" ) // On définit le "type" (la chaîne de caractères) qui // sera associé à notre layer const LayerType store.LayerType = "basicauth" // On déclare la structure qui // servira de socle pour notre layer type BasicAuth struct{} // Les deux méthodes suivantes, attachées à // notre structure BasicAuth, permettent de remplir // le contrat définit par l'interface // director.MiddlewareLayer // LayerType implements director.MiddlewareLayer. func (*BasicAuth) LayerType() store.LayerType { return LayerType } // C'est dans la méthode "Middleware" qu'on pourra implémenter la // logique appliquée par notre layer. // En l'état actuel l'exécution de la méthode provoquera un panic(). // Middleware implements director.MiddlewareLayer. func (*BasicAuth) Middleware(layer *store.Layer) proxy.Middleware { panic("unimplemented") } func New() *BasicAuth { return &BasicAuth{} } // Cette déclaration permet de profiter // des capacités du compilateur pour s'assurer // que la structure BasicAuth remplie toujours le // contrat imposé par l'interface director.MiddlewareLayer var _ director.MiddlewareLayer = &BasicAuth{} ``` 3. Créer le schéma JSON qui sera associé aux options possibles pour notre layer: ```json // Fichier internal/proxy/director/layer/basicauth/layer-options.json { "type": "object", "properties": {}, "additionalProperties": false } ``` 4. Puis créer le fichier Go qui embarquera ces données dans notre binaire via le package [`embed`](https://pkg.go.dev/embed): ```go // Fichier internal/proxy/director/layer/basicauth/layer_options.go package basicauth import ( _ "embed" ) //go:embed layer-options.json var RawLayerOptionsSchema []byte ``` 5. Enfin, créer le fichier d'amorçage pour référencer notre nouveau layer avec Bouncer: ```go // Fichier internal/setup/basicauth_layer.go package setup import ( "forge.cadoles.com/cadoles/bouncer/internal/config" "forge.cadoles.com/cadoles/bouncer/internal/proxy/director" "forge.cadoles.com/cadoles/bouncer/internal/proxy/director/layer/basicauth" ) // On créait une function d'initialisation qui enregistra les éléments suivants auprès de Bouncer: // - Notre nouveau type de layer // - Une fonction capable de créer une instance de notre layer // - Le schéma associé aux options de notre layer func init() { RegisterLayer(basicauth.LayerType, setupBasicAuthLayer, basicauth.RawLayerOptionsSchema) } // La fonction de création de notre layer // reçoit automatiquement la configuration actuelle de Bouncer. // Une layer plus avancé pourrait être configurable de cette manière // en créant une nouvelle section de configuration dédiée. func setupBasicAuthLayer(conf *config.Config) (director.Layer, error) { return &basicauth.BasicAuth{}, nil } ``` ## Tester l'intégration de notre nouveau layer À ce stade, notre nouveau layer est normalement référencé et donc "utilisable" dans Bouncer (si on omet le fait qu'il déclenchera une `panic()`). 1. Vérifier que notre layer est bien référencé en exécutant la commande: ``` ./bin/bouncer admin layer create --help ``` La sortie devrait ressembler à: ``` NAME: bouncer admin layer create - Create layer USAGE: bouncer admin layer create [command options] [arguments...] OPTIONS: --layer-type LAYER_TYPE Set LAYER_TYPE as layer's type (available: [basicauth queue]) [...] ``` Comme vous devriez le voir nous pouvons désormais créer des layers de type `basicauth`. 2. Créer un proxy puis une instance de notre nouveau layer associée à celui ci: ```bash # Créer un proxy ./bin/bouncer admin proxy create --proxy-name cadoles --proxy-to https://www.cadoles.com # Activer celui-ci ./bin/bouncer admin proxy update --proxy-name cadoles --proxy-enabled=true # Ajouter un layer de notre nouveau type à notre proxy ./bin/bouncer admin layer create --proxy-name cadoles --layer-name mybasicauth --layer-type basicauth # Activer notre nouveau layer ./bin/bouncer admin layer update --proxy-name cadoles --layer-name mybasicauth --layer-enabled=true ``` **Notre layer est actif** ! Cependant il est loin d'être fonctionnel. En effet, si vous faites un: ``` curl -v http://localhost:8080 ``` Vous n'aurez guère en retour qu'un: ``` * Trying 127.0.0.1:8080... * Connected to localhost (127.0.0.1) port 8080 (#0) > GET / HTTP/1.1 > Host: localhost:8080 > User-Agent: curl/8.1.2 > Accept: */* > * Empty reply from server * Closing connection 0 curl: (52) Empty reply from server ``` Et également dans la console où s'exécute le service `bouncer-proxy`, vous aurez le message: ``` 2023/06/23 18:39:59 http: panic serving 127.0.0.1:59868: unimplemented ``` **Il est temps d'implémenter réellement la logique associée à notre layer !** > **Note** Vous pouvez désactiver votre layer via le drapeau `--layer-enabled=false` et voir le site Cadoles s'afficher à nouveau ! ## Implémenter l'authentification sur notre nouveau layer Nous allons modifier la méthode `Middleware(layer *store.Layer) proxy.Middleware` attachée à notre structure `BasicAuth`. 1. Modifier le fichier contenant la structure de notre layer de la manière suivante: ```go // Fichier internal/proxy/director/layer/basicauth/basicauth.go // [...] // Middleware implements director.MiddlewareLayer. func (*BasicAuth) Middleware(layer *store.Layer) proxy.Middleware { // La méthode doit retourner un "Middleware" qui est un alias // pour les fonctions généralement utilisées // dans les librairies http en Go pour créer // une fonction d'interception/transformation de requête. return func(next http.Handler) http.Handler { fn := func(w http.ResponseWriter, r *http.Request) { // On récupère les identifiants "basic auth" transmis (ou non) // avec la requête username, password, ok := r.BasicAuth() // On créait une méthode locale pour gérer le cas d'une erreur d'authentification. unauthorized := func() { // On ajoute cette entête HTTP à la réponse pour déclencher l'affichage // de la popup d'authentification dans le navigateur web de l'utilisateur. w.Header().Set("WWW-Authenticate", `Basic realm="restricted", charset="UTF-8"`) // On retoure un code d'erreur HTTP 401 (Unauthorized) http.Error(w, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized) } if !ok { // L'entête Authorization est absente ou ne correspondant // pas à du Basic Auth, on retourne une erreur HTTP 401 et // on interrompt le traitement de la requête ici unauthorized() return } // On vérifie les identifiants associés à la requête isAuthenticated := authenticate(username, password) // Si les identifiants sont non reconnus alors // on interrompt le traitement de la requête if !isAuthenticated { unauthorized() return } // L'authentification a réussie ! On passe la main au handler HTTP suivant next.ServeHTTP(w, r) } return http.HandlerFunc(fn) } } // La méthode authenticate() prend un couple d'identifiants // est vérifie en temps constant si ceux ci correspondent à un couple // d'identifiants attendus. func authenticate(username, password string) bool { // On génère une empreinte au format sha256 pour nos identifiants usernameHash := sha256.Sum256([]byte(username)) passwordHash := sha256.Sum256([]byte(password)) // On effectue de même avec les identifiants attendus. // Pour l'instant, on utilise un couple d'identifiants en "dur". expectedUsernameHash := sha256.Sum256([]byte("foo")) expectedPasswordHash := sha256.Sum256([]byte("baz")) // On utilise la méthode subtle.ConstantTimeCompare() // pour faire la comparaison des identifiants en temps constant // et ainsi éviter les attaques par timing. usernameMatch := (subtle.ConstantTimeCompare(usernameHash[:], expectedUsernameHash[:]) == 1) passwordMatch := (subtle.ConstantTimeCompare(passwordHash[:], expectedPasswordHash[:]) == 1) // L'utilisateur est authentifié si son nom et son mot de passe // correspondent avec ceux attendus. return usernameMatch && passwordMatch } ``` 2. Dans votre navigateur, essayez d'ouvrir l'URL http://127.0.0.1:8080. La popup d'authentification devrait s'afficher et vous devriez pouvoir utiliser les identifiants définis dans la fonction `authenticate()` pour vous authentifier et accéder au site de Cadoles ! > **Note** Essayez de désactiver le layer. L'authentification est automatiquement désactivée également ! ## Déclarer des options pour pouvoir utiliser des identifiants dynamiques En l'état actuel notre layer est fonctionnel. Cependant il souffre d'un problème notable: les identifiants attendus sont statiques et embarqués en dur dans le code. Nous allons utiliser le schéma associé à nos options, jusqu'alors vide, pour pouvoir créer une paire d'identifiants attendus dynamique. 1. Modifier le schéma JSON des options de notre layer: ```json // Fichier internal/proxy/director/layer/basicauth/layer-options.json { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "additionalProperties": false } ``` 2. On modifie notre méthode `Middleware()` et la fonction `authenticate()` pour utiliser ces nouvelles options: ```go package basicauth import ( "crypto/sha256" "crypto/subtle" "net/http" proxy "forge.cadoles.com/Cadoles/go-proxy" "forge.cadoles.com/cadoles/bouncer/internal/proxy/director" "forge.cadoles.com/cadoles/bouncer/internal/store" "gitlab.com/wpetit/goweb/logger" ) const LayerType store.LayerType = "basicauth" type BasicAuth struct{} // LayerType implements director.MiddlewareLayer. func (*BasicAuth) LayerType() store.LayerType { return LayerType } // Middleware implements director.MiddlewareLayer. func (*BasicAuth) Middleware(layer *store.Layer) proxy.Middleware { // La méthode doit retourner un "Middleware" qui est un alias // pour les fonctions généralement utilisées // dans les librairies http en Go pour créer // une fonction d'interception/transformation de requête. return func(next http.Handler) http.Handler { fn := func(w http.ResponseWriter, r *http.Request) { // On récupère les identifiants "basic auth" transmis (ou non) // avec la requête username, password, ok := r.BasicAuth() // On créait une méthode locale pour gérer le cas d'une erreur d'authentification. unauthorized := func() { // On ajoute cette entête HTTP à la réponse pour déclencher l'affichage // de la popup d'authentification dans le navigateur web de l'utilisateur. w.Header().Set("WWW-Authenticate", `Basic realm="restricted", charset="UTF-8"`) // On retoure un code d'erreur HTTP 401 (Unauthorized) http.Error(w, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized) } if !ok { // L'entête Authorization est absente ou ne correspondant // pas à du Basic Auth, on retourne une erreur HTTP 401 et // on interrompt le traitement de la requête ici unauthorized() return } // On extrait les identifiants des options associées à notre layer expectedUsername, usernameExists := layer.Options["username"].(string) expectedPassword, passwordExists := layer.Options["password"].(string) // Si le nom d'utilisateur ou le mot de passe attendu n'existe pas // alors on retourne une erreur HTTP 500 à l'utilisateur. if !usernameExists || !passwordExists { logger.Error(r.Context(), "basicauth layer missing password or username option") http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError) return } // On vérifie les identifiants associés à la requête isAuthenticated := authenticate(username, password, expectedUsername, expectedPassword) // Si les identifiants sont non reconnus alors // on interrompt le traitement de la requête if !isAuthenticated { unauthorized() return } // L'authentification a réussie ! On passe la main au handler HTTP suivant next.ServeHTTP(w, r) } return http.HandlerFunc(fn) } } func authenticate(username, password string, expectedUsername, expectedPassword string) bool { // On génère une empreinte au format sha256 pour nos identifiants usernameHash := sha256.Sum256([]byte(username)) passwordHash := sha256.Sum256([]byte(password)) // On effectue de même avec les identifiants attendus. expectedUsernameHash := sha256.Sum256([]byte(expectedUsername)) expectedPasswordHash := sha256.Sum256([]byte(expectedPassword)) // On utilise la méthode subtle.ConstantTimeCompare() // pour faire la comparaison des identifiants en temps constant // et ainsi éviter les attaques par timing. usernameMatch := (subtle.ConstantTimeCompare(usernameHash[:], expectedUsernameHash[:]) == 1) passwordMatch := (subtle.ConstantTimeCompare(passwordHash[:], expectedPasswordHash[:]) == 1) // L'utilisateur est authentifié si son nom et son mot de passe // correspondent avec ceux attendus. return usernameMatch && passwordMatch } func New() *BasicAuth { return &BasicAuth{} } var _ director.MiddlewareLayer = &BasicAuth{} ``` 3. Modifiez votre layer via la commande d'administration pour déclarer une paire d'identifiants: ```bash ./bin/bouncer admin layer update --proxy-name cadoles --layer-name mybasicauth --layer-options='{"username":"jdoe","password":"notsosecret"}' ``` 4. Essayer d'accéder à l'adresse http://127.0.0.1:8080 avec votre navigateur. La popup d'authentification devrait s'afficher et vous devriez pouvoir vous authentifier avec le nouveau couple d'identifiants définis dans les options de votre layer ! > **Note** Vous pouvez modifier les identifiants plusieurs fois via la commande et vérifier que la fenêtre s'affiche toujours à nouveau, demandant les nouveaux identifiants.