Documentos relacionados
OAuth 2.0 está estandarizado como RFC 6749. Hay un documento detallado disponible en https://oauth.net/2. 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 planes de datos y detalles de Wallet, el usuario final (propietario del recurso) debe compartir sus credenciales con el tercero. Esto crea varios problemas y limitaciones, como almacenamiento de credenciales, autenticación de contraseñas, acceso amplio a los recursos del usuario final y filtración de contraseñas, entre otros. La solución OAuth2.0 aborda estos problemas mediante la introducción de una capa de autorización que protege y limita el acceso a los recursos protegidos del usuario final.
En lugar de usar las credenciales del usuario final para acceder a los 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, el GTAF usa el token de acceso para acceder a los detalles del plan de datos alojados por la APD.
En la siguiente figura, se proporciona un 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 el GTAF para acceder a los detalles del plan de datos desde la APD del proveedor. Un token de acceso es una string que representa una autorización emitida al GTAF. Por lo general, la string es opaca para el GTAF. Los tokens representan alcances y duraciones de acceso específicos, otorgados por el usuario final al proveedor y aplicados por el DPA y el servidor OAuth del proveedor.
El token de acceso proporciona una capa de abstracción que reemplaza las diferentes construcciones de autorización (p.ej., nombre de usuario y contraseña) con un solo token que entiende la APD. Esta abstracción permite emitir tokens de acceso más restrictivos que la concesión de autorización usada para obtenerlos, además de quitar la necesidad de los DPA de comprender una amplia gama de métodos de autenticación.
Los tokens de acceso pueden tener diferentes formatos, estructuras y métodos de uso (p.ej., propiedades criptográficas) según los requisitos de seguridad del proveedor. GTAF solo admite tokens de acceso de tipo del 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, el GTAF solo admite la autenticación HTTP básica para autenticarse con el DPA. El identificador de cliente se codifica mediante 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, que son credenciales de cliente emitidos, se autentican con el servidor OAuth del proveedor mientras realizan solicitudes al extremo del token. La autenticación del cliente se usa para lo siguiente: \
- Recuperarse de un cliente comprometido mediante la inhabilitación del cliente o el cambio de sus credenciales, lo que evita 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 prácticas recomendadas para la administración de autenticación, que requieren la rotación periódica de credenciales
El GTAF utiliza el parámetro de solicitud "client_id" para identificarse cuando envía solicitudes al extremo del token.
De particular importancia es la capacidad de rotar las credenciales del cliente. El servidor de OAuth debe ser compatible con dos pares de credenciales simultáneas durante la rotación y debe tener la capacidad de inhabilitarlas. En una rotación de credenciales típica, sucede lo siguiente:
- El proveedor crea credenciales nuevas en el servidor de OAuth y las entrega al administrador técnico de cuentas de manera segura.
- Google prueba la credencial nueva y cambia la configuración de GTAF para usarla.
- Google notifica al proveedor que es posible que se inhabiliten las credenciales anteriores.
- El proveedor inhabilita las credenciales y notifica a Google
- Google verifica que las credenciales anteriores ya no estén operativas
El servidor OAuth debe ser compatible con el proceso de rotación anterior.
Extremo del token
El GTAF utiliza el extremo del token para obtener un token de acceso mediante la presentación de su token de autorización o actualización. El extremo del token se usa con cada otorgamiento de autorización, excepto el tipo de otorgamiento implícito (ya que un token de acceso se emite directamente).
Los siguientes son algunos puntos que se deben tener en cuenta cuando configuras un extremo de token:
- La ubicación del extremo del token se debe proporcionar en la documentación del servicio.
- El URI del extremo puede incluir un componente de consulta con formato “application/x-www-form-urlencoded” que debe retenerse cuando se agregan parámetros de consulta adicionales. El URI del extremo no debe incluir un componente de fragmento.
- Debido a que las solicitudes al extremo del token dan como resultado la transmisión de credenciales de texto claro (en la solicitud y la respuesta HTTP), el servidor de OAuth del proveedor debe usar TLS para enviar solicitudes al extremo del token.
- La GTAF usa el método HTTP &POST; cuando realiza una solicitud de token de acceso.
- Los parámetros enviados sin un valor deben tratarse como omitidos de la solicitud. El servidor OAuth debe ignorar los parámetros de solicitud no reconocidos. Los parámetros de solicitud y respuesta no se deben incluir más de una vez.
- GTAF solo admite tokens de acceso de tipo del portador.
Alcance del token de acceso
Los extremos de autorización y 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 de alcance se expresa como una lista de strings separadas por mayúsculas y minúsculas, que distinguen entre mayúsculas y minúsculas. El servidor de autorización define las strings. Si el valor contiene varias strings delimitadas por espacios, su orden no importa y cada string 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 el alcance para implementarse, pero admite esta función. Para obtener más información, consulta la sección 3.3 de 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 falla en la autenticación del cliente o no es válida, el servidor OAuth muestra una respuesta de error como se describe en la siguiente sección.
Respuesta correcta
Cuando el GTAF envía una solicitud, el servidor 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 El token de acceso emitido por el servidor de OAuth. GTAF espera que el extremo del token muestre un token del portador.
- expires_in: OBLIGATORIO El ciclo de vida del token de acceso en segundos. Por ejemplo, el valor "3600" indica que el token de acceso caducará una hora después de que se genere la respuesta. Si se omite, el servidor OAuth debe proporcionar la hora de vencimiento por otros medios o documentar el valor predeterminado.
- token_type: OBLIGATORIO El tipo de token emitido. Para obtener más información sobre los diferentes tipos de tokens, consulta la sección 7.1 de RFC 6749. El valor no distingue entre mayúsculas y minúsculas. GTAF solo admite tokens del portador al momento de redactar este documento.
- refresh_token: OPCIONAL. El token de actualización, que se puede usar para obtener nuevos tokens de acceso con la misma concesión de autorización.
- scope: OPCIONAL, si se implementó, y es idéntico al alcance que solicita el GTAF; de lo contrario, es obligatorio.
Los parámetros se incluyen en el cuerpo de la entidad de la respuesta HTTP mediante el protocolo "application/json". Los parámetros se serializan en una estructura de notación de objetos (JSON) de JavaScript agregando cada parámetro en el nivel de estructura más alto. Los nombres de los parámetros y los valores de string se incluyen como strings 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 de encabezado de respuesta HTTP “Cache-Control” con un valor de “no-store” en cualquier respuesta que contenga tokens, credenciales u otra información confidencial, así como el campo de encabezado de respuesta “Pragma” con un valor de “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 a tener en cuenta:
- El 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.
- El GTAF debe evitar hacer suposiciones sobre los tamaños de valores. El servidor OAuth debe documentar el tamaño de cualquier valor que emita.
Respuesta de error
Si una solicitud de autorización falla por cualquier motivo, como que falte un URI de redireccionamiento, no sea válido o no coincida, o si falta el identificador de cliente o no es válido, el servidor 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 enumerados en la sección Error Response y Codes.
Otorgamiento de autorización en GTAF
Una concesión de autorización es una credencial que representa la autorización del usuario final (para acceder a sus recursos protegidos, como la información de saldo de datos) que utiliza el GTAF para obtener un token de acceso.
La GTAF utiliza el tipo de otorgamiento client_credentials. En el tipo de otorgamiento client_credentials, el GTAF solicita un token mediante una solicitud HTTP POST y la autenticación básica HTTP. Todas las solicitudes se envían a través de TLS (es decir, HTTPS) y GTAF no pueden integrarse a un servidor OAuth sin un certificado TLS válido. GTAF puede pasar un alcance de token configurable y pasará un alcance vacío si no está configurado.
GTAF espera que se muestre un token de acceso junto con un valor (tiempo de actividad) (tiempo de actividad). El valor expiration_in debe ser de al menos 900 segundos y no debe durar más de unas horas. Solicitar un token nuevo no debe causar que los tokens existentes caduquen antes.
Para obtener más detalles sobre los distintos tipos de otorgamientos, consulta la sección 1.3 de RFC 6749.
Ejemplo de solicitud y respuesta
Supongamos que el GTAF tiene la siguiente configuración para un servidor OAuth:
URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa
Nota: El secreto del cliente para un DPA real debe ser mucho más seguro que el que se muestra en el ejemplo.
Para producir la string de autorización, el ID de cliente, ':' y la contraseña están concatenados y codificados 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, el GTAF realiza una solicitud HTTPS POST al servidor OAuth mediante estas credenciales, el tipo de otorgamiento de credenciales de cliente y el alcance configurado. Por 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 utiliza GTAF no coincidirán con los enviados por curl, aunque el encabezado de autorización será idéntico.
GTAF espera una respuesta como la siguiente:
{
"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 JSON válida.
Códigos y respuesta de error
Si una solicitud de autorización del GTAF falla debido a cualquiera de los motivos que se indican en la sección Error Response, el servidor OAuth debe responder con un código de estado HTTP 400 (Solicitud incorrecta) (a menos que se especifique lo contrario) y, además, 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 OAuth admita las siguientes respuestas de error:
| Código de error | Respuesta | Motivo |
| HTTP 400 | solicitud_no válida | A la solicitud le falta un parámetro obligatorio, incluye un valor de parámetro no admitido (que no sea tipo de otorgamiento), repite un parámetro, incluye múltiples credenciales, utiliza más de un mecanismo para autenticarse con el GTAF o presenta errores de formato. |
| HTTP 401 | cliente_no válido | Falló la autenticación del cliente (p.ej., cliente desconocido, no se incluyó la autenticación del cliente o un método de autenticación no admitido). El servidor OAuth puede mostrar un código de estado HTTP 401 (No autorizado) para indicar los esquemas de autenticación HTTP compatibles. Si el cliente intentó autenticarse a través del campo de encabezado de la solicitud, el servidor OAuth debe responder con un código de estado HTTP 401 (No autorizado) e incluir el campo de encabezado de respuesta WWW-Authenticate que coincida con el esquema de autenticación utilizado por el cliente. |
| HTTP 500 | Falla del servidor OAuth |
Si quieres obtener detalles sobre otras respuestas que se pueden usar para depurar, consulta la sección 5.2 de RFC 6749.