Configurer le plug-in jwt-auth - API Gateway - Centre de documentation Alibaba Cloud

Le plug-in jwt-auth authentifie et autorise les requêtes à l'aide de jetons JSON Web Tokens (JWT). Il extrait un JWT des paramètres d'URL, des en-têtes de requête ou des cookies, puis vérifie le jeton pour accorder ou refuser l'accès. Contrairement à Authentification et autorisation JWT, ce plug-in identifie également les appelants, ce qui vous permet de configurer des informations d'identification JWT distinctes pour chacun d'eux.

Champs de configuration

Configuration d'authentification

Nom

Type de données

Obligatoire

Valeur par défaut

Description

consumers

array of object

Obligatoire

Les consommateurs de service utilisés pour l'authentification des requêtes.

global_auth

Array of strings

Facultatif (configuration au niveau de l'instance uniquement)

Configurable uniquement au niveau de l'instance. Si la valeur est true, l'authentification s'applique globalement. Si la valeur est false, l'authentification s'applique uniquement aux noms de domaine et aux routes configurés. En l'absence de configuration, l'authentification s'applique globalement uniquement lorsqu'aucune configuration de nom de domaine ou de route n'existe, afin de maintenir la rétrocompatibilité.

Le tableau suivant décrit les champs de chaque élément dans consumers.

Nom	Type de données	Obligatoire	Valeur par défaut	Description
name	string	Obligatoire	-	Le nom du consommateur.
jwks	string	Facultatif. `jwks` ou `remote_jwks` est requis.	-	Une chaîne JSON Web Key Set (JWKS) telle que spécifiée par JSON Web Key (JWK), contenant la clé publique ou la clé symétrique utilisée pour vérifier la signature JWT.
remote_jwks	object	Facultatif. Choisissez soit `jwks`, soit `remote_jwks`.	{"uri":"http://127.0.0.1/keys","service":"test.static","port":"80","ttl":30000,"timeout":3000}	Extrait périodiquement le JWKS à partir d'un URI de service spécifié. Si `jwks` et `remote_jwks` sont tous deux configurés, le JWKS extrait à distance est prioritaire. Remarque La taille du JWKS renvoyé par `remote_jwks` doit être inférieure à 1 Mo. Si la taille dépasse cette limite et qu'une erreur se produit, rejoignez le groupe DingTalk 88010006189 ou soumettez un ticket pour obtenir de l'aide.
issuer	string	Facultatif	-	L'émetteur du JWT. Cette valeur doit correspondre au champ `iss` de la charge utile.
claims	object	Facultatif	-	Les paires clé-valeur correspondant à celles de la charge utile, utilisées pour vérifier la concordance de plusieurs champs. Par exemple, si vous configurez `aud: mobile-site`, le champ `aud` de la charge utile doit être `mobile-site`.
claims_to_headers	array of object	Facultatif	-	Extrait les champs spécifiés de la charge utile JWT et les définit comme en-têtes de requête avant le transfert vers le backend.
from_headers	array of object	Facultatif	[{"name":"Authorization","value_prefix":"Bearer"}]	Extrait le JWT à partir des en-têtes de requête spécifiés.
from_params	array of string	Facultatif	access_token	Extrait le JWT à partir des paramètres d'URL spécifiés.
from_cookies	array of string	Facultatif	-	Extrait le JWT à partir des cookies spécifiés.
clock_skew_seconds	number	Facultatif	60	Le décalage d'horloge autorisé (en secondes) lors de la vérification des champs `exp` et `iat` du JWT.
keep_token	bool	Facultatif	true	Indique s'il faut conserver le JWT lors du transfert de la requête vers le backend.

Remarque

Les valeurs par défaut sont utilisées uniquement lorsque from_headers, from_params et from_cookies ne sont pas configurés.

Le tableau suivant décrit les champs de chaque élément dans from_headers.

Nom

Type de données

Obligatoire

Valeur par défaut

Description

name

string

Obligatoire

L'en-tête de requête à partir duquel le JWT est extrait.

value_prefix

string

Obligatoire

Le préfixe à supprimer de la valeur de l'en-tête. La partie restante est traitée comme le JWT.

Le tableau suivant décrit les champs de chaque élément dans claims_to_headers.

Nom	Type de données	Obligatoire	Valeur par défaut	Description
claim	string	Obligatoire	-	Un champ spécifié dans la charge utile JWT. La valeur doit être une chaîne ou un entier non signé.
header	string	Obligatoire	-	L'en-tête de requête à renseigner avec la valeur de claim extraite et à transférer vers le backend.
override	bool	Facultatif	true	Si la valeur est true, remplace l'en-tête de requête s'il porte le même nom. Si la valeur est false, ajoute la valeur en tant qu'en-tête de requête dupliqué.

Le tableau suivant décrit les champs de chaque élément dans remote_jwks.

Nom	Type de données	Obligatoire	Valeur par défaut	Description
uri	string	Obligatoire	-	L'URL de la requête.
service	string	Obligatoire	-	Exemple pour un service Kubernetes : foo.default.svc.cluster.local. Exemple pour un service Nacos : foo.DEFAULT-GROUP.public.nacos. Pour un service DNS nommé test, saisissez test.dns. Pour un service IP statique nommé test, saisissez test.static.
port	bool	Obligatoire	-	Le port du service.
timeout	bool	Facultatif	3000	Le délai d'expiration de la requête de service en millisecondes.
ttl	bool	Facultatif	30000	La durée de mise en cache en millisecondes.

Configuration d'autorisation (facultative)

Nom

Type de données

Obligatoire

Valeur par défaut

Description

allow

array of string

Facultatif (pas pour la configuration au niveau de l'instance)

Configurable uniquement sur des règles granulaires telles que les routes ou les noms de domaine. Spécifie quels consommateurs sont autorisés à accéder à la ressource correspondante.

Important

Les configurations d'autorisation et d'authentification ne peuvent pas être utilisées dans la même règle.
Pour les requêtes qui passent l'authentification et l'autorisation, un en-tête X-Mse-Consumer est ajouté à la requête pour identifier le nom de l'appelant.

Exemples de configuration

Configurer l'authentification globale et l'autorisation au niveau de la route

Cet exemple active l'authentification JWT globale au niveau de l'instance et restreint l'accès au niveau de la route à des consommateurs spécifiques.

Remarque

Si un JWT peut correspondre à plusieurs JWKS, le premier consommateur correspondant dans l'ordre de configuration est utilisé.

Configuration du plug-in

Configurez le plug-in au niveau de l'instance comme suit :

consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

Configuration de la route et du nom de domaine

Pour les routes route-a et route-b, configurez le plug-in comme suit :

allow:
- consumer1

Pour les noms de domaine *.example.com et test.com, configurez le plug-in comme suit :

allow:
- consumer2

Remarque

Dans cet exemple, route-a et route-b sont les noms de route saisis lors de la création des routes de passerelle. Lorsqu'une requête correspond à ces routes, les appelants portant le nom consumer1 sont autorisés à accéder. Les autres appelants se voient refuser l'accès.
Dans cet exemple, *.example.com et test.com sont utilisés pour faire correspondre le nom de domaine de la requête. Lorsque le nom de domaine correspond, les appelants portant le nom consumer2 sont autorisés à accéder. Les autres appelants se voient refuser l'accès.

Exemples de requêtes

Les requêtes suivantes sont autorisées selon cette configuration. Ces exemples supposent que les requêtes correspondent à la route route-a.

Définissez le JWT dans un paramètre d'URL.

curl  'http://xxx.hello.com/test?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEy****.eyJpc3MiOiJhYmNkIiwic3ViIjoidGVzdCIsImlhdCI6MTY2NTY2MDUyNywiZXhwIjoxODY1NjczODE5fQ.-vBSV0bKeDwQcuS6eeSZN9dLTUnSnZVk8eVCXdooCQ4'

Définissez le JWT dans un en-tête de requête HTTP.

curl  http://xxx.hello.com/test -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJpc3MiOiJhYmNkIiwic3ViIjoidGVzdCIsImlhdCI6MTY2NTY2MDUyNywiZXhwIjoxODY1NjczODE5fQ.-vBSV0bKeDwQcuS6eeSZN9dLTUnSnZVk8eVCXdooCQ4'

Vérifier le résultat

Après une authentification réussie, l'en-tête X-Mse-Consumer est ajouté à la requête avec le nom de l'appelant. Dans cet exemple, sa valeur est consumer1.

Les requêtes suivantes seront refusées.

La requête ne fournit pas de JWT, donc une erreur 401 est renvoyée.
L'appelant correspondant au JWT fourni ne dispose pas d'autorisation d'accès, donc une erreur 403 est renvoyée.

Activer au niveau de l'instance de passerelle mais désactiver pour une route spécifique

Configurez le plug-in au niveau de l'instance comme suit :

global_auth: true
consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

Pour la route route-b, configurez le plug-in comme suit :

_disable_: true

Dans cet exemple, route-b est le nom de route saisi lors de la création de la route de passerelle. Étant donné que _disable_ est défini sur true, lorsque une requête correspond à cette route, le plug-in est désactivé. Aucune authentification JWT n'est effectuée et tous les utilisateurs sont autorisés à accéder.

Pour les requêtes qui ne correspondent pas à la route route-b, l'authentification JWT est effectuée car global_auth est défini sur true au niveau de l'instance. Les consommateurs consumer1 et consumer2 sont tous deux autorisés à accéder.

Activer au niveau du nom de domaine mais désactiver pour une route spécifique

Configurez le plug-in au niveau de l'instance comme suit :

consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

Pour la route route-b, configurez le plug-in comme suit :

_disable_: true

Pour le nom de domaine *.example.com, configurez le plug-in comme suit :

allow:
- consumer1
- consumer2

Dans cet exemple, *.example.com est utilisé pour faire correspondre le nom de domaine de la requête. Lorsque le nom de domaine correspond, les appelants portant le nom consumer1 ou consumer2 sont autorisés à accéder. Les autres appelants se voient refuser l'accès.

Les règles sont mises en correspondance séquentiellement : la première correspondance est appliquée et aucune autre règle n'est évaluée. Les règles de route sont prioritaires sur les règles de nom de domaine, ce qui vous permet d'activer le plug-in pour un nom de domaine tout en le désactivant pour une route spécifique sous ce domaine.

Codes d'erreur associés

Code d'état HTTP

Message d'erreur

Cause

401

Jwt missing

L'en-tête de requête ne fournit pas de JWT.

401

Jwt expired

Le JWT a expiré.

401

Jwt verification fails

La validation de la charge utile JWT a échoué. Par exemple, iss ne correspond pas.

403

Access Denied

Aucune autorisation pour accéder à la route actuelle.