マーケティングプラットフォームAPIでは、ユーザ毎の認証を行うためのAPIを提供しています。 これによりユーザの認証情報(ログインID／パスワード)の管理をマーケティングプラットフォームに委譲することができます。 ユーザ認証APIの対象ユーザは、マーケティングプラットフォームで管理しているユーザ(リード・管理者)です。 マーケティングプラットフォームのユーザ認証には有効期間がありますので、認証の有効性を確認するAPIを提供しています。 有効期間は、最終アクセス時間(認証ユーザトークンの発行、認証ユーザトークンのチェック、マーケティングプラットフォームへのアクセス)からシステム設定「ログインセッション有効期間(管理者)」「ログインセッション有効期間(リード)」で設定した時間（初期値は1時間）となります。
authapi.login
ユーザ認証APIの利用方法について説明します。
クライアントアプリケーションが マーケティングプラットフォーム認証API を利用するには、そのアプリケーションの認証が行われている必要があります。 アプリケーション認証についてはAPIメソッドリファレンス「クライアントアプリケーション認証API」を参照してください。
ここでは、クライアントアプリケーションの認証後に マーケティングプラットフォーム認証API を使用する場合の流れについて、シーケンス図を用いて解説します。
図2-1．クライアントアプリケーション認証後のシーケンス図
(1) 認証画面要求 ユーザは、クライアントアプリケーションの認証画面へアクセスします。 クライアントアプリケーションは 、マーケティングプラットフォームの認証API用ログインURLにマーケティングプラットフォームAPIキー(図2-1のapi_key)、コールバックURL(図2-1のcallback_url)、シグネチャ(図2-1のapi_sig)のパラメータを付加したリダイレクトURLを返します。 マーケティングプラットフォームの認証API用ログインURLは以下です。
https://{domainname}/public/authapi/login
実際に呼出しを行う際には、下記のようにします。
https://{domainname}/public/authapi/login?api_key=xxx&api_sig=xxx&callback_url=xxx
このログインURLでは、管理者とリードの両方を認証することが可能です。 また、リードと管理者のログインURLを分けることも可能です。 その場合、以下の２つのURLを使用します。
管理者用 : https://{domainname}/public/authapi/login/admin
リード用 : https://{domainname}/public/authapi/login/visitor
リダイレクトURLサンプル
https://sample.smartseminar.jp/public/authapi/login/admin?api_key=55b985f4994bf940b63f6bfb0aec3f70&callback_url=https://thirdparty.smartseminar.jp/cl/top&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99
※ 認証ログインキーにemailを使用している場合は、「管理者とリード共用」のログインURLは使用できません。 「管理者用」または「リード用」のログインURLを使用してください。 (認証ログインキーはマーケティングプラットフォームのシステム設定 [認証ログインキー]にて確認できます)
(2) マーケティングプラットフォームへの認証画面要求 (1)のリダイレクトURLにて マーケティングプラットフォームへリダイレクトされることで、ユーザに マーケティングプラットフォームの認証API用のログイン画面が表示されます。
(3)マーケティングプラットフォームへの認証要求 ユーザは マーケティングプラットフォームに登録済みのログインID(図2-1のlogin_id)、ログインパスワード(図2-1のlogin_password)を使用してログインします。 ログインに成功すると マーケティングプラットフォームはコールバックURLで指定されたURLに一時トークン(図2-1のauth_ttoken)パラメータを付加したリダイレクトURLを返します。
https://{callback_url}?auth_ttoken=xxxxxxxxxx
(4) 認証ユーザトークンの取得 クライアントアプリケーションは(3)にて受け取った一時トークンおよびクライアントアプリケーションの認証トークン(図2-1のtoken)を使用してマーケティングプラットフォームから認証ユーザトークンを取得します。 認証ユーザトークンの取得に成功した場合は、レスポンスXMLにユーザID(図2-1のuser_id)、ユーザタイプのID(図2-1のuser_type_id)、ユーザタイプ毎のID(管理者ID／リードID)(図2-1のuser_data_id)、認証ユーザトークン(図2-1のauth_token)が返ります。
詳細は、APIメソッドリファレンス「認証トークンAPI」を参照ください。
マーケティングプラットフォームが発行した一時トークンから認証ユーザトークンを取得するまでの有効期限は、発行からシステム設定「ログインセッション有効期間(管理者)」「ログインセッション有効期間(リード)」で設定した時間（初期値は1時間）です。 有効期限を過ぎた一時トークンは使用できませんのでその場合は再度取得する必要があります。
※「(2)認証画面要求」から「(4)認証後画面」の間に、認証に許諾するための許諾画面を表示することが可能です。許諾画面の表示有無は、マーケティングプラットフォームのシステム設定により設定できます。
(5) 認証後の機能の要求 ユーザは認証されたユーザ権限でクライアントアプリケーションの機能を使用します。
(6) ユーザが マーケティングプラットフォームで認証されているかのチェック クライアントアプリケーションはユーザが マーケティングプラットフォームで認証済みであることを確認します。 マーケティングプラットフォームAPIキー、(4)で取得した認証ユーザトークン、APIの認証トークン、シグネチャを付加して認証トークンチェックAPI(authinfo.getCheck)をコールします。 チェック結果として、成功(success)または失敗(failure)が返されます。
詳細は、APIメソッドリファレンス「認証ユーザトークンチェックAPI」を参照ください。
上述のとおり、ユーザー認証APIにおいては、ユーザーがログイン画面を使ってログインした後、予め指定されたコールバックURLへ下記のような形でauth_ttokenパラメータを付与してリダイレクトします。
https://{callback_url}?auth_ttoken=xxxxxxxxxx
この時に、業務用件によっては任意のパラメータを付与したいというケースがあることを想定し、マーケティングプラットフォームAPIでは、コールバック時に任意パラメータを受け取る方法を下記のように用意しています。
マーケティングプラットフォームへの認証画面要求時に、下記のようにします。
https://{domainname}/public/authapi/login?api_key=xxx&api_sig=xxx&callback_url=xxx¶m_returnpath=xxx¶m_somethingflag=xxx¶m_someaction=xxx
太字のように、param_ という接頭辞をつけて任意のパラメータを渡しておくと、コールバック時に下記のようにリダイレクトされます。
https://{callback_url}?auth_ttoken=xxx&returnpath=xxx&somethingflag=xxx&someaction=xxx
このように、コールバック時には接頭辞が外れた形で任意のパラメータが戻って来ます。