Compartir a través de

Autenticación de API basada en tokens

  • Artículo

Para aumentar la seguridad de las interacciones con Digital Platform API, hemos implementado un sistema de autenticación basado en tokens firmado. Este sistema usa tokens web JSON (JWT) para ayudar a garantizar que las sesiones sean lo más seguras posible. Siga estas instrucciones y debería estar en funcionamiento con JWT en ningún momento.

Nota:

Esta funcionalidad está disponible actualmente para todos los usuarios de Digital Platform API. Aunque la autenticación basada en tokens JWT proporciona seguridad adicional, en este momento se recomienda su uso, pero no es obligatorio. Consulte Servicio de autenticación para obtener más información sobre los procesos de autenticación.

¿Qué es JWT?

Desde el sitio web de JWT:

"JSON Web Token (JWT) es un estándar abierto (RFC 7519) que define una manera compacta y independiente de transmitir información de forma segura entre partes como un objeto JSON".

Xandr proporciona servicios de API REST para que pueda comunicarse con nuestro sistema a través de consultas de línea de comandos y archivos JSON, y devuelve respuestas en forma de JSON. La implementación de un estándar que le permite transmitir esta información de forma segura proporciona una mayor protección de los datos y de todo el sistema de Xandr.

Además, los tokens permiten una mejor administración de los inicios de sesión de usuario. Cuando la contraseña expire, debe cambiar inmediatamente a una nueva contraseña. Con los tokens, puede tener varios tokens a la vez, por lo que cuando un token esté a punto de expirar, tendrá un período de transición que le da tiempo para actualizar la información de inicio de sesión.

Biblioteca JWT

Para usar tokens JWT, tendrá que tener un generador de tokens. Puede generar tokens JWT mediante una de las muchas bibliotecas disponibles en el sitio web de JWT.

Preparación para usar tokens

Para poder usar tokens, deberá iniciar sesión con su contraseña para recopilar información y configurar los tokens en el sistema de Xandr. Una vez registrado el token JWT, no tendrá que volver a iniciar sesión con una contraseña.

Para empezar, autentique y recupere un token de inicio de sesión inicial:

curl -X POST -d '{"auth":{"username":"<username>","password":"<PWD>"}}' https://api.appnexus.com/auth

El nombre de usuario y la contraseña son sus credenciales de inicio de sesión estándar.

Incluido en la respuesta de esta llamada será un token, que tendrá un aspecto similar al siguiente:

"token": "hbapi:123456:9999aa0000dd9:nym2",

Usará este token para acceder al sistema hasta que haya registrado la clave pública (que crearemos en un momento).

A continuación, debe recuperar el identificador de usuario. Recupere el identificador de usuario llamando al servicio de usuario:

curl -H 'Authorization: hbapi:123456:9999aa0000dd9:nym2' 'https://api.appnexus.com/user?username=<username>'

Como usuario que ha iniciado sesión actualmente, también puede usar este comando para buscar el identificador:

curl -H 'Authorization: hbapi:123456:9999aa0000dd9:nym2' 'https://api.appnexus.com/user?current'

Anote el identificador que se devuelve y lo usará más adelante en un archivo JSON para configurar el token.

Create claves privadas y públicas

Nota:

Information

La Administración de red es el rol de plataforma necesario para crear una clave pública para una cuenta determinada.

La clave privada se usa para firmar las solicitudes de autenticación. Una clave privada está pensada para ser exactamente eso: privada. No quiere compartir esta clave con nadie. Ejecute este comando para crear la clave privada:

openssl genrsa -out my-api-key 2048
  • openssl: esta es la herramienta de comandos que creará un archivo que contiene la clave privada. Implementa los protocolos Capa de sockets seguros y Seguridad de la capa de transporte.
  • genrsa: el comando que indica a openssl que genere una clave privada. Esto usa el sistema criptográfico RSA.
  • -out my-api-key: coloque la clave privada en el archivo denominado my-api-key.
  • 2048: tamaño, en bits, de la clave privada. Si deja fuera este número, el valor predeterminado es 512. Se recomienda un valor de 2048.

El my-api-key archivo reemplazará la contraseña como el secreto que protege la cuenta de API.

Use la clave privada para generar una clave pública:

openssl rsa -in my-api-key -pubout > my-api-key.pub
  • rsa: el comando que procesa las claves RSA.
  • -in my-api-key: archivo que contiene la clave privada que se va a usar como entrada para crear la clave pública.
  • -pubout: esta opción especifica que se debe generar una clave pública en lugar de una clave privada.
  • >my-api-key.pub: archivo que contiene la clave pública.

La clave pública se compartirá con la API y se usará para comprobar que la clave privada se usó para firmar el JWT.

Reemplazar caracteres de nueva línea

La clave pública contiene saltos de línea. Dado que esta clave se enviará a la API como parte de una carga JSON, debe reemplazar los saltos de línea por caracteres de nueva línea: \n. Puede hacerlo manualmente y, a continuación, copiar la clave en el archivo JSON, o bien puede ejecutar el siguiente comando y copiar la salida:

perl -pe 's/n\n/\\n/g' my-api-key.pub

Nota:

En función del entorno de la línea de comandos, puede mostrar la clave con saltos de línea en lugar del carácter \n. Si esto sucede, deberá escribir manualmente un \n para reemplazar cada salto de línea al copiar la clave en el archivo JSON.

Create el archivo JSON de clave pública

Create un archivo JSON como el siguiente:

{
  "public-key": {
    "active": true,
    "name": "my-api-key",
    "user_id": <userid>,
    "encoded_value": "<public key>"
  }
}

Reemplace por <userid> el identificador de usuario que recuperamos anteriormente.

Para <public key>, pegue el valor completo de la clave pública, incluido el BEGIN PUBLIC KEY texto y END PUBLIC KEY . No olvide reemplazar todos los saltos de línea por \n. Por ejemplo:

"encoded_value": "-----BEGIN PUBLIC KEY-----\nMIIBI....\n......\n-----END PUBLIC KEY-----"

Guarde el archivo JSON. En este ejemplo, hemos denominado el archivo my-public-key.json.

Registro de la clave pública

Ejecute el siguiente comando para registrar la clave pública:

curl -H 'Authorization: hbapi:123456:9999aa0000dd9:nym2' -H 'Content-Type: application/json' -X POST -d @my-public-key.json 'https://api.appnexus.com/public-key?user_id=<userid>'

Observe que usamos el mismo token en nuestra llamada al servicio de clave pública que usamos en nuestra llamada anterior al servicio de usuario.

Si la clave se registró correctamente, recibirá una respuesta similar a la siguiente:

{
    "response": {
        "status": "OK",
        "count": 1,
        "start": 0,
        "num_elements": 1,
        "debug_info": {
            "instance": "01.authentication-api.test1.nym2",
            "time": 475,
            "start_time": "2017-02-07T16:48:42.747Z",
            "version": "0.22.0",
            "request_id": "01.authentication-api.test1.nym2-1486486122747-0000000000000000000"
        },
        "public-key": {
            "active": true,
            "encoded_value": "-----BEGIN PUBLIC KEY-----\nMIIBI...\n...\n...\n-----END PUBLIC KEY-----",
            "name": "my-api-key",
            "user_id": 1234
        }
    }
    }

Create una firma JWT

Ejemplos de pseudocódigo del generador JWT

En los ejemplos siguientes se supone que el usuario ha establecido determinadas variables en información específica de la clave con la que se va a autenticar. Por ejemplo, la an_key_name variable usada para el kid encabezado en el código siguiente contiene el valor del "name" campo usado en el objeto JSON durante el registro de la clave pública con Xandr (consulte Register Your Public Key above). La username variable utilizada para el valor de sub encabezado se asignaría al nombre de usuario asociado a la clave, etc.

Ejemplo de Python

# Generates the JWT signature, using the PyJWT library
with open(priv_key_path, 'r') as f:
            cert = f.read()
jwt_signature = jwt.encode({
                'sub': username, 
                'iat': datetime.datetime.utcnow()
            }, 
            cert, 
            algorithm='RS256', 
            headers={
                'kid': an_key_name, 
                'alg': 'RS256', 
                "typ":"JWT"
            }
        )

Ejemplo de NodeJS

var jwt = require('jsonwebtoken');
var token = jwt.sign({ sub: username, iat: epoch_time }, cert, { algorithm: 'RS256', header: { kid: an_key_name, alg: 'RS256' }});

Autenticación con un JWT

Ahora es el momento de autenticarse mediante nuestra clave privada y el script de generación JWT. Ejecute un comando similar a este para crear el JWT y autenticarse:

curl -X POST -H 'Content-Type: text/plain' -d $(./<JWT generator>) https://api.appnexus.com/v2/auth/jwt

"Generador JWT" es el script que creó con una biblioteca JWT que genera el token. Hay un ejemplo de pseudocódigo anterior de lo que puede estar en este generador JWT. Puede ejecutar el script por separado y simplemente pasar el token en sí a este comando.

Esto devolverá una respuesta que contenga el nuevo token:

{
        "response": {
                "status": "OK",
                "token": "authn:184994:a1111111-6766-3b66-8544-f11111111ffd:lax1",
                "debug_info": {
                        "instance": "01.authentication-api.test1.lax1",
                        "time": 624,
                        "start_time": "2017-02-07T16:49:52.612Z",
                        "version": "0.22.0",
                        "request_id": "01.authentication-api.test102975.lax1-1486486192612-3065414328498075565"
                }
        }
        }

Uso del token

Ahora puede usar el token devuelto por la llamada JWT para autenticar todas las llamadas a la API. Por ejemplo, esta es la misma llamada al servicio de API de usuario mediante nuestro nuevo token:

curl -H 'Authorization: authn:184994:a1111111-6766-3b66-8546-f11111111ffd:lax1' 'https://api.appnexus.com/user?current'

Nueva sesión

Una vez que haya expirado la sesión, tendrá que volver a autenticarse. Pero a partir de este momento puede omitir todos los pasos de la sección anterior hasta Create un token JWT. Esto significa que para cada sesión, deberá crear un nuevo token JWT y usar ese token para autenticar el resto de las llamadas API. No tendrá que volver a usar la contraseña.

Desactivación de la clave pública

Puede quitar el acceso a la public-keyAPI desactivando . Para desactivar una clave, cree un archivo JSON como este:

{
        "public-key": {
        "active": false
    }
}

Como puede ver, este archivo simplemente establece el active campo falseen , lo que indica que public-key ya activeno es . Ejecute el siguiente comando para desactivar :public-key

curl -X PUT -H 'Authorization: authn:184994:a1111111-6766-3b66-8546-f11111111ffd:lax1' -H 'Content-Type: application/json' -d @pkdeactivate.json 'https://api.appnexus.com/public-key?key_id=2&user_id=1234'

En el comando, debe incluir el json con el active campo establecido false en (en este caso, hemos incluido ese JSON en el archivo pkdeactivate.json). También debe incluir y key_iduser_id en la cadena de consulta (public-key?key_id=2&user_id=1234).

Puede encontrar para key_ids un usuario con un comando simple GET :

curl -H 'Authorization: authn:184994:a1111111-6766-3b66-8546-f11111111ffd:lax1' 'https://api.appnexus.com/public-key?user_id=1234'

Puede reactivar fácilmente la clave con el mismo comando que usamos para desactivarla. Simplemente cambie el archivo JSON para establecerlo active en true.