Autenticación JWT personalizada

Autenticación y autorización

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

App Services is agnostic to the authentication methods used by the third-party provider. It does not impose any restrictions on the external authentication system's requirements or authentication methods. For example, the system could require the user to perform multi-factor authentication (MFA), provide specific credentials, or otherwise identify themselves.

How JWT Authentication Works

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 aplicación Services sigue estos pasos generales:

1. The user logs on to the third-party authentication provider by whatever means the provider requires.

2. If authentication succeeds, the provider returns a JWT to the client app.

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

4. App Services parses and decodes the 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 checks if the signature in the JWK matches the JWT's signature. If so, the user is authenticated.

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

You can configure your app to use one or more signing keys to validate the JWT. There are two settings you need to provide:

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.

App Services UI

App Services CLI

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 nombre solo se usará como referencia posterior) y, a continuación, especifique una clave de firma de 256 bits.

   

"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.

Use a JWK URI

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 necesitas proporcionar un valor:

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

App Services UI

App Services CLI

Especifique la URL del punto final JWKS de terceros:

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

Campos de metadatos

Metadata Fields are additional data that describe each internal App Services user. App Services determines the value of each metadata field from the value of a field included in the third-party JWT. For example, if you set the name field of a user, then App Services will use that field in the JWT as the user's display name.

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	Optional. A name for the metadata field in the user object's data document that maps to the JWT Path. This field name must be less than 64 characters long. Reglas de valores predeterminados Si este campo no se especifica, el nombre será el nombre del campo JWT que contiene el valor. If this field is not specified and the Path value uses dot notation, the default name will be the last part of the notation. For example, if you specify a path of location.primary.city, the default value for the name is city.

App Services UI

App Services CLI

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, agrega una entrada para el campo en el arreglo metadata_fields. Cada entrada debe ser un documento con el siguiente formato:

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

Use a backslash (\) to escape period (.) characters in JWT keys.

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	Nombre de campo
user_data.name	name
user_data.aliases	aliases

The user object, will now include those fields:

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

App Services UI

App Services CLI

Hay dos campos que puedes configurar:

Campo	Descripción
Audience	Un solo valor o una lista separada por comas de valores 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.

To set an audience, configure config.audience. There are two fields you configure:

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

You can register new Custom JWT users and log them in using one of the Realm SDKs or an API service.