Documentación API Kommodo SIPS



Consulta el API de Kommodo



Aquellos usuarios que dispongan de un plan que permita usar el API de Kommodo, deberán implementar un cliente para poder ejecutar las operaciones de dicho API. El cliente debe satisfacer una serie de requisitos de seguridad que se listan en los próximos apartados.

Registrar cliente

Para poder ejecutar los flujos que se detallan a continuación es necesario que el equipo de mantenimiento de Kommodo SIPS registre tu aplicación, llamada cliente, en el sistema de seguridad. Para ello, debes solicitar el registro del cliente escribiendo un correo a sips[at]kommodo.com y se te suministrará un identificador y un secreto.

Protocolo

El protocolo de autorización que se utiliza es OpenID Connect siguiendo el flujo Client Credentials, por lo que si estás familiarizado con él, puedes ir directo a las URL's de referencia descritas en URLs referenciadas.

Flujo

Para poder obtener un token de acceso al API se necesita seguir el protocolo Client Credentials. Para ello, hay que seguir los siguientes pasos:

  1. En primer lugar, debes incluir tus credenciales en modo Basic HTTP, es decir, incluir la cabecera Authorization con su identificador de cliente y su secreto separados por “:” codificados de manera individual en formato url y el resultado en base64. Un ejemplo sería el siguiente, utilizando como identificador “identificadorcliente” y “secretocliente” como secreto:

base64encode(urlencode(identificadorcliente) + ':' + urlencode(secretocliente))

Authorization: Basic aWRlbnRpZmljYWRvcmNsaWVudGU6c2VjcmV0b2NsaWVudGU=

  1. En segundo lugar, con la cabecera mencionada anteriormente debes hacer una invocación HTTP POST a la URL https://auth.kommodo.com/auth/realms/kommodo/protocol/openid-connect/token con la siguiente estructura:

Cabecera HTTP Valor
Content-Type application/x-www-form-urlencoded
Authorization Basic aWRlbnRpZmljYWRvcmNsaWVudGU6c2VjcmV0b2NsaWVudGU=
Campo cuerpo HTTP Valor
grant_type client_credentials
  1. Un ejemplo con la herramienta curl sería el siguiente:

curl -XPOST -H "Authorization: Basic aWRlbnRpZmljYWRvcmNsaWVudGU6c2VjcmV0b2NsaWVudGU=" -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=client_credentials' https://auth.kommodo.com/auth/realms/kommodo/protocol/openid-connect/token

  1. Esta petición devolverá el token correspondiente al cliente que ha iniciado sesión. La respuesta está formada por varios elementos en formato JSON:

Elemento Contenido
access_token Token de acceso que se utilizará para acceder al API.
id_token Token de identificación con la información relativa al cliente. Para más información consultar el siguiente enlace http://openid.net/specs/openid-connect-core-1_0.html#IDToken
token_type Tipo de token, en este caso siempre es “bearer”.
expires_in Tiempo en segundos de validez de dicho token, en este caso es una hora.
  1. La salida que mostraría la llamada de ejemplo curl sería lo siguiente:

{
  "access_token": "eyJhbGciOiJSUzI1Ni…...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsIm……."
}

  1. Una vez obtenido el access_token podremos invocar al API. Para ello, deberemos incluir la cabecera siguiente, sustituyendo ACCESS_TOKEN por el access_token recibido en el paso anterior:

Authorization: Bearer ACCESS_TOKEN
  1. En algunos casos, es posible que algunas invocaciones al API requieran parámetros adicionales. Un ejemplo de petición haciendo uso del token recibido en el ejemplo anterior con curl sería el siguiente:

curl -XPOST -H "Authorization: Bearer eyJhbGciOiJSUzI1Ni…..." -H "Content-Type: application/json" -d '{"limite":1, "filtros":{}}' https://api.kommodo.com/sips/v1/buscar/consumos

Refrescar sesiones

Los tokens recibidos tienen un periodo de expiración, definido en una hora. Cuando el token caduca, el servidor rechazará todas las peticiones que reciba. Por ello, es necesario obtener un nuevo token cuando esto sucede. Para solicitar un token nuevo es necesario realizar el flujo mencionado anteriormente.

Verificación de token, claves y caducidad de firma

Los tokens vienen firmados por el sistema de autenticación, por lo que todo cliente que quiera verificar que el token pertenece a auth.kommodo.com deberá comprobar que la firma sea correcta. En el caso de que se entregue un token que no está debidamente formado o haya sido alterado, el sistema lo rechazará. Para evitar que esto suceda, deben tenerse en cuenta varias cosas.

  1. El token caduca en un intervalo de tiempo definido en la petición de obtención.

  2. Por regla general, cuando se produzca un error HTTP 401 Unauthorized bien porque el token ha caducado, o bien porque las claves se han renovado, se recomienda realizar una petición de refresco siguiendo el flujo previamente descrito.


URLs referenciadas
Función URL
Autenticación https://auth.kommodo.com/auth/realms/kommodo/protocol/openid-connect/auth
Solicitud de token https://auth.kommodo.com/auth/realms/kommodo/protocol/openid-connect/token
Página de claves https://auth.kommodo.com/auth/realms/kommodo/protocol/openid-connect/certs
Página de información del protocolo OpenID Connect del servidor https://auth.kommodo.com/auth/realms/kommodo/.well-known/openid-configuration

Advertencia

El API de Kommodo SIPS se actualiza con frecuencia para ofrecer nuevas mejoras a sus usuarios. Estos cambios no suelen tener ninguna consecuencia para los clientes del API, pero en algunas ocasiones estas actualizaciones pueden requerir que los usuarios deban adecuar su cliente, considerándose cambios relevantes. Se consideran cambios relevantes aquellos que impliquen eliminar o renombrar campos en el JSON de respuesta de cualquiera de los endpoints. En estos casos, se implementará una nueva versión del API, manteniendo la anterior versión durante un periodo de al menos 6 meses desde su lanzamiento, con el objetivo de que todos los usuarios dispongan de tiempo suficiente para adaptar sus aplicaciones conectadas a Kommodo SIPS. Por el contrario, el cliente del API debe ser capaz de soportar la incorporación de nuevos campos en los JSON de respuesta, no considerándose éstos cambios relevantes a efectos de versionado y disponibilidad del API.