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.
Antes de lanzar una prueba inicial, cada solicitante tendrá que contar con un usuario y contraseña de DMSAS y claves públicas y privadas.
Es necesario comunicar a Servicios CGES el usuario y las claves públicas para realizar la configuración de permisos antes de invocar a los servicios publicados.
Una vez se consigan estos primeros pasos será necesario definir junto a la STIC , y con suficiente antelación, los requisitos de configuración y funcionales necesarios para la integración completa.
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):
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.
Para el proceso de generación de token y la operativa, puede consultar el apartado siguiente.
Las pruebas de concepto incluyen la generación del token de autenticación y un primer lanzamiento de un método con un token de operación.
Se recomienda también preparar la generación de nuevos tokens de operación usando el token de refresco, ya que así se refuerza la seguridad enviando las credenciales con mayor periodicidad.
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.
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.
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.
| Generación y refresco de token durante el consumo de un método REST |
|---|
Loading...
|
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:
Entorno | Direccionamiento |
|---|---|
Desarrollo | Intranet: http://10.118.122.36:8001/servicioscges/api/v1/sistemasExternos |
Preproducción | Intranet: http://servicioscges.pre.sas.junta-andalucia.es/servicioscges/api/v1/sistemasExternos |
Producción | Intranet: https://servicioscges.sas.junta-andalucia.es/servicioscges/api/v1/sistemasExternos Internet: https://ws001.sspa.juntadeandalucia.es/servicioscges/api/v1/sistemasExternos |
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.
Entorno | Clave pública |
|---|---|
Desarrollo | { |
Preproducción | Solicitar al Área de Servicios al Usuario y |
Producción | Solicitar al Área de Servicios al Usuario y |