IBM Marketing Software API のセキュリティー・フレームワーク
Marketing Platform は、IBM® Marketing Software 製品によって実装される API のセキュリティー・フレームワークを提供します。
ページの構成プロパティーのセットにより、開発者は IBM Marketing Software 製品によって提供されている API の以下のセキュリティーを設定することができます。
- 特定の製品 API では、製品へのアクセスをブロックすることができます。
- 特定の製品 API では、指定された API と製品の間の通信に HTTPS を要求することができます。
- 特定の製品 API では、指定された API と製品の間の通信に認証を要求することができます。
API セキュリティーを制御する構成プロパティーは、IBM Marketing Platform | セキュリティー | API 管理カテゴリーの下にあります。各製品には、製品ごとに提供されている API の新規セキュリティー設定を作成するために使用できる構成プロパティーのテンプレートがあります。
API のセキュリティー設定は、単体テストまたはデプロイメントごと、または API のライフサイクル全体で、必要に応じて設定および変更することができます。
セキュリティー・フレームワークは現在、Campaign の API のみをサポートしています。
Marketing Platform セキュリティー・フレームワークでは、保護された API にアクセスするために次の 2 つの認証オプションをサポートしています。使用環境に応じていずれかを使用できます。
- Marketing Platform に登録されている内部ユーザーは、セキュア・トークンを取得するために各自の Marketing Platform ログイン資格情報を使用して認証できます。
- Marketing Platform で使用するようにセットアップしたフェデレーションに含まれる外部ユーザーは、ID プロバイダー・サーバーを介して認証できます。
Marketing Platform ログイン API を使用した内部ユーザー認証
クライアント・アプリケーションで内部ユーザーを認証するには、Marketing Platform login API を使用して、セキュア・トークンを生成します。その後、API 自体で必要なパラメーターに加えて、要求ヘッダーに必要なパラメーターを渡すことにより、保護された API を呼び出すことができます。
セキュリティー・フィルターは、処理を行うために、保護された要求を代行受信、妥当性検査、およびパススルーします。
Marketing Platform ユーザーが認証された後、Marketing Platform セキュリティー・フィルターは、処理のために製品に渡す前に、USER_NAME_STRING キーの属性としてユーザーのログイン名を要求に追加します。
セキュア・トークンには、15 秒というデフォルトのライフ・スパンがあります。トークンのライフ・スパンが満了した後、保護された API を呼び出すためにそのトークンを使用することはできなくなります。ユーザーに対して Marketing Platform login API が呼び出されるたびに、そのユーザーの以前のセキュリティー・トークンはすべて無効になります。
全般 | その他カテゴリーの下のページにある「トークンの存続時間」プロパティーの値を設定することにより、セキュア・トークンのライフ・スパンを変更することができます。
URL の例
http[s]://host:port/unica/api/manager/authentication/login/
ヘッダー・パラメーター
| パラメーター | 説明 |
|---|---|
| m_user_name | 内部ユーザーの Marketing Platform ログイン名。 |
| m_user_password | プレーン・テキストでの内部ユーザーの Marketing Platform パスワード。 |
レスポンス
ログインに成功すると、応答 HTTP 200 が以下の JSON データとともに返されます。
- m_tokenId - ランダムに生成されるトークン
- m_user_name - ログイン・ユーザーのユーザー名
- createDate - 以下の例で示されている形式のタイム・スタンプ (タイム・ゾーンは IST)。
Mon Jul 06 18:23:35 IST 2015
正しくない資格情報によってログインに失敗すると、応答 HTTP 401 (無許可) が返されます。ブロックされるよう login API が構成されている場合、応答 403 (禁止) が返されます。HTTPS を使用するよう login API が構成されている場合に HTTP で呼び出されると、応答 403 (禁止) が返されます。
内部ユーザーをログアウトするには、Marketing Platform logout API を使用します。
Marketing Platform ログアウト API による内部ユーザーのログアウト
Marketing Platform logout API を使用して、内部ユーザーをログアウトし、セキュア・トークンを削除します。
logout API はデフォルトで保護されています。事前定義キーに対する要求ヘッダーには、認証パラメーターが必要です。
URL の例
http[s]://host:port/unica/api/manager/authentication/logout/
ヘッダー・パラメーター
| パラメーター | 説明 |
|---|---|
| m_user_name | 内部ユーザーの Marketing Platform ログイン名。 |
| m_tokenId | 認証によって入手されるセキュア・トークン。 |
| api_auth_mode | 内部ユーザーに対して値 manager を使用します。 |
レスポンス
認証に成功すると、応答 HTTP 200 が返され、セキュア・トークンが削除されます。応答が HTTP 200 である場合、クライアント・アプリケーションによってログアウトが確認されます。
認証に失敗すると、応答 HTTP 401 が返されます。
フェデレーションによる外部ユーザー認証とログアウト
サポートされているフェデレーションと Marketing Platform が統合されると、ユーザーは自分のシステムにログインすることが可能になり、クライアント・アプリケーションは Marketing Platform によって提供される ID プロバイダー (IdP) サーバーを介してトークンを取得します。
フェデレーテッド・ユーザーを認証した後、対応する Marketing Platform ログイン名が USER_NAME_STRING キーの属性として要求に追加されます。
IdP サーバーでログアウトを行う必要があります。
ヘッダー・パラメーター
以下の表では、Marketing Platform によって提供される IdP サーバーを介して認証するときに使用するヘッダー・パラメーターについて説明しています。
| パラメーター | 説明 |
|---|---|
| f_userId | フェデレーションでのユーザー ID。 |
| f_clientId | フェデレーションでのクライアント ID。 |
| f_spId | フェデレーションでのサービス・プロバイダー ID。 |
| f_tokenId | IdP サーバーからのシングル・サインオン・トークン。 |
| api_auth_mode | フェデレーテッド認証に対して値 fsso を使用します。 |
レスポンス
応答は HTTP 200 です。これに加えて、API に応じた追加の項目が返されます。