ユーザーの登録と成果物のサブスクリプションを委任する方法

[アーティクル]
01/10/2024

適用対象: Developer | Basic | Standard | Premium

委任することで、ご自身の Web サイトでユーザーデータを保持し、カスタム検証を実行できます。委任によって、開発者のサインインまたはサインアップ (および関連アカウントの管理操作) と製品のサブスクリプションを、開発者ポータルの組み込みの機能ではなく、お使いの既存の Web サイトを使用して処理することができます。

開発者のサインインまたはサインアップと開発者アカウントの管理オプションを既存の Web サイトに委任するには、サイト上で特殊な委任エンドポイントを作成します。この特殊な委任は、API Management 開発者ポータルから開始されたサインインまたはサインアップと、関連する要求のエントリポイントとして機能します。

最終的なワークフローは次のようになります。

開発者が、API Management 開発者ポータルのサインインまたはサインアップリンク、またはアカウント管理リンクをクリックします。
ブラウザーが委任エンドポイントにリダイレクトされます。
次に、委任エンドポイントにより、ユーザーがサインインまたはサインアップ UI、またはアカウント管理 UI にリダイレクトされるか、ユーザーにそれらの UI が表示されます。
操作が完了すると、ユーザーは API Management 開発者ポータルの最後にアクセスした場所にリダイレクトされます。

委任エンドポイント経由で要求をルーティングするように API Management を設定する

Azure portal 内で、API Management リソース内で開発者ポータルを検索します。
[委任] 項目をクリックします。
チェックボックスをクリックして、サインインおよびサインアップの委任を有効にします。
特殊な委任エンドポイントの URL を決めて、 [委任エンドポイント URL] フィールドに入力します。
[委任の認証キー] フィールドで、次のいずれかを行います。
- 要求が API Management から送信されたものかをどうかを確かめるための署名のコンピューティングに使用するシークレットを入力します。
- API Management の [生成] ボタンをクリックします。これによりランダムキーが生成されます。
[保存] をクリックします。

委任エンドポイントを作成する

ご自身のサイト上で実装する新しい委任エンドポイントを作成するには、次の手順をお勧めします。

操作に応じて次の形式で要求を受信します。

http://www.yourwebsite.com/apimdelegation?operation={operation}&returnUrl={元のページの URL}&salt={文字列}&sig={文字列}

-または-

http://www.yourwebsite.com/apimdelegation?operation={operation}&userId={アカウントのユーザー ID}&salt={文字列}&sig={文字列}

クエリパラメーター:

パラメーター	説明
operation	委任要求の種類を特定します。使用できる操作: SignIn、SignUp、ChangePassword、ChangeProfile、CloseAccount、SignOut。
returnUrl	SignIn または SignUp 時、ユーザーがサインインまたはサインアップリンクをクリックした場所の URL。
userId	ChangePassword、ChangeProfile、CloseAccount、SignOut 時、管理するアカウントのユーザー ID。
salt	セキュリティハッシュの計算に使用される特殊な salt 文字列。
sig	自分で計算したハッシュとの比較に使用された、計算によって求められたセキュリティハッシュ。

要求の送信元が Azure API Management であることを確認します (省略できますが、セキュリティ上強く推奨されます)。
- returnUrl (または UserId) および salt クエリパラメータに基づいて、文字列の HMAC-SHA512 ハッシュを計算します。例については、コード例を参照してください。
  
  SignIn および SignUp の場合:
```
HMAC(salt + '\n' + returnUrl)
```
  ChangePassword、ChangeProfile、CloseAccount、SignOut の場合:
```
HMAC(salt + '\n' + userId)
```
- 上の計算によって求められたハッシュを sig クエリパラメーターの値と比較します。 2 つのハッシュ値が等しい場合は、次の手順に移動します。それ以外の場合は、要求を拒否します。
サインインまたはサインアップの要求、またはアカウント管理操作の要求を受け取っていることを確認します。
サインインまたはサインアップ UI、またはアカウント管理 UI をユーザーに表示します。
お客様の側で操作が完了したら、API Management でユーザーを管理します。たとえば、ユーザーがサインアップすると、ユーザーの対応するアカウントを API Management 内に作成します。
- ユーザーを作成します。
- ユーザー ID は、ユーザーストア内のユーザー ID と同じ値、または追跡しやすい ID に設定してください。
ユーザーがサインインまたはサインアップ後、正常に認証された場合、次の操作を行います。
- API Management REST API を使用して、共有アクセストークンを要求します。
- 上記の API 呼び出しによって受け取った SSO URL に returnUrl クエリパラメーターを付加します。次に例を示します。
  
  https://contoso.developer.azure-api.net/signin-sso?token=<URL-encoded token>&returnUrl=%2Freturn%2Furl
- 上で生成された URL にユーザーをリダイレクトします。

製品のサブスクリプション処理の委任

製品のサブスクリプション処理を委任するしくみは、ユーザーのサインイン/サインアップ処理の委任と似ています。最終的なワークフローは次のようになります。

開発者が API Management 開発者ポータルで製品を選択し、 [サブスクライブ] ボタンをクリックします。
ブラウザーが委任エンドポイントにリダイレクトされます。
委任エンドポイントで、必要な製品のサブスクリプション手順が実行されます。この手順の設計は、お客様に任されています。これには次が含まれます。
- 別のページへのリダイレクトして課金情報を要求する。
- 追加の質問を行う。
- 情報を保存するだけでユーザーのアクションを求めない。

API Management 機能を有効にする

[委任] ページで [製品のサブスクリプションの委任] をクリックします。

委任エンドポイントを作成する

ご自身のサイト上で実装する新しい委任エンドポイントを作成するには、次の手順をお勧めします。

操作に応じて次の形式で要求を受信します。

http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={サブスクライブする成果物}&userId={要求元のユーザー}&salt={文字列}&sig={文字列}

-または-

http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={管理対象のサブスクリプション}&salt={文字列}&sig={文字列}

クエリパラメーター:

パラメーター	説明
operation	委任要求の種類を特定します。有効な製品サブスクリプション要求のオプションを次に示します。 Subscribe: 提供された ID (以下を参照) を持つ特定の製品をユーザーがサブスクライブするための要求。登録を解除: ユーザーの製品のサブスクリプションを解除するための要求
productId	"サブスクライブ" 時、ユーザーがサブスクリプションを要求した製品の ID。
userId	"サブスクライブ" 時の要求側ユーザーの ID。
subscriptionId	[登録を解除] で、製品のサブスクリプション ID。
salt	セキュリティハッシュの計算に使用される特殊な salt 文字列。
sig	自分で計算したハッシュとの比較に使用された、計算によって求められたセキュリティハッシュ。

要求の送信元が Azure API Management であることを確認します (省略できますが、セキュリティ上強く推奨されます)。
- productId、userId (または subscriptionId)、salt クエリパラメータに基づいて、文字列の HMAC-SHA512 ハッシュを計算します。
  
  Subscribe の場合:
```
HMAC(salt + '\n' + productId + '\n' + userId)
```
  [登録を解除] の場合:
```
HMAC(salt + '\n' + subscriptionId)
```
- 上の計算によって求められたハッシュを sig クエリパラメーターの値と比較します。 2 つのハッシュ値が等しい場合は、次の手順に移動します。それ以外の場合は、要求を拒否します。
operation で要求された操作の種類 (課金、追加の質問など) に基づいて、製品のサブスクリプションを処理します。
お客様の側で操作が完了したら、API Management でサブスクリプションを管理します。たとえば、サブスクリプションのための REST API を呼び出して、API Management 製品にユーザーをサブスクライブします。

コード例

これらのコードサンプルは、ユーザーのサインインまたはサインアップを委任する際に returnUrl クエリパラメータのハッシュを生成する方法を示しています。 returnUrl は、ユーザーがサインインまたはサインアップリンクをクリックしたページの URL です。

"委任検証キー" を取得する。このキーは、Azure ポータルの [委任] 画面で設定されます。
HMAC を作成する。この HMAC は、署名の検証のために使用されます。これにより、渡された returnUrl の有効性が証明されます。

他のハッシュを計算する場合も、同じコードを多少変更して使用することができます。たとえば、製品サブスクリプションを委任する場合は、productId と userId を使用します。

returnUrl のハッシュを生成する C# のコード

using System.Security.Cryptography;

string key = "delegation validation key";
string returnUrl = "returnUrl query parameter";
string salt = "salt query parameter";
string signature;
using (var encoder = new HMACSHA512(Convert.FromBase64String(key)))
{
    signature = Convert.ToBase64String(encoder.ComputeHash(Encoding.UTF8.GetBytes(salt + "\n" + returnUrl)));
    // change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
    // compare signature to sig query parameter
}

returnUrl のハッシュを生成する NodeJS のコード

var crypto = require('crypto');

var key = 'delegation validation key'; 
var returnUrl = 'returnUrl query parameter';
var salt = 'salt query parameter';

var hmac = crypto.createHmac('sha512', new Buffer(key, 'base64'));
var digest = hmac.update(salt + '\n' + returnUrl).digest();
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter

var signature = digest.toString('base64');

重要

委任変更を有効にするには、開発者ポータルを再発行する必要があります。

次のステップ

開発者ポータルの詳細を確認する。
Microsoft Entra ID または Azure AD B2C を使用して認証します。
開発者ポータルに関する質問が他にある場合は、 FAQ で回答を確認する。

ユーザーの登録と成果物のサブスクリプションを委任する方法

開発者のサインインおよびサインアップ処理の委任

委任エンドポイント経由で要求をルーティングするように API Management を設定する

委任エンドポイントを作成する

製品のサブスクリプション処理の委任

API Management 機能を有効にする

委任エンドポイントを作成する

コード例

returnUrl のハッシュを生成する C# のコード

returnUrl のハッシュを生成する NodeJS のコード

次のステップ

その他のリソース