Primera toma de contacto

En este apartado se detalla el proceso a seguir para una primera toma de contacto con la API.

Para ello, se ofrecen un conjunto de pruebas de concepto basadas en diferentes tecnologías para facilitar la implementación del uso de JWT. 

Respecto al usuario de login durante el desarrollo, se puede hacer uso de cualquier usuario DMSAS con validez, pero para el paso a los entornos de Preproducción y Producción, será condición necesaria poseer o solicitar un usuario de servicio de DMSAS para evitar que caduquen las claves periódicamente o que la integración dependa de un usuario nominal que pueda ser dado de baja en un momento dado. La petición de un usuario DMSAS de servicio puede realizarse mediante una petición CGES a través de los canales habituales.

Pruebas de concepto para una primera conexión

Durante la fase de desarrollo, os proponemos conectar con el entorno de pruebas de SERVICIOS CGES.

Definición API (Desarrollo): http://10.118.122.36:8001/servicioscges/index.html

Para facilitar los primeros pasos en la integración se han desarrollado ejemplos de login en diferentes tecnologías, pero la implementación puede realizarse con la tecnología que se considere conveniente. 

Generación del par de claves pública/privada

Si ya se dispone de autenticación, puede generar un par de claves públicas y privadas a través del siguiente método del servicio (ver definición):

<div style="margin: 0 0 15px;margin-top: 0px;margin-right: 0px;margin-bottom: 15px;margin-left: 0px;border: 1px solid #000;border-radius: 4px;-webkit-box-shadow: 0 0 3px rgba(0,0,0,.19);box-shadow: 0 0 3px rgba(0,0,0,.19);border-color: #61affe;background: rgba(97,175,254,.1);"><div style="border-color: #61affe;display: flex;-webkit-box-align: center;align-items: center;padding: 5px;"><span style="background: #61affe;font-size: 14px;font-weight: 700;min-width: 80px;padding: 6px 15px;text-align: center;border-radius: 3px;text-shadow: 0 1px 0 rgba(0,0,0,.1);font-family: sans-serif;color: #fff;">GET</span><span style="font-size: 16px;display: -webkit-box;display: -ms-flexbox;display: flex;-webkit-box-flex: 0;-ms-flex: 0 3 auto;flex: 0 3 auto;-webkit-box-align: center;-ms-flex-align: center;align-items: center;word-break: break-all;padding: 0 10px;font-family: monospace;font-weight: 600;color: #3b4151;">/accesos/jwt/keys</span><div style="font-size: 13px;-webkit-box-flex: 1;-ms-flex: 1;flex: 1;font-family: sans-serif;color: #3b4151;">Generador de claves para el uso de tokens</div></div></div>

Si desea la clave en formato x.509 PEM, puede enviar el parámetro x.509PEMFormat=true para obtenerlo.

Como alternativa, se suministran dos recursos online externos para la generación de claves:

Se debe generar una clave con las siguientes propiedades:

• Key size: 2048
• Key use: Signature
• Algorithm: RS256

Una vez generada, la clave pública que se debe hacer llegar a ServiciosCGES debe tener una estructura como la del siguiente ejemplo:

Debe conservar la clave privada asociada a la clave pública suministrada para la firma del token durante el proceso de encriptación.

Acceso al servicio y consumo mediante tokens JWT

La aplicación hace uso de un conjunto de tokens siguiendo el estándar JWT (JSON Web Token) tanto para el login en la aplicación como para la operatividad con el resto de métodos. 

Se distinguen un total de tres tokens : Token de autenticación, token de operación y token de refresco .

Token de autenticación

El token de autenticación es generado por cada proveedor que hace uso del servicio y debe contener la siguiente información en la carga útil (payload):

• login: El usuario DMSAS que debe acceder al sistema de CGES.
• password: La contraseña de dicho usuario.
• origen: Palabra clave suministrada por Servicios CGES para verificar el acceso.

Una vez generado el payload, se procederá la firma con la clave privada del proveedor seguida de la encriptación con la clave pública de Servicios CGES .

Por seguridad, se recomienda que este token tenga una caducidad relativamente baja (máximo 10 minutos). 

Tokens de operación y refresco

El token de autenticación será utilizado como parámetro para la llamada al método REST de acceso al sistema, que devolverá un token de operación y un token de refresco.

<div style="margin: 0 0 15px;margin-top: 0px;margin-right: 0px;margin-bottom: 15px;margin-left: 0px;border: 1px solid #000;border-radius: 4px;-webkit-box-shadow: 0 0 3px rgba(0,0,0,.19);box-shadow: 0 0 3px rgba(0,0,0,.19);border-color: #61affe;background: rgba(97,175,254,.1);"><div style="border-color: #61affe;display: flex;-webkit-box-align: center;align-items: center;padding: 5px;"><span style="background: #61affe;font-size: 14px;font-weight: 700;min-width: 80px;padding: 6px 15px;text-align: center;border-radius: 3px;text-shadow: 0 1px 0 rgba(0,0,0,.1);font-family: sans-serif;color: #fff;">GET</span><span style="font-size: 16px;display: -webkit-box;display: -ms-flexbox;display: flex;-webkit-box-flex: 0;-ms-flex: 0 3 auto;flex: 0 3 auto;-webkit-box-align: center;-ms-flex-align: center;align-items: center;word-break: break-all;padding: 0 10px;font-family: monospace;font-weight: 600;color: #3b4151;">/accesos/token</span><div style="font-size: 13px;-webkit-box-flex: 1;-ms-flex: 1;flex: 1;font-family: sans-serif;color: #3b4151;">Obtención de token</div></div></div>

Por motivos de seguridad, la caducidad del token de operación está definida en 30 minutos , una vez transcurrido este tiempo, será necesario volver a realizar el acceso al sistema.

Se podrá utilizar el token de refresco para hacer un relogin sin necesidad de volver a generar el token de autenticación durante las 48 horas posteriores a su generación, obteniéndose de nuevo un token de operación para otros 30 minutos. 

Pasado el periodo de validez del token de refresco, será necesario volver a utilizar el token de autenticación e iniciar el proceso desde el principio. 

• La llamada para generar tokens con el token de autenticación debe llevar en la cabecera el parámetro Authorization con el prefijo JWE seguido del token de autenticación. La respuesta devolverá el token de operación (token), el token de refresco (tokenRefresh) y la hora del caducidad del token de operación (expireTime).
• Cada vez que caduque el token de operación, podrá generar uno nuevo con el token de refresco enviando en la cabecera el parámetro Authorization con el prefijo Bearer seguido del token de refresco. La respuesta en este caso sólo devolverá el nuevo token de operación (token) y su nueva hora de caducidad (expireTime) válida para los siguientes 30 minutos.

En caso de caducidad de token, el sistema devolverá el siguiente error HTTP 401:

Liberación de tokens

Para invalidar cualquier token de operación o de refresco, puede hacer uso del método habilitado para tal fin.

<div style="margin: 0 0 15px;margin-top: 0px;margin-right: 0px;margin-bottom: 15px;margin-left: 0px;border: 1px solid #000;border-radius: 4px;-webkit-box-shadow: 0 0 3px rgba(0,0,0,.19);box-shadow: 0 0 3px rgba(0,0,0,.19);border-color: #f93e3e;background: rgba(249,62,62,.1);"><div style="border-color: #f93e3e;display: flex;-webkit-box-align: center;align-items: center;padding: 5px;"><span style="background: #f93e3e;font-size: 14px;font-weight: 700;min-width: 80px;padding: 6px 15px;text-align: center;border-radius: 3px;text-shadow: 0 1px 0 rgba(0,0,0,.1);font-family: sans-serif;color: #fff;">DELETE</span><span style="font-size: 16px;display: -webkit-box;display: -ms-flexbox;display: flex;-webkit-box-flex: 0;-ms-flex: 0 3 auto;flex: 0 3 auto;-webkit-box-align: center;-ms-flex-align: center;align-items: center;word-break: break-all;padding: 0 10px;font-family: monospace;font-weight: 600;color: #3b4151;">/accesos/token</span><div style="font-size: 13px;-webkit-box-flex: 1;-ms-flex: 1;flex: 1;font-family: sans-serif;color: #3b4151;">Liberación de token</div></div></div>

Diagrama del procesamiento del token en llamadas a la API

En el siguiente diagrama se recoge el procedimiento a seguir con respecto a los tokens al consumir cualquier método REST de la API.

Direccionamientos y claves públicas de ServiciosCGES

Apartado que lista las URLs de acceso y las claves públicas para cada uno de los entornos en los que la API está disponible.

Direccionamientos

En la siguiente tabla se muestra el direccionamiento raíz de los servicios REST para cada entorno, que deberá completarse con la URI de cada método REST a utilizar:

Claves públicas

A continuación se recogen las claves públicas de la aplicación de Servicios CGES para los diferentes entornos.

Las claves varían entre el entorno de Desarrollo y los entornos productivos.