Autorización/Autenticación
El federador implementa seguridad basada en oAuth2 con tokens, por lo cual la primera llamada de las aplicaciones autorizadas debe realizarse a la url que provee el token ([auth]).
Registro de Aplicaciones
Previo al uso del servicio de autenticación, la aplicación que realiza el pedido debe solicitar a los administradores del federador para cada dominio donde funcione (en el caso de funcionar para más de un hospital o prestador de salud, debe hacerlo para cada uno):
- Registrar una URI fija para la aplicación en el federador (debe ser la del dominio)
- En el caso de utilizar firma digital: Registrar una clave pública RSA (SHA-256)
Una vez registrada la aplicación, se establece una relación de confianza entre la aplicación y el federador, esto es, la aplicación se considera ‘pre-autorizada’ para acceder a los pacientes asociados.
El federador asignará al servicio un identificador denominado client_id
Luego, en tiempo de ejecución, el servicio debe obtener un token de acceso para poder acceder a los documentos. Estos tokens de acceso pueden ser generados automáticamente, sin necesidad de intervención humana, con una expiración recomendada de 15 minutos. Generación del Token de Autenticación
Para obtener el token de acceso, debe generar un token JWT (de un solo uso) que será utilizado para autenticar el servicio ante el federador. El token JWT debe ser construido con los claims que figuran a continuación Para más información sobre cómo generar y firmar el token, ver http://jwt.io. Los marcados en rojo son estándares y los marcados en azul son payload específico del federador. En caso de utilizar firma digital (clave pública / privada), se requiere firmar digitalmente el token y utilizar el método RS256 de JWT. Si no se utiliza firma digital, utilizar directamente el método HS256.
Claim Descripción Detalles iss Issuer URL de la aplicación sub Subject client_id de la aplicación aud Audience URL de [auth] iat Issued At Fecha de generación del Token exp Expiration Date Fecha de Expiración del token (no más de 5 minutos en el futuro) jti Identificación de Token un string nonce que identifica este JWT de autenticación
Ejemplo (Datos)
Claim Descripción Detalles iss Issuer www.hospitalramosmejia.gov.ar sub Subject 202910 aud Audience www.federador.gov.ar/auth/v1 iat Issued At 2017-04-15T19:25:46.507Z exp Expiration Date 2018-04-15T19:25:46.507Z jti Identificación de Token qwertyuiopasdfghjklzxcvbnm123456
JSON (Plain Text)
{ "iss": "www.hospitalramosmejia.gov.ar", "iat": 1492284346, "exp": 1523820346, "aud": "www.federador.gob.ar/auth/v1", "sub": "202910", “jti” : “qwertyuiopasdfghjklzxcvbnm123456” }
JWT Generado (HS256)
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ3d3cuaG9zcGl0YWxyYW1vc21lamlhLmdvdi5hciIsImlhdCI6MTQ5MjI4NDM0NiwiZXhwIjoxNTIzODIwMzQ2LCJhdWQiOiJ3d3cuYW1iYWRvYy5nb3YuYXIvYXV0aC92MSIsInN1YiI6IjIwMjkxMCIsIm5hbWUiOiJTYWxkaXZhciBHb256YWxlcyBFcm5lc3RvIiwicm9sZSI6Ik3DqWRpY28gQ2zDrW5pY28iLCJpZGVudCI6Ind3dy5hbWJhZG9jLmdvdi5hci91c3Vhcmlvc3wyMDE4MiJ9.NEaC-iMGHCMV5KtfyBRsoO_Feleqn-InQjd7Ntuq5QU
(Puede verificarse el token generado en jwt.io)
Obtención del Token de Acceso
El token de acceso se obtiene realizando un POST HTTPS a la dirección [auth] con Content-Type : application/x-www-form-urlencoded y los siguientes parámetros:
Parametro Descripción Detalles grant_type Valor Fijo client_credentials scope El nivel de acceso requerido patient/DocumentReference.write (para registrar documentos individuales) patient/Bundle.write (para registrar documentos con adjuntos) client_assertion_type Valor Fijo urn:ietf:params:oauth:client-assertion-type:jwt-bearer client_assertion Token JWT Firmado (Ver el paso anterior: Generación del Token de Autenticacion)
Ejemplo
POST /token HTTP/1.1 Host: www.federador.gov.ar/auth Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=patient%2FDocumentReference.write&client_assertion_type=rn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ3d3cuaG9zcGl0YWxyYW1vc21lamlhLmdvdi5hciIsImlhdCI6MTQ5MjI4NDM0NiwiZXhwIjoxNTIzODIwMzQ2LCJhdWQiOiJ3d3cuYW1iYWRvYy5nb3YuYXIvYXV0aC92MSIsInN1YiI6IjIwMjkxMCIsIm5hbWUiOiJTYWxkaXZhciBHb256YWxlcyBFcm5lc3RvIiwicm9sZSI6Ik3DqWRpY28gQ2zDrW5pY28iLCJpZGVudCI6Ind3dy5hbWJhZG9jLmdvdi5hci91c3Vhcmlvc3wyMDE4MiJ9.NEaC-iMGHCMV5KtfyBRsoO_Feleqn-InQjd7Ntuq5QU Respuesta a la Solicitud de Token de Acceso
La respuesta será un objeto JSON con las siguientes propiedades Propiedad Descripción Detalles scope El nivel de acceso otorgado patient/DocumentReference.write y/o patient/Bundle.write
access_token El token otorgado por el servidor token_type Valor Fijo bearer expires_in Plazo de expiración del token Se sugiere un plazo de 900 (quince minutos)
Ejemplo de Respuesta JSON
{ "access_token": "m7rt6i7s9nuxkjvi8vsx", "token_type": "bearer", "expires_in": 900, "scope": "patient/write,patient/read" }
Inclusión del Token en el Encabezado de las Solicitudes HTTPS
En todas las invocaciones al registro o repositorio debe incluirse el token obtenido como encabezado (header).
Nombre: Authorization Valor: Bearer: [token]
El token será validado por el registro contra las reglas de negocio (verificando si la aplicación puede o no acceder a la información del paciente requerido)