API-PLUMIER

De EduWiki
Saltar a: navegación, buscar
Versión Fecha Autor
API-Plumier v0.9 19/01/2017 Jose Luis Martínez del Amor

Índice de contenidos

Introducción

El presente documento explica el sistema de acceso a los servicios de Plumier XXI. El formato elegido se basa en la arquitectura de servicios REST y el intercambio de objetos en formato JSON. La arquitectura estará organizada en tipos de recurso y cada recurso tiene una o más representaciones y uno o más métodos que se describen a continuación.

Autenticación con OAuth

El proceso de autenticación se realizará utilizando el flujo básico del protocolo OAuth en su versión 2.0 (http://oauth.net/2/). Según este protocolo, se delega la autenticación del usuario final a un servicio de autenticación que, tras la autenticación y conformidad del usuario, proporcionará un token de acceso con el que la aplicación cliente podrá actuar en su nombre. Básicamente el proceso se compone de los siguientes pasos:

1. Obtener un código de autorización

La aplicación Cliente bien sea mediante redirección (en una Aplicación Web), o mediante un Cliente Web incrustado (Aplicación instalada), dirige al usuario final a la URL del Servidor de Autorización donde deberá autenticarse y consentir el acceso a sus datos por parte de la aplicación cliente:

URL de Acceso Descripción
https://localhost:8080/cas/oauth2.0/authorize Punto inicial del proceso de autenticación donde el usuario deberá autenticarse y dar su consentimiento. El result ado sera un código de autorización “code”.

La URL necesita los siguientes parámetros:

Parámetro Valor Descripción
response_type code Indica al Servidor de Autorización que debe devolverle un código de autorización.
client_id Identificador de la aplicación Cliente. El ID de Cliente identificará unívocamente la aplicación Cliente y es necesario para el acceso. Este dato es proporcionado por la Consejería.
redirect_uri URL en la que se espera la respuesta con el código de Autorización. Determina donde se enviará la respuesta, puede ser una URL donde el cliente escuche o una URL donde el cliente web embebido pueda detectar la respuesta. Esta URL deberá ser validada por la Conserjería en el momento de otorgar el ID de cliente.
scope Conjunto de permisos que la aplicación solicita separados por espacios. Indica las operaciones que el Cliente va a realizar sobre los datos del Usuario Final.
state string Parámetro de utilidad para el Cliente que puede rellenar con cualquier información que necesite para interpretar la respuesta recibida en redirect_uri. Este parámetro será devuelto a esa URL tal cual, sin ser manipulado por el Servidor de Autorización.

Un ejemplo de URL de invocación al servidor de autorización puede ser:

http://localhost:8080/cas/oauth2.0/authorize?scope=prueba&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fsample-oauth2-client%2Fpruebacbk%2Fcbk&state=statePrueba&client_id=PRUEBAS_CBK

Interpretando la respuesta

El Servidor de Autorización compone la URL de respuesta a partir de la URL indicada en “redirect_uri”. Si en esa URL hay un servicio escuchando (Caso de las aplicaciones Web), el servicio será el encargado de recoger la respuesta, también se puede recoger la URL del Cliente Web utilizado para abrir la conexión y extraer de ella el código. Se pueden recibir 2 tipos de respuesta: Respuesta de error:

http://localhost:8080/sample-oauth2-client/pruebacbk/cbk?error=access_denied&state=statePrueba

Respuesta de confirmación:

http://localhost:8080/sample-oauth2-client/pruebacbk/cbk?code=ST-1-56FCizl0PXGkKaUkNEtq-cas.murciaeduca.es&state=statePrueba

2. Intercambiar el código de autorización por un token de acceso

El código de autorización recibido en el paso anterior se debe intercambiar por un token de acceso, para ello se invoca con él la siguiente URL:

URL de Acceso Descripción
https://localhost:8080/cas/oauth2.0/accessToken Punto donde intercambiar el código de autorización por un Token de Acceso.

Los parámetros que espera la URL son:

Parámetro Descripción
code El código de autorización obtenido en el paso anterior.
client_id El ID de Cliente que identifica unívocamente la aplicación. Este dato es proporcionado por la Consejería
client_secret Secreto del cliente proporcionado por la Consejería a la vez que el ID de Cliente.
redirect_uri Esta URL validada por la Conserjería en el momento de otorgar el ID de cliente, en este caso cumple la función de validar al Cliente junto al ID y al secreto.
grant_type Debe contener el valor authorization_code, tal y como lo define la especificación OAuth 2.0.

Un ejemplo de URL de invocación al servidor de autorización para obtener un token de acceso puede ser:

http://localhost:8080/cas/oauth2.0/accessToken?client_secret=SECRETO_CLIENTE_PRUEBAS_CBK&grant_type=authorization_code&redirect_uri=http%3A%2F%2Flocalhost%3A8081%2Fsample-oauth2-client%2Fpruebacbk%2Fcbk&code=ST-1-P21txpeWtQoNkqFyndTh-cas.murciaeduca.es&client_id=PRUEBAS_CBK

En el cuerpo de la respuesta se pueden encontrar estos parámetros:

Parámetro Descripción
access_token Token de acceso para acceder a los servicios.
expires Tiempo de vida del token de acceso.
refresh_token Token que puede ser utilizado para renovar el token de acceso una vez haya expirado.

3. Invocación a los servicios

Cuando se invoque a un servicio que requiera autenticación se debe incluir el token de acceso como “Bearer token” en la cabecera http de autorización.


ID: 1 Address: http://localhost:8080/pxxi-profesores-rs/centros

Http-Method: GET

Content-Type:

Headers: {Accept=[application/json], Authorization=[Bearer TGT-1-okitl6HqcgkwcJD4QUqrnp7E0mineAZG4HLubTnOwhecMJFNfD-cas.murciaeduca.es], cache-control=[no-cache], connection=[keep-alive], Content-Type=[null], host=[localhost:8080], pragma=[no-cache], user-agent=[Java/1.7.0_51]}

4. Renovar un token de acceso

Para renovar el token de acceso se utiliza la misma URL que para obtener el token de acceso a partír del código de acceso:

URL de Acceso Descripción
https://localhost:8080/cas/oauth2.0/accessToken Punto donde obtener un Token de Acceso a partir de un token de refresco.

Los parámetros que espera la URL son:

Parámetro Descripción
refresh_token El token de refresco para obtener el token de acceso.
client_id El ID de Cliente que identifica unívocamente la aplicación. Este dato es proporcionado por la Consejería.
client_secret Secreto del cliente proporcionado por la Consejería a la vez que el ID de Cliente.
grant_type Debe contener el valor refresh_token, tal y como lo define la especificación OAuth 2.0 para la renovación de un token.

Un ejemplo de URL de invocación al servidor de autorización para obtener un token de acceso puede ser:

http://localhost:8080/cas/oauth2.0/accessToken?client_secret=SECRETO_CLIENTE_PRUEBAS_CBK&grant_type=refresh_token&refresh_token=ST-4-qo3hwCtidIhaJPQg0VH1diVWjSNllkm4WzitcTZ3pFfvVjpf5e-localhost&client_id=PRUEBAS_CBK

En el cuerpo de la respuesta se pueden encontrar estos parámetros:

Parámetro Descripción
access_token Nuevo token de acceso para acceder a los servicios.
expires Tiempo de vida del nuevo token de acceso.

5. Revocar un token

Para revocar un token de acceso o un token de refresco hay que invocar a la siguiente URL con el token a revocar:

URL de Acceso Descripción
https://localhost:8080/cas/oauth2.0/revoke Punto donde revocar el token de acceso.

Los parámetros que espera la URL son:

Parámetro Descripción
token Token de acceso a revocar.

Es recomendable revocar tanto el token de acceso como el token de refresco.

Autenticación con CAS

Algunos servicios que se autentican utilizando cookies de sesión generadas por el conjunto Apache Shriro – CAS. El proceso consiste obtener lo que se conoce como “Ticket Granting Ticket” o (TGT) presentando un usuario y contraseña para posteriormente intercambiar dicho TGT por un “Service Ticket” (ST). Apache Shiro que protege los servicios asociando el el ST a la sesión tomcat.

1. Obtener un Ticket Granting Ticket

Para obtener un Ticket Granting Ticket del CAS se debe invocar a la siguiente URL:

URL de Acceso Descripción
https://caspruebas.murciaeduca.es/mirador-api/services/public/login/{usuario}/{clave} Punto inicial del proceso de autenticación con CAS. El resultado un objeto con un código de resultado y un TGT.

La URL necesita los siguientes parámetros:

Parámetro Valor Descripción
usuario Nombre de usuario. El login de usuario (login de docente, NRE de alumno, NIF de padre, …).
clave Contraseña del usuario. Contraseña asociada al usuario.

La respuesta es un objeto con los siguientes campos:

Formato de Datos

{

"status": {número},

"session_token": {string}

}

Nombre del campo Valor Descripción Notas
status número Código de estado, 200 = OK.
session_token string Ticket Granting Ticket devuelto.

Un ejemplo de URL de invocación al servidor de autorización puede ser:

http://caspruebas.murciaeduca.es/mirador-api/services/public/login/6733559/miclave

2. Obtener un Service Ticket

Para obtener un Service Ticket del CAS se debe invocar a la siguiente URL:

URL de Acceso Descripción
https://caspruebas.murciaeduca.es/mirador-api/services/public/login/{tgt} El segundo paso en el proceso de autenticación con CAS. El resultado es una cadena con el ST.

La URL necesita los siguientes parámetros:

Parámetro Valor Descripción
tgt Ticket Granting Ticket. El Ticket Granting Ticket obtenido en el paso anterior.

La respuesta es una cadena con el Service ticket.

Un ejemplo de URL de obtención del service ticket es:

http://caspruebas.murciaeduca.es/mirador-api/services/public/login/TGT-16-ZbqIOOdy3xMBAgLMJ3w2lt5ONYoWHfqCbA6weRdIc2laFy4Cbm-caspruebas.murciaeduca.es

Referencia API de Profesores

Referencia API de Mirador