OpenID Connectによる認証

概要

OpenID Connect は、OAuth2.0の上位に位置するシンプルなIDプロトコルです。

Tapyrus APIでは外部のOpenID プロバイダーが提供する認証基盤を利用してTapyrus APIのユーザーを認証することができます。

ここではOpenID ConnectをTapyrus APIで使用するための設定やクライアントアプリケーションからのアクセス方法について説明します。

OpenID プロバイダー

OpenID Connect による認証を行うサービス提供者をOpenID プロバイダー(OP)といいます。主要なOPは以下の通りです。 Tapyrus APIでは利用するユーザーを識別するためにOPの認証基盤を利用することができます。

OIDC Provider	Issuer	Document
Google	https://accounts.google.com/	https://developers.google.com/identity/protocols/oauth2/openid-connect
Yahoo	https://api.login.yahoo.com/	https://developer.yahoo.com/oauth2/guide/
Microsoft	https://login.microsoftonline.com/{tenant}/v2.0	https://docs.microsoft.com/ja-jp/azure/active-directory/develop/v2-protocols-oidc

OPはOpenID Connect Discovery 1.0で定義されるディスカバリ・ドキュメントをサポートしている必要があります。

OpenID プロバイダーの設定

外部のOPを利用するための設定を行います。

Tapyrus API Dashboardにログイン後、メニューからOIDC 認証設定を選択します(下図)。

OIDC認証の設定画面ではOpenID Connectを利用してTapyrus APIに接続するためのOP側の設定を行います。各項目には外部OPから提供される値を設定してください。

• Issuer: 外部OPに接続するためのURL。ディスカバリ・ドキュメントは{Issuerの値}/.well-known/openid-configurationへアクセスすることにより取得できます。主なOPが提供するIssuerは前述の通りです。詳しくは各OPのドキュメントを参照してください。

• クライアントID: 外部OPから提供されるクライアントIDです。

• クライアントシークレット: 外部OPから提供されるクライアントシークレットです。

クライアントアプリケーションの設定

Tapyrus APIへアクセスするクライアントアプリケーションの登録を行います。 複数のクライアントアプリケーションを登録することができます。

Tapyrus API Dashboardにログイン後、メニューからクライアントアプリケーションを選択します(下図)。

新規作成画面では以下の項目を入力してクライアントアプリケーションを登録してください。

• アプリケーション名: クライアントアプリケーションの名称を128文字以内で設定してください。
• コールバックURL: クライアントアプリケーションがWebアプリケーションの場合は、認証成功後にリダイレクトするURLを設定してください。 クライアントアプリケーションがWebアプリケーションではない場合(例えば、モバイル端末のネイティブアプリケーション)はこの項目は必要ありません。

クライアントアプリケーションの登録後それぞれのアプリケーションにクライアントIDが一意に割り振られます。 このクライアントIDはクライアントアプリケーションがTapyrus APIに接続する際に必要となります。

クライアントアプリケーションからの利用

以下ではクライアントアプリケーションからOpenID Connectで認証してTapyrus APIを利用する方法について説明します。

認証には以下のステップが必要となります。

• OPへの認可リクエスト
• クライアントへの認可レスポンス
• アクセストークンの取得
• アクセストークンの使用

これら一連のステップを下図で示します。

OPへの認可リクエスト

OIDCによる認証プロセスを開始するにはTapyrus APIの認証エンドポイントに認可リクエストを送信する必要があります。

APIエンドポイント/oauth2/v1/authorize

パラメータとして以下が必要です。

• response_type: 常に code を指定します。
• client_id: クライアントアプリケーションの設定で登録されたクライアントID
• state: クライアントアプリケーションで生成された任意の文字列

Tapyrus APIはクライアントアプリケーションの認証要求を外部OPにリダイレクトします。 リダイレクト先は各OPのディスカバリードキュメントに記載されている認証エンドポイントです。 認証要求がリダイレクトされると外部OPの認証画面が表示されます。 ユーザーはこの認証画面でTapyrusAPIが必要としている権限を確認し、承認する必要があります。

クライアントへの認可レスポンス

外部OPで認証を行うとOPはTapyrus APIのへのコールバックを呼び出します。

APIエンドポイント/oauth2/v1/authorize/callback

Tapyrus APIは続けてクライアントアプリケーションへのコールバックを呼び出します。 この際のコールバックのURLは クライアントアプリケーションの設定で設定したものです。 Tapyrus APIからのコールバックには以下のパラメーターが含まれます。

• code: Tapyrus API が発行する認可コード。認可コードの有効期限は 10 分とし、１度利用された認可コードは無効になる。
• state: クライアントアプリから渡されたものをそのまま設定する。

アクセストークンの取得

コールバックを受信したクライアントアプリケーションはTapyrus APIに対して トークンリクエストを送信する必要があります。

APIエンドポイント/oauth2/v1/token

パラメーターとして以下が必要です。

• grant_type : 値はauthorization_code でなければいけません。
• code: Tapyrus API が発行した認可コード。コールバックで受信したものをそのまま設定します。
• client_id : クライアントアプリケーションの設定で登録されたクライアントID

Tapyrus APIは以下を含むJSON形式を応答として返します。

• access_token: ランダムに生成された文字列
• token_type: 常に bearer が返る

アクセストークンを使用してTapyrus APIにアクセスする

取得したaccess_tokenを使用して、Tapyurus APIが提供する機能にアクセスすることができます。

Tapyrus APIへのすべてのリクエストに対してHTTPヘッダに Authorization: Bearer <access_token> を設定してください。

サンプルコード

OpenID Connectによる認証を利用したクライアントアプリケーションのコードのサンプルはこちらからダウンロードできます。

• Tapyrus API Client Examples