コンテンツにスキップ

サーバ間認証方式

このページでは、API を利用するためのサーバ間認証方式について説明します。

Info

本開発へ入るパートナー様向けの内容です。APIをお試しで利用したい場合、Avatar Play 担当者からお試し用のAPIキーを入手して利用できます。

概要

Avatar Play の API は、Google Cloud Platform(以下、GCP) の APIキーとサービスアカウントを使った認証方式を採用しています。GCPの認証方式については、認証概要を参照ください。

API へアクセスする際は、APIキーの指定を必須としています。APIキーは、エンドポイントにパラメータ指定するだけで利用でき、すべてのAPIへアクセスできますが、セキュリティ上安全とはみなされません。商用サービスで利用する際は、APIキーにIPアドレス制限を加えるか、サービスアカウントを使った認証方式を採用する必要があります。

APIキーの入手

事前のセットアップ

  1. GCPプロジェクトを作成します。APIキーやサービスアカウントのみの利用の場合、課金の設定は不要です。
  2. API へのアクセス権持つユーザーが所属するGoogleグループを作成します。

以下の情報を Avatar Play 担当者へ伝えます。

  • GCPプロジェクトのプロジェクト番号 (GCPコンソールのダッシュボードのプロジェクト情報から確認できます)
  • Googleグループのメールアドレス

APIキーの作成

DeNA側のセットアップが完了すると、次のステップに進めます。

  1. GCPコンソールの「APIとサービス」より、「API と サービスを有効化」ボタンを押し、APIライブラリを開きます。
  2. 「Avatar Play API」を検索し、選択します。
  3. 提供元が dena.jp であることを確認し、APIを有効化します。
  4. GCPコンソールの「APIとサービス > 認証情報」より、認証情報を作成します。このとき、「APIキー」を選択します。

これで APIキーを利用できるようになります。「API の制限」より、用途を Avatar Play API のみに制限しておくことが好ましいです。

APIキーを使って Echo API へアクセスできるか確認します。エラーが返されなければ成功です。

$ curl "https://api.avatarplay3d.com/avatar/v1/Echo?key={APIキー}&message=hello"
{
 "message": "hello"
}

APIキーで認証する

Info

サービスアカウントを使った認証を利用する場合は読み飛ばしてください。

APIキーが有効になっただけでは Echo 以外の API はまだ利用できません。後述のサービスアカウントを利用せず APIキーのみで API を利用する場合、APIキーの認証設定が必要になります。これは、開発初期を APIキーのみの認証で進めたい場合にも有効です。

APIキーをSHA256でハッシュ化した文字列を、Avatar Play 担当者へ伝えます。Mac OSで生成する例を示します。

$ echo -n {APIキー} | shasum -a 256
854834d71cfb50b614d34863a601fc22375c0c39b477bbb83e63105f1863280a  -

DeNA側でのセットアップが完了すると、すべてのAPIへアクセスできるようになります。

APIキーの利用にIPアドレス制限を加える

APIキーの利用にIPアドレス制限を加えることで、利用元となるアプリケーションを制限できます。設定はGCPコンソールの「APIとサービス > 認証情報」から行えます。サービスアカウントの認証を利用しない場合はIPアドレス制限を加えることを強く推奨します。

サービスアカウントで認証する

サービスアカウントの作成

GCPコンソールより API アクセス用のサービスアカウントを作成し、サービスアカウントのメールアドレスを Avatar Play 担当者へ伝えます。

JWTの作成と送信

DeNA側でのセットアップ作業が完了すると、サービスアカウントを使った認証が有効になります。GCPコンソールよりサービスアカウントの秘密鍵を作成し、それを使って署名したJWTを Authorization ヘッダに設定して API へアクセスします。実装例はGCPのドキュメント「認証されたリクエストを Endpoints API に送信する」を参照してください。パラメータ aud には、Avatar Play が発行したアプリIDを指定します。

APIのエンドポイントは、 /avatar のパスを /secure に置き換えたエンドポイントを利用します。

$ curl "https://api.avatarplay3d.com/secure/v1/Echo?key={APIキー}&message=hello" -H "Authorization: Bearer {JWT}"
{
 "message": "hello"
}

最終更新日: 2019-10-21

最終更新日: 2019-10-21