Autenticación JWT personalizada

Autenticación y autorización

El proveedor de JWT externo autentica a los usuarios y devuelve un JWT. App Services utiliza el JWT para identificar a los usuarios de la aplicación y autorizar sus solicitudes.

App Services es independiente de los métodos de autenticación utilizados por el proveedor externo. No impone ninguna restricción a los requisitos ni a los métodos de autenticación del sistema de autenticación externo. Por ejemplo, el sistema podría requerir que el usuario realice una autenticación multifactor (MFA), proporcione credenciales específicas o se identifique de alguna otra manera.

Cómo funciona la autenticación JWT

Existen numerosos recursos en línea que profundizan en las complejidades de la autenticación JWT y la estructura del token. En el contexto de App Services, el siguiente diagrama muestra el flujo del proceso de un usuario que inicia sesión en una aplicación Device Sync. Los pasos debajo del diagrama proporcionan detalles.

haga clic para ampliar

La autenticación JWT con App Services sigue estos pasos generales:

1. El usuario inicia sesión en el proveedor de autenticación de terceros mediante el medio que requiera el proveedor.

2. Si la autenticación tiene éxito, el proveedor devuelve un JWT a la aplicación cliente.

3. La aplicación cliente inicia sesión en la App Services app, proporcionando la credencial JWT.

4. App Services analiza y decodifica el JWT.

5. Si proporcionó manualmente claves de firma en App Services, este servicio comprueba si la clave de firma del JWT coincide con una de las claves de firma especificadas. De ser así, el usuario se autentica.

6. Si configuró App Services para usar una URI de clave web JSON (JWK), App Services pasa el JWT y la clave pública a la API JWK del proveedor externo.

   1. El proveedor decodifica y verifica la firma y devuelve un JWK.

   2. App Services comprueba si la firma del JWK coincide con la del JWT. De ser así, el usuario se autentica.

Configuración

La autenticación JWT personalizada se configura desde la interfaz de usuario o con la CLI. Elija su método preferido a continuación.

{
  "custom-token": {
    "name": "custom-token",
    "type": "custom-token",
    "config": {
      "audience": "<JWT Audience>",
      "requireAnyAudience": <boolean>,
      "signingAlgorithm": "<JWT Signing Algorithm>",
      "useJWKURI": <boolean>,
      "jwkURI": "<JWK or JWKS URL>",
    },
    "secret_config": {
      "signingKeys": [
        "<Signing Key Secret Name>",
        ...
      ]
    },
    "metadata_fields": [
      {
        "required": <boolean>,
        "name": "<JWT Field Path>",
        "field_name": "<Metadata Field Name>",
      },
      ...
    ],
    "disabled": <boolean>
  }
}

Método de verificación

El campo Verification Method determina cómo App Services validará el JWT devuelto por el proveedor de JWT. Puede configurar App Services para que valide el JWT mediante las claves de firma que proporcione o mediante una URI de clave web JSON (JWK) emitida por el proveedor externo.

Especifica manualmente las claves de firma

Puedes configurar tu aplicación para usar una o más claves de firma para validar el JWT. Debes proporcionar dos configuraciones:

Campo	Descripción
Signing Algorithm config.signingAlgorithm	El método criptográfico que utiliza el sistema externo para firmar el JWT. La autenticación personalizada admite JWT firmados con cualquiera de los siguientes algoritmos: HS256 RS256
Signing Key secret_config.signingKeys	Una lista de hasta tres secretos que contienen cada uno una clave de firma utilizada por el sistema de autenticación de terceros para firmar JWT. La clave solo puede contener letras ASCII, números, guiones bajos y guiones, y debe tener entre 32 y 512 caracteres. La siguiente es una 256clave de firma válida de bits: 231a58b00632c9c4d8ac02b268ca4caf8dd48fd020e3dffa72666523d860988f Nota Si no está seguro de qué valor utilizar, considere visitar un sitio web generador de claves aleatorias, como keygen.io, y utilizar uno de los 256valores de bits generados.

Interfaz de usuario de servicios de aplicaciones

CLI de servicios de aplicaciones

1. Establece el algoritmo de firma:

   

2. Cree una o más claves de firma para firmar el JWT. Para ello, proporcione un nombre para la clave (este solo se usará como referencia posterior) y, a continuación, especifique una clave de firma de 256bits.

   

"config": {
  "signingAlgorithm": "<JWT Signing Algorithm>",
},
"secret_config": {
  "signingKeys": [
    "<Signing Key Secret Name>",
    ...
  ]
}

Advertencia

Signing Key es una clave secreta y cualquiera que la posea puede emitir credenciales de usuario válidas para tu aplicación. Asegúrate de que nunca se almacene en una ubicación de acceso público, como un repositorio de Git, un foro de mensajes o en tu código.

Utilice una URI JWK

Algunos sistemas de autenticación externa proporcionan un conjunto de kid claves web JSON (JWKS) que describe el RS256 algoritmo y las claves de firma que el sistema utiliza para firmar JWT. Puede usar el JWKS para configurar el proveedor en lugar de especificar manualmente el algoritmo y las claves de firma. El JWKS devuelto debe incluir un encabezado que especifique el ID de clave de una clave del JWKS. El JWKS puede especificar hasta tres claves de firma y debe usar el algoritmo.

Nota

JWK y JWKS se utilizan como sinónimos en Atlas App Services.

Solo hay un valor que debes proporcionar:

• JWK URI, que es la URL de terceros que aloja un servicio JWK o JWKS. Al elegir esta opción, App Service configura automáticamente el cifrado con el método RS256 requerido.

Interfaz de usuario de servicios de aplicaciones

CLI de servicios de aplicaciones

Especifique la URL del punto final JWKS de terceros:

"config": {
  "useJWKURI": <boolean>,
  "jwkURI": "<JWK or JWKS URL>"
}

Campos de metadatos

Metadata Fields Son datos adicionales que describen a cada usuario interno de App Services. App Services determina el valor de cada campo de metadatos a partir del valor de un campo incluido en el JWT de terceros. Por ejemplo, si se configura el campo name de un usuario, App Services usará ese campo en el JWT como su nombre para mostrar.

Nota

App Services actualiza los metadatos de un usuario cada vez que inicia sesión y expone los campos en el data objeto de los metadatos del usuario.

Importante

Límites de caracteres en campos JWT y metadatos

La longitud de un token JWT aumenta con la cantidad de campos de metadatos que contiene y el tamaño de cada campo. App Services limita la longitud de un token JWT a 1 millones de caracteres y la longitud de cada campo de metadatos a 4096 caracteres. Si se exceden estos límites, App Services registra un error y el ticket no se procesa.

Hay tres valores que debes especificar para cada campo de metadatos:

Campo	Descripción
Required required	Si true , el campo de metadatos es obligatorio para todos los usuarios asociados con el proveedor. El JWT devuelto por el sistema externo debe tener un valor asignado al campo designado por Path.
Path name	El nombre o la ruta de un campo en el JWT que contiene el valor del campo de metadatos. Para especificar la ruta de un campo en un objeto incrustado, utilice la notación de punto. Si el nombre del campo en el JWT contiene un punto. (), utilice una barra invertida ()\ para escaparlo. Por ejemplo, si el nombre es,http://example.com/id http://example\.com/idutilice.
Field Name field_name	Opcional. Un nombre para el campo de metadatos en el documento del objeto de usuario data que se asigna a la ruta JWT. Este nombre de campo debe tener menos de 64 caracteres. Reglas de valores predeterminados Si no se especifica este campo, el nombre predeterminado será el nombre del campo JWT que contiene el valor. Si no se especifica este campo y el valor de la ruta usa la notación de punto, el nombre predeterminado será la última parte de la notación. Por ejemplo, si especifica location.primary.city la ruta, el valor predeterminado del nombre city será.

Interfaz de usuario de servicios de aplicaciones

CLI de servicios de aplicaciones

Para definir un campo de metadatos, haz clic en Add Field y especifica la asignación entre el campo de metadatos en el JWT y su nombre de campo correspondiente en el objeto de usuario.

Para definir un campo de metadatos en un archivo de configuración de autenticación JWT personalizada, agregue una entrada para el campo a la matriz metadata_fields. Cada entrada debe ser un documento con el siguiente formato:

{
  required: <boolean>,
  name: "<field path>",
  field_name: "<metadata field name>"
}

Utilice una barra invertida (\) para escapar los caracteres de punto (.) en las claves JWT.

Por ejemplo, en este objeto JSON, representa el "nested_key" en el nombre de ruta como valid\.json\.key\.nested_key.

{ "valid.json.key": {
    "nested_key": "val"
  }
}

Ejemplo

Un sistema de autenticación externa devuelve JWT que incluyen información adicional sobre cada usuario en el campo user_data:

(JWT JSON)
{
  "aud": "myapp-abcde",
  "exp": 1516239022,
  "sub": "24601",
  "user_data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  }
}

Para incluir los valores del campo en el user_data objeto de usuario de cada usuario, especifique los siguientes campos de metadatos en su configuración de App Services:

Ruta de acceso	Nombre de campo
user_data.name	name
user_data.aliases	aliases

El objeto de usuario ahora incluirá esos campos:

(USER METADATA OBJECT)
{
  "id": "59fdd02846244cdse5369ebf",
  "type": "normal",
  "data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  },
  identities: [
    {
      "id": "24601",
      "provider_type": "custom-token",
      "data": {
        "name": "Jean Valjean",
        "aliases": [
          "Monsieur Madeleine",
          "Ultime Fauchelevent",
          "Urbain Fabre"
        ]
      },
    }
  ]
}

Audiencia

El Audience de un JWT especifica el destinatario del token. Los JWT describen su audiencia en la notificación aud. App Services espera que aud contenga el ID de la aplicación para la que está configurado el proveedor. Sin embargo, si el JWT del sistema de autenticación externo especifica un valor aud diferente, puede configurar el proveedor para que use ese valor.

Interfaz de usuario de servicios de aplicaciones

CLI de servicios de aplicaciones

Hay dos campos que puedes configurar:

Campo	Descripción
Audience	Un valor único o una lista de valores separados por comas para la audiencia o audiencias que se espera encontrar en un JWT de cliente.
Require	Si proporciona varias audiencias, debe especificar cómo gestionarlas. Sus opciones son: Todas estas audiencias: el JWT debe incluir todas las audiencias en la lista. Cualquiera de estas audiencias: el JWT solo necesita incluir una audiencia de la lista.

Para definir una audiencia, configure config.audience. Hay dos campos que se configuran:

Campo	Descripción
audience	Una matriz de cadenas que especifican la audiencia o audiencias que se espera encontrar en un JWT de cliente.
requireAnyAudience	Booleano. Si false es, el JWT debe incluir todas las audiencias listadas. Si true es, el JWT solo debe incluir una o más de las audiencias listadas.

"config": {
  "audience": [
    "<JWT Audience>",
  ],
  "requireAnyAudience": <boolean>,
}

Uso de la autenticación JWT

Puede registrar nuevos usuarios de JWT personalizados e iniciar sesión mediante uno de los SDK de Realm o un servicio API.