Saltar al contenido principal

Autenticación OAuth 2.0

OAuth 2.0 es un protocolo que permite a tu aplicación acceder a los datos de la cuenta de un usuario sin acceder a su contraseña. Para poder realizar peticiones a la API necesitarás, aparte de la Subscription Key del portal a3developer, un token de acceso que generará la WKA al autenticar el usuario.

Atención

Para poder obtener el token es necesario disponer de un client OAuth personalizado por cada cliente de a3innuva Nómina y es un proceso que actualmente gestionamos internamente desde Wolters Kluwer. Si no dispones de un client OAuth, por favor, completa el siguiente formulario para que podamos proporcionártelo.

Implementamos un flujo de autenticación Híbrido-Authorization Code, que es el que se utiliza habitualmente para aplicaciones web. Es importante que tu aplicación web mantenga seguros los credenciales de autenticación (client_id y client_secret)

Endpoints​

Endpoint
Autorizaciónhttps://login.wolterskluwer.eu/auth/core/connect/authorize
Request tokenhttps://login.wolterskluwer.eu/auth/core/connect/token
Refresh tokenhttps://login.wolterskluwer.eu/auth/core/connect/token
Atención

La comunicación con el sistema de WKA deberá ser mediante TLS 1.2 o superior.

Flujo de autenticación​

1. Redirige al usuario para autorizar tu aplicación​

Tu aplicación debe dirigir a los usuarios a la siguiente URL:

https://login.wolterskluwer.eu/auth/core/connect/authorize?
client_id=YOUR_CLIENT_ID&
response_type=code+id_token&
response_mode=fragment&
redirect_uri=YOUR_REDIRECT_URI&
scope=offline_access+openid+IDInfo+WK.ES.A3EquipoContex&
state=GUID&
nonce=GUID

Los siguientes valores se deben de pasar como parámetro:

  • client_id: es el client_id del client OAuth que te hemos proporcionado. Por ejemplo: WK.ES.A3WebApi.A23456
  • response_type:
    • Si el flow de tu client OAuth es Hybrid deberás informar el valor fijo code+id_token
    • Si el flow es Authorization Code deberás informar code
  • response_mode: indica cómo se debe devolver el resultado de la autorización. Si el tipo de flow del client OAuth es Hybrid (por defecto), permite los siguientes valores:
    • fragment: Los parámetros de respuesta se devolverán como URI fragment a la redirect_uri. Por ejemplo: https://my-redirect-uri#code=06ec359474651b...074&id_token=eyIkaWQiOi...UNoP9A&scope=offline_access%20openid%20IDInfo%20WK.ES.A3EquipoContex
    • form_post: Es el modo de respuesta definido en el OAuth 2.0 Form Post Response Mode specification. Devuelve una respuesta 200 OK y los parámetros están embebidos en un formulario HTML con parámetros ocultos.
      Atención Si el flow es Authorization Code, no deberás enviar el parámetro response_mode, y la respuesta se enviará por parámetros en la query string a tu redirect_uri
  • redirect_uri: la URL en tu servidor para redirigir de vuelta: esta debe ser una dirección https, sin embargo, para probar puedes usar http://localhost:53971/Login/CallbackFromWKA o http://oob/oauth20_desktop.srf si es una aplicación de escritorio. Ten en cuenta que no se puede usar http://127.0.0.1 Si necesitas agregar una nueva redirect_uri recuerda que debes hacer la petición a través de este formulario.
  • scope: offline_access+openid+IDInfo+WK.ES.A3EquipoContex
  • state: es un texto que debe usarse para evitar ataques de falsificación. Informa un valor único para cada llamada (por ejemplo, un GUID) que se devolverá como parámetro en la llamada a tu redirect_uri. Deberás validar que el valor recibido coincide con el que has enviado.
  • nonce: el objetivo de este parámetro es parecido al del state salvo que este valor se incluirá dentro del id_token

2. Llamada al punto de autorización del WKA Auth Server​

Tu sitio web deberá lanzar una petición GET con la url construida según el punto anterior.

3. WKA Auth Server muestra una pantalla de login​

Si la url está bien construida y la petición es correcta, nuestro servidor de autenticación mostrará una pantalla de login para que el usuario informe sus credenciales de la WKA. LoginWKA

Importante!

Recuerda que los credenciales de la WKA no tienen porqué ser los mismos que los del portal a3developer. Son las credenciales con las que normalmente accede el usuario a su aplicación a3innuva Nómina

4. El usuario informa sus credenciales​

Si el usuario de WKA tiene acceso a varias empresas (tenants), se le mostrará un formulario donde deberá seleccionar qué conjunto de recursos quiere exponer:

LoginWKAIDCA

5. Autorización​

El servidor de autorización de WKA validará los credenciales informados, y si son correctos, enviará una petición GET a la return_uri con los parámetros:

  • code: un código temporal que solo se puede canjear una vez y caduca 5 minutos después de su emisión. Revisa el siguiente punto donde se detalla cómo usarlo.
  • id_token: es un JWT Token que contiene información de identificación. No es el token de acceso a la aplicación. Está cifrado con SHA-256 y en el payload puedes revisar información acerca de la identidad y de seguridad (por ejemplo, el valor nonce para contrastarlo con el que has enviado).
  • state: si el state no coincide con el enviado, la solicitud puede haber sido creada por un tercero y debes cancelar el proceso.

6. Intercambiar el Authorization Code​

Ahora ya puedes obtener el access_token utilizando el code que te ha proporcionado el WKA Auth Server. Para realizar este paso, deberás enviar una petición POST al endpoint:

https://login.wolterskluwer.eu/auth/core/connect/token

Esta petición requiere de unos parámetros codificados en el propio body de la petición:

  • client_id: es el identificador de tu cliente OAuth. Por ejemplo WK.ES.A3WebApi.A23456
  • client_secret: es la clave secreta de tu cliente OAuth. Por ejemplo NvPqSESxR9JKr6Te
  • code: el code que has obtenido en el paso anterior.
  • grant_type: authorization_code
  • redirect_uri: la misma uri que has informado en el proceso de autorización
curl --location --request POST 'https://login.wolterskluwer.eu/auth/core/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET'
--data-urlencode 'code=YOUR_AUTHORIZATION_CODE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=YOUR_REDIRECT_URI' \

7. El servidor WKA Auth devuelve el access_token​

El servidor WKA Auth verificará todos los parámetros en la solicitud, asegurándose de que el código no haya caducado y que la identificación del cliente y el secreto coincidan. Si todo sale bien, generará tus tokens y los devolverá en la respuesta, que contendrá los siguientes valores:

  • access_token: JWT token necesario para poder hacer las llamadas a la API a3innuva Nómina
  • id_token: JWT token con datos de la identidad del usuario.
  • expires_in: tiempo en segundos hasta que el token expire. Por defecto son 60 minutos.
  • token_type: Bearer
  • refresh_token: Es el token que se puede utilizar para refrescar el access_token una vez haya expirado. Por defecto tiene una caducidad de 30 días.

Contenido del access-token​

El access-token es un JSON web token (JWT) que se puede decodificar en un objeto JSON y contiene información sobre el usuario y la autenticación realizada.

{
  "$id": "1",
  "iss": "https://login.wolterskluwercloud.com",
  "aud": "https://login.wolterskluwercloud.com/resources",
  "exp": 1668712060,
  "nbf": 1668708460,
  "client_id": "WK.ES.A3WebApi.A23456",
  "scope": [
    "offline_access",
    "openid",
    "IDInfo",
    "WK.ES.A3EquipoContex"
  ],
  "sub": "d6d396d5-4bfe-4fcd-9f2a-ab76007854a5",
  "auth_time": 1668707536,
  "idp": "idsrv",
  "wk.es.clientid": "23456",
  "wk.es.idcda": "1M8Q2",
  "wk.es.a3equipouserid": "a3developers@wolterskluwer.com",
  "wk.es.secondclientid": "65432",
  "usr": "9cff49af-1b13-4964-9291-ad8d0cb047a9",
  "owapp": "53335e0c-a116-44f5-b525-aa4400ada916",
  "mem": "9cff49cf-1b23-4334-2191-aa8800b04779",
  "oun": "82bffb8f-4b0b-4065-ac27-aba600f09952",
  "amr": [
    "password"
  ]
}

El campo exp hace referencia a la fecha de expiración del access_token en formato EPOCH

Necesitarás validar que el JWT está correctamente firmado y verificar que la información que contiene es correcta. En esta página puedes ver un conjunto de librerías por lenguaje de programación, indicando para cada una qué claims se verifican.

Atención

El tiempo de expiración del access_token es de 1 hora.

8. Llamada a la API​

Ahora ya puedes hacer llamadas a la API a3innuva Nómina añadiendo al headerde tu petición las siguientes variables:

  • Authorization: "Bearer " + access_token
  • Ocp-Apim-Subscription-Key: clave principal de tu suscripción del portal a3developer.
GET /Laboral/api/companies?pageNumber=1&pageSize=25&filter=lastUpdate gt 2022-01-01&OrderBy=companyCode
Authorization: Bearer eyIkaWQiOiIxIiwidHlwIjoiSld...
Ocp-Apim-Subscription-Key: 2kxwf5rb7ffb65dd5
Content-Type: application/json

9. Respuesta de la API​

Si la Ocp-Apim-Subscription-Key y el acces_token son válidos, la API devolverá un HTTP/200 - OK y un body de respuesta con la información en formato json:

[
	{
    "companyCode": 100,
    "companyName": "EMPRESA TEST",
    "identifierNumber": "E2133833T",
    "lastUpdate": "2022-06-30T11:22:59.563Z"
	}
]
Última actualización en