トークンベースの API 認証

[アーティクル]
02/26/2024

Digital Platform API との対話のセキュリティを強化するために、署名付きトークンベースの認証システムを実装しました。このシステムでは、JSON Web トークン (JWT) を使用して、セッションが可能な限り安全であることを確認します。これらの手順に従うと、JWT で短時間で稼働できるようになります。

注:

この機能は現在、Digital Platform API のすべてのユーザーが使用できます。 JWT トークンベースの認証ではセキュリティが強化されますが、現時点では、その使用が推奨されますが、必須ではありません。認証プロセスの詳細については、「 Authentication Service 」を参照してください。

JWT とは

JWT Web サイトから:

"JSON Web トークン (JWT) はオープン標準 (RFC 7519) であり、関係者間の情報を JSON オブジェクトとして安全に送信するためのコンパクトで自己完結型の方法を定義します。

Xandr は、コマンドラインクエリと JSON ファイルを介してシステムと通信できるように REST API サービスを提供し、JSON の形式で応答を返します。この情報を安全に送信できる標準を実装すると、データと Xandr のシステム全体の保護が強化されます。

さらに、トークンを使用すると、ユーザーログインをより適切に管理できます。パスワードの有効期限が切れた場合は、すぐに新しいパスワードに切り替える必要があります。トークンを使用すると、一度に複数のトークンを使用できるため、トークンの有効期限が近づくと、ログイン情報を更新する時間を与える切り替え期間が与えられます。

JWT ライブラリ

JWT トークンを使用するには、トークンジェネレーターが必要です。 JWT Web サイトで利用できる多数のライブラリのいずれかを利用することで、JWT トークンを生成できます。

トークンを使用する準備

トークンを使用する前に、パスワードを使用してログインして情報を収集し、Xandr のシステムでトークンを設定する必要があります。 JWT トークンが登録されたら、パスワードで再度ログインする必要はありません。

最初のログイントークンを認証して取得することから始めます。

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

ユーザー名とパスワードは、標準のログイン資格情報です。

この呼び出しからの応答には、次のようなトークンが含まれます。

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

公開キーを登録するまで、このトークンを使用してシステムにアクセスします (すぐに作成します)。

次に、ユーザー ID を取得する必要があります。ユーザーサービスを呼び出してユーザー ID を取得します。

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

現在ログオンしているユーザーは、次のコマンドを使用して ID を見つけることもできます。

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

返される ID を書き留めます。これは後で JSON ファイルで使用してトークンを設定します。

秘密キーと公開キーを作成する

注:

Information

ネットワーク管理は、特定のアカウントの公開キーを作成するために必要なプラットフォームロールです。

秘密キーは、認証要求に署名するために使用されます。秘密キーは、まさにプライベートを意味します。このキーを他のユーザーと共有する必要はありません。次のコマンドを実行して、秘密キーを作成します。

openssl genrsa -out my-api-key 2048

openssl: これは、秘密キーを含むファイルを作成するコマンドツールです。 Secure Sockets レイヤーとトランスポート層セキュリティプロトコルを実装します。
genrsa: 秘密キーを生成するように openssl に指示するコマンド。これにより、RSA 暗号化システムが使用されます。
-out my-api-key: 秘密キーをという名前 my-api-keyのファイルに配置します。
2048: 秘密キーのサイズ (ビット単位)。この数値をオフのままにした場合、既定値はです 512。の値 2048をお勧めします。

ファイルは my-api-key 、パスワードを API アカウントを保護するシークレットとして置き換えられます。

秘密キーを使用して公開キーを生成します。

openssl rsa -in my-api-key -pubout > my-api-key.pub

rsa: RSA キーを処理するコマンド。
-in my-api-key: 公開キーを作成するための入力として使用する秘密キーを含むファイル。
-pubout: このオプションは、公開キーが秘密キーではなく出力されるように指定します。
>my-api-key.pub: 公開キーを保持するファイル。

公開キーは API と共有され、秘密キーが JWT の署名に使用されたことを確認するために使用されます。

改行文字を置き換える

公開キーに改行が含まれています。このキーは JSON ペイロードの一部として API に送信されるため、改行を改行文字 (\n) に置き換える必要があります。手動でこれを行い、キーを JSON ファイルにコピーするか、次のコマンドを実行して出力をコピーできます。

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

注:

コマンドライン環境によっては、\n 文字ではなく改行でキーが表示される場合があります。その場合は、キーを JSON ファイルにコピーするときに、改行ごとに置き換える \n を手動で入力する必要があります。

公開キー JSON ファイルを作成する

次のような JSON ファイルを作成します。

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

を、先ほど取得したユーザー ID に置き換えます <userid> 。

の場合<public key>は、と END PUBLIC KEY テキストを含む公開キーの完全な値をBEGIN PUBLIC KEY貼り付けます。すべての改行を \n に置き換えてください。例:

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

JSON ファイルを保存します。この例では、ファイル my-public-key.jsonにという名前を付けました。

公開キーを登録する

次のコマンドを実行して公開キーを登録します。

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

公開キーサービスの呼び出しで、以前のユーザーサービスの呼び出しで使用したのと同じトークンが使用されていることに注意してください。

キーが正常に登録された場合は、次のような応答を受け取ります。

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

JWT 署名を作成する

JWT ジェネレーターの擬似コードの例

次の例では、ユーザーが認証に使用されるキーに固有の情報に特定の変数を設定していることを前提としています。たとえば、次の an_key_name コードのヘッダーに使用される kid 変数は、Xandr での公開キーの "name" 登録中に JSON オブジェクトで使用されるフィールドの値を保持します (上記の「公開キーの登録」を参照してください)。ヘッダー値にsub使用される変数はusername、キーなどに関連付けられているユーザー名にマップされます。

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

NodeJS の例

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

JWT で認証する

ここで、秘密キーと JWT 生成スクリプトを使用して認証します。次のようなコマンドを実行して JWT を作成し、認証します。

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

"JWT ジェネレーター" は、トークンを生成する JWT ライブラリを使用して作成したスクリプトです。この JWT ジェネレーターには、上記の擬似コードの例があります。スクリプトを個別に実行し、トークン自体をこのコマンドに渡すだけです。

これにより、新しいトークンを含む応答が返されます。

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

トークンを使用する

JWT 呼び出しから返されたトークンを使用して、API へのすべての呼び出しを認証できるようになりました。たとえば、新しいトークンを使用してユーザー API サービスを呼び出すのと同じ例を次に示します。

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

新しいセッション

セッションの有効期限が切れた後、もう一度認証する必要があります。ただし、この時点から、前のセクションのすべての手順を「JWT トークンの作成」までスキップできます。つまり、セッションごとに新しい JWT トークンを作成し、そのトークンを使用して残りの API 呼び出しを認証する必要があります。パスワードを再度使用する必要はありません。

公開キーを非アクティブ化する

API アクセスを削除する場合は、 public-keyを非アクティブ化します。キーを非アクティブ化するには、次のような JSON ファイルを作成します。

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

ご覧のとおり、このファイルはフィールドを active にfalse設定するだけです。これは、がでなくなったactiveことをpublic-key示しています。次のコマンドを実行して、を非アクティブ化します 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'

コマンドでは、フィールドがにfalse設定された JSON active を含める必要があります (この場合、その JSON はファイルpkdeactivate.jsonに含まれています)。とをクエリ文字列 (public-key?key_id=2&user_id=1234) に含めるkey_iduser_id必要もあります。

簡単なGETコマンドをkey_ids使用して、ユーザーのを検索できます。

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

キーを非アクティブ化するために使用したのと同じコマンドを使用して、キーを簡単に再アクティブ化できます。 JSON をに設定activetrueするように変更するだけです。

次の方法で共有