Todos los productos
Search

Este producto

    API Gateway:Plugin de OAuth

    Centro de documentos

    API Gateway:Plugin de OAuth

    Última actualización: Sep 21, 2026

    El plugin de OAuth emite tokens de acceso de OAuth 2.0 basados en JSON Web Tokens (JWT), conforme a RFC 9068.

    Tipo de plugin

    Autenticación y autorización.

    Configuración del plugin

    Campos

    Configuración de autenticación

    Campo

    Tipo de dato

    Obligatorio

    Valor predeterminado

    Descripción

    consumers

    array of object

    Sí

    -

    Llamantes (consumidores) con permiso para solicitar autenticación.

    issuer

    string

    No

    Higress-Gateway

    Emisor del JWT.

    auth_path

    string

    No

    /oauth2/token

    Sufijo de ruta para la emisión de tokens. Asegúrese de que la ruta coincida con esta dirección. Si utiliza gestión de API, cree una API con la misma ruta.

    global_credentials

    bool

    No

    true

    Indica si las credenciales emitidas en cualquier ruta otorgan acceso después de que la autenticación del consumidor se complete correctamente.

    auth_header_name

    string

    No

    Authorization

    Encabezado de solicitud que contiene el JWT.

    token_ttl

    number

    No

    7200

    Tiempo de vida del token tras su emisión, en segundos.

    clock_skew_seconds

    number

    No

    60

    Desfase de reloj permitido para verificar los campos exp e iat del JWT, en segundos.

    keep_token

    bool

    No

    true

    Indica si se conserva el JWT en las solicitudes reenviadas al backend.

    global_auth

    array of string

    No (obligatorio solo para configuraciones a nivel de instancia)

    -

    Exclusivo del nivel de instancia. Si se establece en true, la autenticación aplica a todas las rutas. Si se establece en false, aplica únicamente a los dominios y rutas configurados. Si no se especifica, la autenticación aplica de forma global solo cuando no existen configuraciones a nivel de dominio o de ruta.

    Campos dentro de consumers:

    Campo

    Tipo de dato

    Obligatorio

    Valor predeterminado

    Descripción

    name

    string

    Sí

    -

    Nombre del consumidor.

    client_id

    string

    Sí

    -

    Identificador de cliente de OAuth 2.0.

    client_secret

    string

    Sí

    -

    Clave secreta de cliente de OAuth 2.0.
    Importante

    • Si una ruta coincide con auth_path, la solicitud no se reenvía al backend. En su lugar, la ruta genera un token.

    • Si global_credentials es false, asegúrese de que la ruta con el plugin habilitado no utilice coincidencia exacta. Una ruta de coincidencia por prefijo coexistente podría provocar un comportamiento inesperado.

    • En las solicitudes autenticadas se añade el encabezado X-Mse-Consumer para identificar al llamante.

    (Opcional) Configuración de autorización

    Campo

    Tipo de dato

    Obligatorio

    Valor predeterminado

    Descripción

    allow

    array of string

    No (obligatorio para configuraciones fuera del nivel de instancia)

    -

    Exclusivo del nivel de ruta o de dominio. Especifica qué consumidores pueden acceder a las solicitudes coincidentes para lograr un control de permisos detallado.
    Importante

    Las configuraciones de autorización y autenticación no pueden coexistir en la misma regla.

    Ejemplos

    Configuración de autenticación a nivel de ruta

    Aplique a continuación la configuración del plugin en route-a y route-b:

    consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    Con esta configuración, las credenciales emitidas por route-a no permiten acceder a route-b, ni viceversa.

    Para compartir credenciales entre varias rutas:

    global_credentials: true
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    Configuración de autorización global y de autenticación a nivel de ruta

    La siguiente configuración habilita la autenticación JWT para rutas o dominios específicos. Si un JWT coincide con varios JSON Web Key Sets (JWKSs), se aplica el primer consumer que coincida.

    Configuración a nivel de instancia:

    global_auth: false
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    Configuración para route-a y route-b:

    allow:
- consumer1

    Configuración para *.example.com y test.com:

    allow:
- consumer2
    Nota

    • route-a y route-b son rutas de gateway. Las solicitudes que coinciden con estas rutas admiten únicamente al consumidor llamado consumer1.

    • *.example.com y test.com coinciden con nombres de dominio en las solicitudes. Las peticiones que coinciden con estos dominios admiten únicamente al consumidor llamado consumer2.

    Habilitar la autenticación a nivel de gateway

    Habilite la autenticación OAuth2 para todas las solicitudes del gateway:

    global_auth: true
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    Ejemplos de solicitud

    Usar el tipo de concesión Client Credential

    Obtener un token de acceso

    # Obtain an access token by using the GET method. We recommend that you use this method.
curl 'http://test.com/oauth2/token?grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Obtain an access token by using the POST method. To perform this operation, you need to match a route that points to a real destination service. Otherwise, the gateway does not read request bodies.
curl 'http://test.com/oauth2/token' -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Obtain the value of the access_token field from the response.
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0",
  "expires_in": 7200
}

    Usar el token de acceso para iniciar una solicitud

    curl 'http://test.com' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0'

    Códigos de error

    Código de estado HTTP

    Mensaje de error

    Motivo

    401

    Invalid Jwt token.

    El JWT falta, tiene un formato incorrecto o caducó.

    403

    Access Denied.

    El consumidor no tiene autorización para acceder a esta ruta.