App Service 認証の API とランタイムのバージョンを管理する

[アーティクル]
11/20/2023

この記事では、App Service での組み込み認証と承認の API とランタイムのバージョンをカスタマイズする方法について説明します。

App Service 認証用の管理 API には、2 つのバージョンがあります。 Azure portal での "認証" エクスペリエンスには、V2 バージョンが必要です。 V1 の API が既に使用されているアプリは、いくつかの変更が行われた後に、V2 バージョンにアップグレードできます。具体的には、シークレット構成を、スロット固定のアプリケーション設定に移動する必要があります。これは、アプリのポータルの [認証] セクションから自動的に実行されるようにすることができます。

構成バージョンを更新する

警告

V2 に移行すると、Azure portal、Azure CLI、Azure PowerShell の既存のエクスペリエンスなど、一部のクライアントを介したアプリケーションに対する App Service の認証または承認機能の管理が無効になります。これを元に戻すことはできません。

V2 API では、V1 で行われていたように、個別のプロバイダーとして Microsoft アカウントを作成したり編集したりすることはできません。そうではなく、集約型 Microsoft ID プラットフォームを使用して、Microsoft Entra と個人用 Microsoft アカウントの両方でユーザーをサインインさせます。 V2 API に切り替えるときは、Microsoft ID プラットフォームプロバイダーを構成するために V1 の Microsoft Entra 構成が使用されます。 V1 Microsoft アカウントプロバイダーは移行プロセスで持ち越されて、引き続き通常どおり動作しますが、より新しい Microsoft ID プラットフォームモデルに移行するべきです。詳細については、「Microsoft アカウントプロバイダーの登録のサポート」を参照してください。

自動化された移行プロセスでは、プロバイダーのシークレットがアプリケーション設定内に移動され、構成の残りの部分は新しい形式に変換されます。自動移行を使用するには:

ポータル内でアプリに移動し、 [認証] メニューオプションを選択します。
アプリが V1 モデルを使用して構成されている場合は、[アップグレード] ボタンが表示されます。
確認プロンプトで説明を確認します。移行を実行する準備ができたら、プロンプトで [アップグレード] を選択します。

移行を手動で管理する

次の手順では、上記で説明した自動バージョンを使用しない場合に、アプリケーションを V2 API に手動で移行することができます。

シークレットをアプリケーション設定に移動

V1 API を使用して既存の構成を取得します。
```
az webapp auth show -g <group_name> -n <site_name>
```
結果の JSON ペイロードで、構成した各プロバイダーに使われるシークレット値を記録しておきます。
- Microsoft Entra: clientSecret
- Google: googleClientSecret
- Facebook: facebookAppSecret
- X: twitterConsumerSecret
- Microsoft アカウント: microsoftAccountClientSecret
重要

シークレット値は重要なセキュリティ資格情報であり、慎重に扱う必要があります。これらの値を共有したり、ローカルマシン上に保持したりしないでください。
各シークレット値のスロット固定アプリケーション設定を作成します。各アプリケーション設定の名前を選択できます。この値は、前の手順で取得した値と一致しているか、その値を使用して作成した Key Vault シークレットを参照している必要があります。

この設定を作成するには、Azure portal を使用するか、プロバイダーごとに次の方法を実行できます。
```
# For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
```
Note

この構成のアプリケーション設定はスロット固定としてマークする必要があります。つまり、それらは、スロットスワップ操作中に環境間を移動しません。これは、認証構成自体が環境に関連付けられているからです。
authsettings.json という名前で新しい JSON ファイルを作成します。前に受け取った出力を取得し、そこから各シークレット値を削除します。シークレットが含まれていないことを確認して、残りの出力をファイルに書き込みます。場合によっては、空の文字列を含む配列が構成に含まれていることがあります。 microsoftAccountOAuthScopes がそうでないことを確認し、そうである場合は、その値を null に切り替えます。

前の手順で作成した各プロバイダーのアプリケーション設定名を指すプロパティを authsettings.json に追加します。

Microsoft Entra: clientSecretSettingName
Google: googleClientSecretSettingName
Facebook: facebookAppSecretSettingName
X: twitterConsumerSecretSettingName
Microsoft アカウント: microsoftAccountClientSecretSettingName

この操作後のファイルの例は、次のようになります。このケースでは、Microsoft Entra ID 用の構成だけが行われています。

{
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

このファイルをアプリの新しい認証および承認構成として送信します。

az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

この後もアプリが想定どおりに動作していることを確認します。
前の手順で使用したファイルを削除します。

これで、ID プロバイダーのシークレットをアプリケーション設定として格納するためにアプリが移行されました。

Microsoft アカウントプロバイダーの登録のサポート

既存の構成に Microsoft アカウントプロバイダーが含まれており、Microsoft Entra プロバイダーが含まれていない場合は、構成を Microsoft Entra プロバイダーに切り替えた後に移行を実行できます。手順は次のとおりです。

Azure portal で [アプリの登録] に移動して、お使いの Microsoft アカウントプロバイダーに関連付けられている登録を見つけます。 [個人用アカウントからのアプリケーション] という見出しの下に表示されている場合があります。
その登録の [認証] ページに移動します。 [リダイレクト URI] の下に、末尾が /.auth/login/microsoftaccount/callback のエントリが表示されます。この URI をコピーします。
コピーしたものと一致する新しい URI を追加します。ただし、末尾は /.auth/login/aad/callback にする必要があります。これにより、App Service の認証および承認構成でこの登録を使用できるようになります。
アプリの App Service 認証および承認構成に移動します。
Microsoft アカウントプロバイダーの構成を収集します。
前の手順で収集したクライアント ID とクライアントシークレットの値を指定し、"詳細" 管理モードを使用して Microsoft Entra プロバイダーを構成します。発行者 URL には <authentication-endpoint>/<tenant-id>/v2.0 を使用し、<authentication-endpoint> をクラウド環境の認証エンドポイント (たとえば、グローバル Microsoft Entra ID の場合、"https://login.microsoftonline.com") に置き換え、さらに、<tenant-id> を ディレクトリ (テナント) ID に置き換えます。
構成を保存したら、ブラウザーでサイトの /.auth/login/aad エンドポイントに移動し、サインインフローを完了して、ログインフローをテストします。
この時点で、構成は正常にコピーされましたが、既存の Microsoft アカウントプロバイダーの構成はそのまま残っています。これを削除する前に、アプリのすべての部分が、ログインリンクなどを通して Microsoft Entra プロバイダーを参照していることを確認します。アプリのすべての部分が想定どおりに動作することを確認します。
これらが Microsoft Entra プロバイダーに対して機能することの検証が完了したら、Microsoft アカウントプロバイダーの構成を削除して構いません。

警告

Microsoft Entra アプリ登録のサポートされているアカウントの種類を変更することで、この 2 つの登録をまとめることが可能です。ただし、これにより、Microsoft アカウントユーザーに対して新しい同意プロンプトが強制され、それらのユーザーの ID 要求の構造が異なるものになる場合があります。特に、新しいアプリ ID が使用されてから、sub で値が変化します。この方法は、十分に理解している場合を除き、推奨されません。代わりに、V2 API でこの 2 つの登録に対するサポートが提供されるのを待つことをお勧めします。

V2 への切り替え

上記の手順を実行したら、Azure portal でアプリに移動します。 [認証 (プレビュー)] セクションを選択します。

または、サイトリソースの下にある config/authsettingsv2 リソースに対して PUT 要求を行うこともできます。ペイロードのスキーマは、ファイルベースの構成で取り込まれたものと同じです。

特定の認証ランタイムバージョンにアプリをピン留めする

認証と承認を有効にすると、機能の概要で説明されているように、プラットフォームミドルウェアが HTTP 要求パイプラインに挿入されます。このプラットフォームミドルウェアは、定期的なプラットフォームの更新の一環として、新機能と機能強化で定期的に更新されます。既定では、Web アプリまたは関数アプリは、このプラットフォームミドルウェアの最新バージョンで実行されます。これらの自動更新は、常に下位互換性があります。ただし、まれに、この自動更新によって Web アプリまたは関数アプリにランタイムの問題が発生することがあります。その場合は、以前のミドルウェアバージョンに一時的にロールバックすることができます。この記事では、特定のバージョンの認証ミドルウェアにアプリを一時的にピン留めする方法について説明します。

自動および手動でのバージョンの更新

アプリの runtimeVersion 設定を設定することで、プラットフォームミドルウェアの特定のバージョンにアプリをピン留めすることができます。特定のバージョンに明示的にピン留めし直さない限り、アプリは常に最新バージョンで実行されます。一度にサポートされるバージョンはいくつかあります。サポートされなくなった無効なバージョンにピン留めすると、アプリでは代わりに最新バージョンが使用されます。常に最新バージョンを実行するには、runtimeVersion を ~1 に設定します。

現在のランタイムバージョンの表示と更新

アプリで使用されるランタイムバージョンを変更できます。新しいランタイムバージョンは、アプリを再起動した後に有効になります。

現在のランタイムバージョンの表示

プラットフォーム認証ミドルウェアの現在のバージョンを表示するには、Azure CLI を使用するか、アプリ内にある組み込みバージョン HTTP エンドポイントのいずれか 1 つを経由します。

Azure CLI から

Azure CLI を使用して、az webapp auth show コマンドで現在のミドルウェアバージョンを表示します。

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

このコードでは、<my_app_name> をアプリの名前に置き換えます。また、<my_resource_group> をアプリのリソースグループの名前に置き換えます。

CLI の出力に runtimeVersion フィールドが表示されます。次の出力例のようになります。ここでは、わかりやすくするために抜粋されています。

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}

バージョンエンドポイントから

アプリで /.auth/version エンドポイントをクリックして、アプリが実行されている現在のミドルウェアバージョンを表示することもできます。次の出力例のようになります。

{
"version": "1.3.2"
}

現在のランタイムバージョンの更新

Azure CLI を使用すると、az webapp auth update コマンドでアプリの runtimeVersion 設定を更新できます。

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

<my_app_name> をご自分のアプリの名前に置き換えます。また、<my_resource_group> をアプリのリソースグループの名前に置き換えます。また、<version> を 1.x ランタイムの有効なバージョン、または最新バージョンの ~1 に置き換えます。さまざまなランタイムバージョンのリリースノートを参照して、ピン留めするバージョンの決定に役立ててください。

このコマンドは、上記のコードサンプルの [テスト] をクリックすることで、Azure Cloud Shell から実行できます。また、Azure CLI をローカルに使用して、az ログインを実行してサインインした後に、このコマンドを実行することもできます。

次のステップ

チュートリアル:エンドツーエンドでのユーザーの認証と承認

次の方法で共有

App Service 認証の API とランタイムのバージョンを管理する

構成バージョンを更新する

移行を手動で管理する

シークレットをアプリケーション設定に移動

Microsoft アカウントプロバイダーの登録のサポート

V2 への切り替え

特定の認証ランタイムバージョンにアプリをピン留めする

自動および手動でのバージョンの更新

現在のランタイムバージョンの表示と更新

現在のランタイムバージョンの表示

Azure CLI から

バージョンエンドポイントから

現在のランタイムバージョンの更新

次のステップ

フィードバック

その他のリソース

次の方法で共有

App Service 認証の API とランタイムのバージョンを管理する

構成バージョンを更新する

移行を手動で管理する

シークレットをアプリケーション設定に移動

Microsoft アカウント プロバイダーの登録のサポート

V2 への切り替え

特定の認証ランタイム バージョンにアプリをピン留めする

自動および手動でのバージョンの更新

現在のランタイム バージョンの表示と更新

現在のランタイム バージョンの表示

Azure CLI から

バージョン エンドポイントから

現在のランタイム バージョンの更新

次のステップ

フィードバック

その他のリソース

Microsoft アカウントプロバイダーの登録のサポート

特定の認証ランタイムバージョンにアプリをピン留めする

現在のランタイムバージョンの表示と更新

現在のランタイムバージョンの表示

バージョンエンドポイントから

現在のランタイムバージョンの更新