Partager via

Authentification de l’API basée sur les jetons

Pour renforcer la sécurité de vos interactions avec l’API Digital Platform, nous avons implémenté un système d’authentification basé sur des jetons signés. Ce système utilise des jetons web JSON (JWT) pour garantir que vos sessions sont aussi sécurisées que possible. Suivez ces instructions et vous devez être opérationnel avec JWT en un rien de temps.

Remarque

Cette fonctionnalité est actuellement disponible pour tous les utilisateurs de l’API De plateforme numérique. Bien que l’authentification basée sur les jetons JWT offre une sécurité accrue, son utilisation est actuellement encouragée, mais pas obligatoire. Pour plus d’informations sur les processus d’authentification, consultez Service d’authentification .

Qu’est-ce que JWT ?

À partir du site web JWT :

« JSON Web Token (JWT) est une norme ouverte (RFC 7519) qui définit un moyen compact et autonome de transmettre en toute sécurité des informations entre les parties en tant qu’objet JSON. »

Xandr fournit des services d’API REST pour vous permettre de communiquer avec notre système par le biais de requêtes en ligne de commande et de fichiers JSON, et retourne des réponses sous la forme de JSON. L’implémentation d’une norme qui vous permet de transmettre ces informations en toute sécurité offre une meilleure protection de vos données et de l’ensemble du système de Xandr.

En outre, les jetons permettent une meilleure gestion des connexions utilisateur. Lorsque votre mot de passe expire, vous devez basculer immédiatement vers un nouveau mot de passe. Avec les jetons, vous pouvez avoir plusieurs jetons à la fois. Par conséquent, lorsqu’un jeton arrive à expiration, vous disposez d’une période de transition qui vous donne le temps de mettre à jour vos informations de connexion.

Bibliothèque JWT

Pour utiliser des jetons JWT, vous devez disposer d’un générateur de jetons. Vous pouvez générer des jetons JWT en utilisant l’une des nombreuses bibliothèques disponibles sur le site web JWT.

Préparation à l’utilisation des jetons

Avant de pouvoir utiliser des jetons, vous devez vous connecter à l’aide de votre mot de passe pour collecter des informations et configurer vos jetons dans le système de Xandr. Une fois votre jeton JWT inscrit, vous n’avez plus besoin de vous connecter à nouveau avec un mot de passe.

Commencez par authentifier et récupérer un jeton de connexion initial :

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

Le nom d’utilisateur et le mot de passe sont vos informations d’identification de connexion standard.

La réponse de cet appel comprend un jeton, qui ressemble à ceci :

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

Vous utiliserez ce jeton pour accéder au système jusqu’à ce que vous ayez inscrit votre clé publique (que nous allons créer dans un instant).

Ensuite, vous devez récupérer votre ID d’utilisateur. Récupérez votre ID d’utilisateur en appelant le service utilisateur :

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

En tant qu’utilisateur actuellement connecté, vous pouvez également utiliser cette commande pour rechercher votre ID :

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

Notez l’ID retourné. Vous l’utiliserez ultérieurement dans un fichier JSON pour configurer votre jeton.

Create clés privées et publiques

Remarque

Information

Network Administration est le rôle de plateforme requis pour créer une clé publique pour un compte donné.

Votre clé privée est utilisée pour signer vos demandes d’authentification. Une clé privée est censée être exactement celle-ci : privée. Vous ne souhaitez partager cette clé avec personne. Exécutez cette commande pour créer votre clé privée :

openssl genrsa -out my-api-key 2048
  • openssl : il s’agit de l’outil de commande qui crée un fichier contenant votre clé privée. Il implémente les protocoles Secure Sockets Layer et Transport Layer Security.
  • genrsa : commande qui indique à openssl de générer une clé privée. Cela utilise le système de chiffrement RSA.
  • -out my-api-key: placez la clé privée dans le fichier nommé my-api-key.
  • 2048: taille, en bits, de la clé privée. Si vous laissez ce nombre, la valeur par défaut est 512. Nous vous recommandons d’utiliser la 2048valeur .

Le my-api-key fichier remplacera votre mot de passe en tant que secret qui protège votre compte d’API.

Utilisez votre clé privée pour générer une clé publique :

openssl rsa -in my-api-key -pubout > my-api-key.pub
  • rsa : commande qui traite les clés RSA.
  • -in my-api-key: fichier contenant la clé privée à utiliser comme entrée pour créer la clé publique.
  • -pubout: cette option spécifie qu’une clé publique doit être sortie plutôt qu’une clé privée.
  • > my-api-key.pub: fichier qui contiendra votre clé publique.

Votre clé publique sera partagée avec l’API et sera utilisée pour vérifier que votre clé privée a été utilisée pour signer le JWT.

Remplacer les caractères de nouvelle ligne

Votre clé publique contient des sauts de ligne. Étant donné que cette clé sera envoyée à l’API dans le cadre d’une charge utile JSON, vous devez remplacer les sauts de ligne par des caractères de nouvelle ligne : \n. Vous pouvez effectuer cette opération manuellement, puis copier la clé dans votre fichier JSON, ou exécuter la commande suivante et copier la sortie :

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

Remarque

Selon votre environnement de ligne de commande, cela peut simplement afficher la touche avec des sauts de ligne plutôt que le caractère \n. Si cela se produit, vous devez entrer manuellement une \n pour remplacer chaque saut de ligne lorsque vous copiez la clé dans votre fichier JSON.

Create votre fichier JSON de clé publique

Create un fichier JSON comme suit :

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

Remplacez par <userid> l’ID utilisateur que nous avons récupéré précédemment.

Pour <public key>, collez la valeur complète de la clé publique, y compris le BEGIN PUBLIC KEY texte et END PUBLIC KEY . N’oubliez pas de remplacer tous les sauts de ligne par \n. Par exemple :

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

Enregistrez le fichier JSON. Pour cet exemple, nous avons nommé le fichier my-public-key.json.

Inscrire votre clé publique

Exécutez la commande suivante pour inscrire votre clé publique :

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>'

Notez que nous avons utilisé le même jeton dans notre appel au service à clé publique que dans notre appel précédent au service utilisateur.

Si votre clé a été correctement inscrite, vous recevrez une réponse similaire à celle-ci :

{
    "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 une signature JWT

Exemples de pseudo-code du générateur JWT

Les exemples ci-dessous supposent que l’utilisateur a défini certaines variables sur des informations spécifiques à la clé utilisée pour l’authentification. Par exemple, la an_key_name variable utilisée pour l’en-tête kid dans le code ci-dessous contiendrait la valeur du "name" champ utilisé dans l’objet JSON lors de l’inscription de la clé publique auprès de Xandr (voir Inscrire votre clé publique ci-dessus). La username variable utilisée pour la valeur d’en-tête sub est mappée au nom d’utilisateur associé à la clé, etc.

Exemple 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"
            }
        )

Exemple NodeJS

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

S’authentifier avec un JWT

Il est maintenant temps de vous authentifier à l’aide de notre clé privée et de votre script de génération JWT. Exécutez une commande similaire à celle-ci pour créer votre JWT et vous authentifier :

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

« Générateur JWT » est le script que vous avez créé avec une bibliothèque JWT qui génère le jeton. Il existe un exemple de pseudo-code ci-dessus de ce qui peut être dans ce générateur JWT. Vous pouvez exécuter votre script séparément et simplement passer le jeton lui-même à cette commande.

Cette opération retourne une réponse contenant votre nouveau jeton :

{
        "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"
                }
        }
        }

Utiliser votre jeton

Vous pouvez maintenant utiliser le jeton retourné par votre appel JWT pour authentifier tous les appels dans l’API. Par exemple, voici ce même appel au service d’API utilisateur à l’aide de notre nouveau jeton :

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

Nouvelle session

Une fois votre session expirée, vous devez vous authentifier à nouveau. Mais à partir de là, vous pouvez ignorer toutes les étapes de la section précédente jusqu’à Create un jeton JWT. Cela signifie que pour chaque session, vous devez créer un jeton JWT et utiliser ce jeton pour authentifier le reste de vos appels d’API. Vous n’aurez plus besoin d’utiliser votre mot de passe.

Désactiver votre clé publique

Vous pouvez supprimer l’accès à l’API en désactivant .public-key Pour désactiver une clé, créez un fichier JSON comme suit :

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

Comme vous pouvez le voir, ce fichier définit simplement le active champ sur false, ce qui indique que n’est public-key plus active. Exécutez la commande suivante pour désactiver :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'

Dans la commande , vous devez inclure le json avec le active champ défini false sur (dans ce cas, nous avons inclus ce JSON dans le fichier pkdeactivate.json). Vous devez également inclure et key_id dans user_id la chaîne de requête (public-key?key_id=2&user_id=1234).

Vous pouvez trouver le key_ids pour un utilisateur à l’aide d’une commande simple GET :

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

Vous pouvez facilement réactiver la clé avec la même commande que celle utilisée pour la désactiver. Modifiez simplement le JSON pour définir active sur true.