Documentos relacionados
OAuth 2.0 se estandarizó como RFC 6749. En https://oauth.net/2, se encuentra disponible un documento detallado. La autenticación básica HTTP se define en la sección 2 de RFC 2617.
Descripción general
Por lo general, para proporcionar a las aplicaciones de terceros acceso a recursos restringidos, como los detalles del plan de datos y de la billetera, el usuario final (propietario del recurso) debe compartir sus credenciales con el tercero. Esto genera varios problemas y limitaciones, como el almacenamiento de credenciales, la autenticación con contraseña, el acceso amplio a los recursos del usuario final y la filtración de contraseñas, entre otros. OAuth 2.0 aborda estos problemas con la introducción de una capa de autorización y, de este modo, protege y limita el acceso a los recursos protegidos del usuario final.
En lugar de usar las credenciales del usuario final para acceder a recursos protegidos, como los detalles del plan de datos, el GTAF obtiene un token de acceso. Los tokens de acceso se emiten a GTAF en nombre de las credenciales de GTAF. Luego, la GTAF usa el token de acceso para acceder a los detalles del plan de datos alojados por el DPA.
En la siguiente figura, se muestra el flujo de información de alto nivel:
Figura 1. Flujo de OAuth abstracto.
Tokens de acceso
Los tokens de acceso son las credenciales que usa la GTAF para acceder a los detalles del plan de datos de la DPA del operador. Un token de acceso es una cadena que representa una autorización emitida para el GTAF. Por lo general, la cadena es opaca para la GTAF. Los tokens representan permisos y duraciones de acceso específicos que el usuario final otorga al operador y que aplican el DPA y el servidor de OAuth del operador.
El token de acceso proporciona una capa de abstracción, ya que reemplaza diferentes estructuras de autorización (p.ej., nombre de usuario y contraseña) por un solo token que comprende el DPA. Esta abstracción permite emitir tokens de acceso más restrictivos que el otorgamiento de autorización que se usó para obtenerlos, así como eliminar la necesidad de que el DPA comprenda una amplia variedad de métodos de autenticación.
Los tokens de acceso pueden tener diferentes formatos, estructuras y métodos de utilización (p.ej., propiedades criptográficas) según los requisitos de seguridad del operador. GTAF solo admite tokens de acceso de tipo portador definidos en [RFC6750].
Autenticación de clientes
El GTAF funciona como un "cliente confidencial" y es capaz de mantener las contraseñas seguras. Actualmente, la GTAF solo admite la autenticación básica HTTP para autenticarse con la DPA. El identificador del cliente se codifica con el algoritmo de codificación "application/x-www-form-urlencoded", y el valor codificado se usa como nombre de usuario. La contraseña se codifica con el mismo algoritmo y se usa como contraseña.
Los clientes confidenciales, como GTAF, a los que se les emiten credenciales de cliente, se autentican con el servidor de OAuth del operador mientras realizan solicitudes al extremo del token. La autenticación del cliente se usa para lo siguiente: \
- Recuperarse de un cliente vulnerado inhabilitándolo o cambiando sus credenciales, lo que impide que un atacante abuse de los tokens de actualización robados Cambiar un solo conjunto de credenciales de cliente es mucho más rápido que revocar un conjunto completo de tokens de actualización.
- Implementar las prácticas recomendadas de administración de la autenticación, que requieren la rotación periódica de credenciales
El GTAF usa el parámetro de solicitud "client_id" para identificarse cuando envía solicitudes al extremo del token.
En particular, es importante la capacidad de rotar las credenciales del cliente. El servidor de OAuth debe poder admitir dos pares de credenciales simultáneos durante la rotación y debe tener la capacidad de inhabilitar credenciales. En una rotación de credenciales típica, sucede lo siguiente:
- La empresa de transporte crea nuevas credenciales en el servidor de OAuth y se las entrega a su administrador de cuentas técnicas de forma segura.
- Google prueba la nueva credencial y cambia la configuración de GTAF para usarla.
- Google notifica al operador que es posible que se inhabiliten las credenciales anteriores.
- La empresa de telefonía celular inhabilita las credenciales y notifica a Google
- Google verifica que las credenciales anteriores ya no estén operativas.
El servidor de OAuth debe ser capaz de admitir el proceso de rotación anterior.
Extremo del token
El extremo del token lo usa el GTAF para obtener un token de acceso presentando su otorgamiento de autorización o token de actualización. El extremo del token se usa con cada otorgamiento de autorización, excepto con el tipo de otorgamiento implícito (ya que se emite un token de acceso directamente).
A continuación, se incluyen algunos puntos que se deben tener en cuenta cuando se configura un extremo de token:
- La ubicación del extremo del token debe proporcionarse en la documentación del servicio.
- El URI del extremo puede incluir un componente de consulta con formato "application/x-www-form-urlencoded" que se debe conservar cuando se agregan parámetros de consulta adicionales. El URI del extremo no debe incluir un componente de fragmento.
- Dado que las solicitudes al extremo del token generan la transmisión de credenciales de texto no encriptado (en la solicitud y la respuesta HTTP), el servidor OAuth del operador debe usar TLS para enviar solicitudes al extremo del token.
- El GTAF usa el método HTTP "POST" cuando realiza solicitudes de tokens de acceso.
- Los parámetros que se envían sin un valor deben tratarse como omitidos en la solicitud. El servidor de OAuth debe ignorar los parámetros de solicitud no reconocidos. Los parámetros de solicitud y respuesta no deben incluirse más de una vez.
- GTAF solo admite tokens de acceso de tipo portador.
Permiso del token de acceso
Los extremos de autorización y de token permiten que el cliente especifique el alcance de la solicitud de acceso con el parámetro de solicitud "scope". A su vez, el servidor de autorización usa el parámetro de respuesta "scope" para informar al cliente sobre el alcance del token de acceso emitido.
El valor del parámetro scope se expresa como una lista de cadenas que distinguen mayúsculas de minúsculas y están delimitadas por espacios. El servidor de autorización define las cadenas. Si el valor contiene varias cadenas separadas por espacios, su orden no importa y cada cadena agrega un rango de acceso adicional al alcance solicitado.
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
GTAF no requiere que se implemente el alcance, pero admite esta función. Para obtener más información, consulta la sección 3.3 de la RFC 6749.
Cómo emitir un token de acceso
Si la solicitud de token de acceso que envía el GTAF es válida y está autorizada, el servidor de OAuth emite un token de acceso y un token de actualización opcional. Si la solicitud no supera la autenticación del cliente o no es válida, el servidor de OAuth devuelve una respuesta de error, como se describe en la siguiente sección.
Respuesta correcta
Cuando el GTAF envía una solicitud, el servidor de OAuth emite un token de acceso y un token de actualización opcional, y construye la respuesta agregando los siguientes parámetros al cuerpo de la entidad de la respuesta HTTP con un código de estado 200 (OK): \
- access_token: OBLIGATORIO. Es el token de acceso que emite el servidor de OAuth. GTAF espera que el extremo del token devuelva un token de portador.
- expires_in: OBLIGATORIO. Es la vida útil del token de acceso en segundos. Por ejemplo, el valor "3600" indica que el token de acceso vencerá una hora después de que se generó la respuesta. Si se omite, el servidor de OAuth debe proporcionar el tiempo de vencimiento por otros medios o documentar el valor predeterminado.
- token_type: OBLIGATORIO. Es el tipo de token emitido. Para obtener más información sobre los diferentes tipos de tokens, consulta la sección 7.1 del RFC 6749. El valor no distingue mayúsculas de minúsculas. En el momento de escribir este artículo, GTAF solo admite tokens de portador.
- refresh_token: OPCIONAL. Es el token de actualización, que se puede usar para obtener tokens de acceso nuevos con el mismo otorgamiento de autorización.
- scope: OPCIONAL, si se implementa y es idéntico al permiso solicitado por el GTAF; de lo contrario, es obligatorio.
Los parámetros se incluyen en el cuerpo de la entidad de la respuesta HTTP con "application/json". Los parámetros se serializan en una estructura de JavaScript Object Notation (JSON) agregando cada parámetro en el nivel de estructura más alto. Los nombres de los parámetros y los valores de cadena se incluyen como cadenas JSON. Los valores numéricos se incluyen como números JSON. El orden de los parámetros no importa y puede variar.
El servidor de autorización DEBE incluir el campo del encabezado de respuesta HTTP "Cache-Control" con el valor "no-store" en cualquier respuesta que contenga tokens, credenciales o cualquier otra información sensible, así como el campo del encabezado de respuesta "Pragma" con el valor "no-cache".
Por ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Estos son algunos puntos importantes que debes tener en cuenta:
- La GTAF ignora los nombres de valores no reconocidos en la respuesta.
- Los tamaños de los tokens y otros valores recibidos del servidor de OAuth no se definen.
- La GTAF debe evitar hacer suposiciones sobre los tamaños de los valores. El servidor de OAuth debe documentar el tamaño de cualquier valor que emita.
Respuesta de error
Si una solicitud de autorización falla por algún motivo, como la falta de un URI de redireccionamiento, o si este es no válido o no coincide, o si falta el identificador del cliente o este no es válido, el servidor de OAuth debe responder con un código de estado HTTP 400 (Solicitud incorrecta), a menos que se especifique lo contrario, y debe incluir al menos uno de los parámetros que se enumeran en la sección Códigos y respuestas de error.
Otorgamiento de autorización en GTAF
Un otorgamiento de autorización es una credencial que representa la autorización del usuario final (para acceder a sus recursos protegidos, como la información del saldo de datos) que usa la GTAF para obtener un token de acceso.
El GTAF usa el tipo de otorgamiento client_credentials. En el tipo de concesión client_credentials, GTAF solicita un token con una solicitud HTTP POST y autenticación básica HTTP. Todas las solicitudes se envían a través de TLS (es decir, HTTPS) y GTAF no se puede integrar con un servidor de OAuth sin un certificado TLS válido. GTAF puede pasar un alcance de token configurable y pasará un alcance vacío si no se configura uno.
La GTAF espera que se muestre un token de acceso junto con un valor de "expires_in" (tiempo de vida). El valor de expires_in debe ser de al menos 900 segundos y no debe superar las pocas horas. La solicitud de un token nuevo no debe provocar que los tokens existentes venzan antes de tiempo.
Para obtener más detalles sobre los distintos tipos de concesión, consulta la sección 1.3 del RFC 6749.
Ejemplo de solicitud y respuesta
Supongamos que el GTAF tiene la siguiente configuración para un servidor de OAuth:
URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa
Nota: El secreto del cliente de un DPA real debe ser mucho más seguro que el que se muestra en el ejemplo.
Para generar la cadena de autorización, se concatenan el ID del cliente, “:”, y la contraseña, y se codifican en base64. Esto se puede replicar en una interfaz de línea de comandos de la siguiente manera:
$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==
Luego, GTAF realiza una solicitud HTTPS POST al servidor de OAuth con estas credenciales, el tipo de concesión client_credentials y el alcance configurado. En el ejemplo, la solicitud de GTAF es similar a la solicitud generada por:
$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'
Los encabezados que usa GTAF no coincidirán con los que envía curl, aunque el encabezado de autorización será idéntico.
GTAF espera una respuesta con el siguiente formato:
{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}
A continuación, se muestra un ejemplo de una respuesta válida:
{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}
Nota: La respuesta debe ser un JSON válido.
Códigos y respuestas de error
Si una solicitud de autorización de GTAF falla por alguno de los motivos indicados en la sección Respuesta de error, el servidor de OAuth debe responder con un código de estado HTTP 400 (Solicitud incorrecta), a menos que se especifique lo contrario, y debe incluir uno de los siguientes parámetros en la respuesta:
Por ejemplo: \
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
GTAF espera que el servidor de OAuth admita las siguientes respuestas de error:
| Código de error | Respuesta | Motivo |
| HTTP 400 | invalid_request | La solicitud no incluye un parámetro obligatorio, incluye un valor de parámetro no admitido (que no sea el tipo de otorgamiento), repite un parámetro, incluye varias credenciales, utiliza más de un mecanismo para autenticarse con la GTAF o está mal formada de alguna otra manera. |
| HTTP 401 | invalid_client | Falló la autenticación del cliente (p.ej., cliente desconocido, no se incluyó la autenticación del cliente o no se admite el método de autenticación). El servidor de OAuth puede devolver un código de estado HTTP 401 (No autorizado) para indicar qué esquemas de autenticación HTTP son compatibles. Si el cliente intentó autenticarse a través del campo de encabezado de solicitud "Authorization", el servidor de OAuth debe responder con un código de estado HTTP 401 (Unauthorized) y debe incluir el campo de encabezado de respuesta "WWW-Authenticate" que coincida con el esquema de autenticación que usa el cliente. |
| HTTP 500 | Error del servidor de OAuth |
Para obtener detalles sobre otras respuestas que se pueden usar para la depuración, consulta la sección 5.2 del RFC 6749.