Azure App Service 上での認証と承認の高度な使用方法Advanced usage of authentication and authorization in Azure App Service

この記事では、App Service 上で組み込みの認証と承認をカスタマイズする方法と、アプリケーションから ID を管理する方法について説明します。This article shows you how to customize the built-in authentication and authorization in App Service, and to manage identity from your application.

すぐに開始するには、以下のチュートリアルのいずれかをご覧ください。To get started quickly, see one of the following tutorials:

複数のサインイン プロバイダーを使用するUse multiple sign-in providers

ポータル構成では、ユーザーに複数 (Facebook と Twitter の両方など) のサインイン プロバイダーを表示するターンキー手法は提供されません。The portal configuration doesn't offer a turn-key way to present multiple sign-in providers to your users (such as both Facebook and Twitter). ただし、この機能をアプリに追加することは難しくありません。However, it isn't difficult to add the functionality to your app. 手順の概要は次のとおりです。The steps are outlined as follows:

最初に、Azure Portal の [認証/承認] ページで、有効にする各 ID プロバイダーを構成します。First, in the Authentication / Authorization page in the Azure portal, configure each of the identity provider you want to enable.

[要求が認証されない場合に実行するアクション] で、 [匿名要求を許可する (操作不要)] を選択します。In Action to take when request is not authenticated, select Allow Anonymous requests (no action).

サインイン ページ、ナビゲーション バー、またはアプリのその他の任意の場所で、有効にした各プロバイダーへのサインイン リンク (/.auth/login/<provider>) を追加します。In the sign-in page, or the navigation bar, or any other location of your app, add a sign-in link to each of the providers you enabled (/.auth/login/<provider>). 次に例を示します。For example:

<a href="/.auth/login/aad">Log in with the Microsoft Identity Platform</a>
<a href="/.auth/login/facebook">Log in with Facebook</a>
<a href="/.auth/login/google">Log in with Google</a>
<a href="/.auth/login/twitter">Log in with Twitter</a>
<a href="/.auth/login/apple">Log in with Apple</a>

ユーザーがいずれかのリンクをクリックすると、それぞれのサインイン ページが開き、ユーザーがサインインできます。When the user clicks on one of the links, the respective sign-in page opens to sign in the user.

サインイン後のユーザーをカスタム URL にリダイレクトさせるには、post_login_redirect_url クエリ文字列パラメーターを使用します (ご利用の ID プロバイダーの構成におけるリダイレクト URI と混同しないでください)。To redirect the user post-sign-in to a custom URL, use the post_login_redirect_url query string parameter (not to be confused with the Redirect URI in your identity provider configuration). たとえば、サインイン後にユーザーを /Home/Index にリダイレクトさせるには、次の HTML コードを使用します。For example, to navigate the user to /Home/Index after sign-in, use the following HTML code:

<a href="/.auth/login/<provider>?post_login_redirect_url=/Home/Index">Log in</a>

プロバイダーからのトークンを検証するValidate tokens from providers

クライアント主導のサインインでは、アプリケーションはユーザーをプロバイダーに手動でサインインさせ、検証のために認証トークンを App Service に送信します (「Authentication flow」をご覧ください)。In a client-directed sign-in, the application signs in the user to the provider manually and then submits the authentication token to App Service for validation (see Authentication flow). この検証自体では、必要なアプリ リソースへのアクセス権が実際には付与されませんが、検証に成功すると、アプリ リソースへのアクセスに使用できるセッション トークンが付与されます。This validation itself doesn't actually grant you access to the desired app resources, but a successful validation will give you a session token that you can use to access app resources.

プロバイダーのトークンを検証するには、最初に目的のプロバイダーを使用して App Service のアプリが構成されている必要があります。To validate the provider token, App Service app must first be configured with the desired provider. 実行時に、プロバイダーから認証トークンを取得した後、検証のためにトークンを /.auth/login/<provider> にポストします。At runtime, after you retrieve the authentication token from your provider, post the token to /.auth/login/<provider> for validation. 次に例を示します。For example:

POST https://<appname>.azurewebsites.net/.auth/login/aad HTTP/1.1
Content-Type: application/json

{"id_token":"<token>","access_token":"<token>"}

トークンの形式は、プロバイダーによって若干異なります。The token format varies slightly according to the provider. 詳しくは、以下の表をご覧ください。See the following table for details:

プロバイダーの値Provider value 要求本文に必要Required in request body 説明Comments
aad {"access_token":"<access_token>"}
microsoftaccount {"access_token":"<token>"} expires_in プロパティは省略可能です。The expires_in property is optional.
ライブ サービスからトークンを要求する場合は、常に wl.basic スコープを要求します。When requesting the token from Live services, always request the wl.basic scope.
google {"id_token":"<id_token>"} authorization_code プロパティは省略可能です。The authorization_code property is optional. 指定した場合、必要に応じて redirect_uri プロパティを添付することもできます。When specified, it can also optionally be accompanied by the redirect_uri property.
facebook {"access_token":"<user_access_token>"} Facebook からの有効なユーザー アクセス トークンを使用します。Use a valid user access token from Facebook.
twitter {"access_token":"<access_token>", "access_token_secret":"<acces_token_secret>"}

プロバイダー トークンが正常に検証された場合、API は、セッション トークンである authenticationToken を応答本文に入れて戻ります。If the provider token is validated successfully, the API returns with an authenticationToken in the response body, which is your session token.

{
    "authenticationToken": "...",
    "user": {
        "userId": "sid:..."
    }
}

このセッション トークンを入手したら、X-ZUMO-AUTH ヘッダーを HTTP 要求に追加することで、保護対象のアプリ リソースにアクセスすることができます。Once you have this session token, you can access protected app resources by adding the X-ZUMO-AUTH header to your HTTP requests. 次に例を示します。For example:

GET https://<appname>.azurewebsites.net/api/products/1
X-ZUMO-AUTH: <authenticationToken_value>

セッションからサインアウトするSign out of a session

ユーザーは、アプリの /.auth/logout エンドポイントに GET 要求を送信することでサインアウトを開始できます。Users can initiate a sign-out by sending a GET request to the app's /.auth/logout endpoint. GET 要求は次の処理を行います。The GET request does the following:

  • 現在のセッションから認証 Cookie をクリアします。Clears authentication cookies from the current session.
  • トークン ストアから現在のユーザーのトークンを削除します。Deletes the current user's tokens from the token store.
  • Azure Active Directory と Google の場合、ID プロバイダーでサーバー側のサインアウトを実行します。For Azure Active Directory and Google, performs a server-side sign-out on the identity provider.

Web ページの簡単なサインアウト リンクを次に示します。Here's a simple sign-out link in a webpage:

<a href="/.auth/logout">Sign out</a>

既定では、サインアウトに成功すると、クライアントは URL /.auth/logout/done にリダイレクトされます。By default, a successful sign-out redirects the client to the URL /.auth/logout/done. post_logout_redirect_uri クエリ パラメーターを追加して、サインアウト後のリダイレクト ページを変更できます。You can change the post-sign-out redirect page by adding the post_logout_redirect_uri query parameter. 次に例を示します。For example:

GET /.auth/logout?post_logout_redirect_uri=/index.html

post_logout_redirect_uri の値をエンコードすることをお勧めします。It's recommended that you encode the value of post_logout_redirect_uri.

完全修飾 URL を使用している場合、URL は同じドメインでホストされているか、アプリの許可された外部リダイレクト URL として構成されている必要があります。When using fully qualified URLs, the URL must be either hosted in the same domain or configured as an allowed external redirect URL for your app. 次の例では、同じドメインにホストされていない https://myexternalurl.com にリダイレクトします。In the following example, to redirect to https://myexternalurl.com that's not hosted in the same domain:

GET /.auth/logout?post_logout_redirect_uri=https%3A%2F%2Fmyexternalurl.com

Azure Cloud Shell で次のコマンドを実行します。Run the following command in the Azure Cloud Shell:

az webapp auth update --name <app_name> --resource-group <group_name> --allowed-external-redirect-urls "https://myexternalurl.com"

URL フラグメントを保持するPreserve URL fragments

ユーザーは、アプリにサインインすると、通常は /wiki/Main_Page#SectionZ のように同じページの同じセクションにリダイレクトされたいと考えます。After users sign in to your app, they usually want to be redirected to the same section of the same page, such as /wiki/Main_Page#SectionZ. ただし、URL フラグメント (たとえば #SectionZ) はサーバーに送信されないため、OAuth のサインインが完了してアプリにリダイレクトされた後は既定で保持されません。However, because URL fragments (for example, #SectionZ) are never sent to the server, they are not preserved by default after the OAuth sign-in completes and redirects back to your app. 目的のアンカーに再度移動する必要がある場合、ユーザー エクスペリエンスは最適ではありません。Users then get a suboptimal experience when they need to navigate to the desired anchor again. この制限は、すべてのサーバー側認証ソリューションに適用されます。This limitation applies to all server-side authentication solutions.

App Service 認証では、OAuth サインイン全体で URL フラグメントを保存できます。In App Service authentication, you can preserve URL fragments across the OAuth sign-in. これを行うには、WEBSITE_AUTH_PRESERVE_URL_FRAGMENT というアプリ設定を true に設定します。To do this, set an app setting called WEBSITE_AUTH_PRESERVE_URL_FRAGMENT to true. Azure portal で行うか、Azure Cloud Shell で次のコマンドを実行するだけです。You can do it in the Azure portal, or simply run the following command in the Azure Cloud Shell:

az webapp config appsettings set --name <app_name> --resource-group <group_name> --settings WEBSITE_AUTH_PRESERVE_URL_FRAGMENT="true"

ユーザー要求へのアクセスAccess user claims

App Service では、特殊なヘッダーを使用して、アプリケーションにユーザー要求を渡します。App Service passes user claims to your application by using special headers. 外部要求ではこれらのヘッダーの設定が許可されないので、これらのヘッダーは App Service によって設定されている場合にのみ存在します。External requests aren't allowed to set these headers, so they are present only if set by App Service. いくつかのヘッダーの例は次のとおりです。Some example headers include:

  • X-MS-CLIENT-PRINCIPAL-NAMEX-MS-CLIENT-PRINCIPAL-NAME
  • X-MS-CLIENT-PRINCIPAL-IDX-MS-CLIENT-PRINCIPAL-ID

任意の言語またはフレームワークで記述されたコードで、これらのヘッダーから必要な情報を取得できます。Code that is written in any language or framework can get the information that it needs from these headers. ASP.NET 4.6 アプリの場合は、 ClaimsPrincipal が自動的に適切な値に設定されます。For ASP.NET 4.6 apps, the ClaimsPrincipal is automatically set with the appropriate values. ただし、ASP.NET Core では、App Service のユーザー要求と統合する認証ミドルウェアが提供されません。ASP.NET Core, however, doesn't provide an authentication middleware that integrates with App Service user claims. 回避策については、「MaximeRouiller.Azure.AppService.EasyAuth」を参照してください。For a workaround, see MaximeRouiller.Azure.AppService.EasyAuth.

アプリでトークン ストアが有効になっている場合は、/.auth/me を呼び出して認証されたユーザーの追加の詳細を取得することもできます。If the token store is enabled for your app, you can also obtain additional details on the authenticated user by calling /.auth/me. Mobile Apps サーバー SDK には、このデータを操作するためのヘルパー メソッドが用意されています。The Mobile Apps server SDKs provide helper methods to work with this data. 詳細については、「Azure Mobile Apps Node.js SDK の使用方法」と「Azure Mobile Apps 用 .NET バックエンド サーバー SDK の操作」を参照してください。For more information, see How to use the Azure Mobile Apps Node.js SDK, and Work with the .NET backend server SDK for Azure Mobile Apps.

アプリ コードでのトークンの取得Retrieve tokens in app code

サーバー コードからプロバイダー固有のトークンが要求ヘッダーに挿入されるので、これらのトークンに簡単にアクセスできます。From your server code, the provider-specific tokens are injected into the request header, so you can easily access them. 次の表は、可能なトークン ヘッダー名を示しています。The following table shows possible token header names:

プロバイダーProvider ヘッダー名Header names
Azure Active DirectoryAzure Active Directory X-MS-TOKEN-AAD-ID-TOKEN
X-MS-TOKEN-AAD-ACCESS-TOKEN
X-MS-TOKEN-AAD-EXPIRES-ON
X-MS-TOKEN-AAD-REFRESH-TOKEN
Facebook トークンFacebook Token X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN
X-MS-TOKEN-FACEBOOK-EXPIRES-ON
GoogleGoogle X-MS-TOKEN-GOOGLE-ID-TOKEN
X-MS-TOKEN-GOOGLE-ACCESS-TOKEN
X-MS-TOKEN-GOOGLE-EXPIRES-ON
X-MS-TOKEN-GOOGLE-REFRESH-TOKEN
TwitterTwitter X-MS-TOKEN-TWITTER-ACCESS-TOKEN
X-MS-TOKEN-TWITTER-ACCESS-TOKEN-SECRET

クライアント コード (モバイル アプリやブラウザー内の JavaScript など) から、HTTP GET 要求を /.auth/me に送信します (トークン ストアを有効にする必要があります)。From your client code (such as a mobile app or in-browser JavaScript), send an HTTP GET request to /.auth/me (token store must be enabled). 返される JSON にはプロバイダー固有のトークンがあります。The returned JSON has the provider-specific tokens.

注意

アクセス トークンはプロバイダー リソースへのアクセス用であるため、クライアント シークレットを使用してプロバイダーを構成する場合にのみ存在します。Access tokens are for accessing provider resources, so they are present only if you configure your provider with a client secret. 更新トークンを取得する方法を確認するには、「更新アクセス トークン」を参照してください。To see how to get refresh tokens, see Refresh access tokens.

ID プロバイダー トークンの更新Refresh identity provider tokens

プロバイダーのアクセス トークン (セッション トークンではなく) が期限切れになった場合は、そのトークンを再度使用する前に、ユーザーを再認証する必要があります。When your provider's access token (not the session token) expires, you need to reauthenticate the user before you use that token again. アプリケーションの /.auth/refresh エンドポイントに GET 呼び出しを行って、トークンの期限切れを回避することができます。You can avoid token expiration by making a GET call to the /.auth/refresh endpoint of your application. 呼び出されると、App Service は認証されたユーザーのトークン ストア内のアクセス トークンを自動的に更新します。When called, App Service automatically refreshes the access tokens in the token store for the authenticated user. アプリ コードによる後続のトークン要求で、更新トークンを取得します。Subsequent requests for tokens by your app code get the refreshed tokens. ただし、トークンの更新が動作するためには、トークン ストアにプロバイダーの更新トークンが含まれている必要があります。However, for token refresh to work, the token store must contain refresh tokens for your provider. 更新トークンの取得方法は各プロバイダーによって文書化されていますが、次の一覧に概要を示します。The way to get refresh tokens are documented by each provider, but the following list is a brief summary:

  • Google: access_type=offline クエリ文字列パラメーターを /.auth/login/google API 呼び出しに追加します。Google: Append an access_type=offline query string parameter to your /.auth/login/google API call. Mobile Apps SDK を使用している場合は、LogicAsync オーバーロードの 1 つにパラメーターを追加できます (Google 更新トークンに関するページをご覧ください)。If using the Mobile Apps SDK, you can add the parameter to one of the LogicAsync overloads (see Google Refresh Tokens).
  • Facebook: 更新トークンを提供しません。Facebook: Doesn't provide refresh tokens. 長期間維持されるトークンの有効期限は 60 日間です (Facebook のアクセス トークンの有効期限と延長に関するページをご覧ください)。Long-lived tokens expire in 60 days (see Facebook Expiration and Extension of Access Tokens).
  • Twitter: アクセス トークンに有効期限はありません (Twitter OAuth の FAQ に関するページを参照してください)。Twitter: Access tokens don't expire (see Twitter OAuth FAQ).
  • Azure Active Directory: https://resources.azure.com で、次の手順を実行します。Azure Active Directory: In https://resources.azure.com, do the following steps:
    1. ページの上部にある [Read/Write] を選択します。At the top of the page, select Read/Write.

    2. 左側のブラウザーで、subscriptions > ** <subscription_name** > resourceGroups > **_ <resource_group_name> ** > providers > Microsoft.Web > sites > ** <app_name>** > config > authsettings に移動します。In the left browser, navigate to subscriptions > **<subscription_name_** > resourceGroups > **<resource_group_name>** > providers > Microsoft.Web > sites > **<app_name>** > config > authsettings.

    3. [編集] をクリックします。Click Edit.

    4. 次のプロパティを変更します。Modify the following property. <app_id> を、アクセスするサービスの Azure Active Directory アプリケーション ID に置き換えます。Replace <app_id> with the Azure Active Directory application ID of the service you want to access.

      "additionalLoginParams": ["response_type=code id_token", "resource=<app_id>"]
      
    5. [Put] をクリックします。Click Put.

プロバイダーが構成されたら、トークン ストアで更新トークンを見つけ、そのアクセス トークンの有効期限を確認できます。Once your provider is configured, you can find the refresh token and the expiration time for the access token in the token store.

任意の時点でアクセス トークンを更新するには、任意の言語で /.auth/refresh を呼び出します。To refresh your access token at any time, just call /.auth/refresh in any language. 次のスニペットでは、jQuery を使用して、JavaScript クライアントからアクセス トークンを更新します。The following snippet uses jQuery to refresh your access tokens from a JavaScript client.

function refreshTokens() {
  let refreshUrl = "/.auth/refresh";
  $.ajax(refreshUrl) .done(function() {
    console.log("Token refresh completed successfully.");
  }) .fail(function() {
    console.log("Token refresh failed. See application logs for details.");
  });
}

ユーザーがアプリに許可されている権限を取り消すと、/.auth/me の呼び出しは 403 Forbidden 応答で失敗する可能性があります。If a user revokes the permissions granted to your app, your call to /.auth/me may fail with a 403 Forbidden response. エラーを診断するには、アプリケーション ログで詳細を確認します。To diagnose errors, check your application logs for details.

セッション トークンの有効期限の猶予期間の延長Extend session token expiration grace period

認証されたセッションは、8 時間後に期限切れになります。The authenticated session expires after 8 hours. 認証されたセッションの期限が切れた後、既定で 72 時間の猶予期間があります。After an authenticated session expires, there is a 72-hour grace period by default. この猶予期間内は、ユーザーを再認証せずにセッション トークンを App Service で更新できます。Within this grace period, you're allowed to refresh the session token with App Service without reauthenticating the user. セッション トークンが無効になったときに /.auth/refresh を呼び出すことができ、トークンの有効期限を自分で追跡する必要はありません。You can just call /.auth/refresh when your session token becomes invalid, and you don't need to track token expiration yourself. 72 時間の猶予期間が経過した後、ユーザーはもう一度サインインして有効なセッション トークンを取得する必要があります。Once the 72-hour grace period is lapses, the user must sign in again to get a valid session token.

72 時間が十分な時間でない場合は、この有効期間を延長することができます。If 72 hours isn't enough time for you, you can extend this expiration window. 有効期限を長期に延長すると、セキュリティに大きく影響する可能性があります (認証トークンが漏洩または盗難にあった場合など)。Extending the expiration over a long period could have significant security implications (such as when an authentication token is leaked or stolen). したがって、既定の 72 時間のままにするか、延長期間を最小限の値に設定する必要があります。So you should leave it at the default 72 hours or set the extension period to the smallest value.

既定の有効期間を延長するには、Cloud Shell で次のコマンドを実行します。To extend the default expiration window, run the following command in the Cloud Shell.

az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>

注意

猶予期間は、ID プロバイダーからのトークンではなく、App Service で認証されたセッションにのみ適用されます。The grace period only applies to the App Service authenticated session, not the tokens from the identity providers. 有効期限が切れたプロバイダー トークンの猶予期間はありません。There is no grace period for the expired provider tokens.

サインイン アカウントのドメインの制限Limit the domain of sign-in accounts

Microsoft アカウントと Azure Active Directory の両方に複数のドメインからサインインできます。Both Microsoft Account and Azure Active Directory lets you sign in from multiple domains. たとえば、Microsoft アカウントでは outlook.comlive.comhotmail.com アカウントが許可されます。For example, Microsoft Account allows outlook.com, live.com, and hotmail.com accounts. Azure AD では、サインイン アカウントに任意の数のカスタム ドメインが許可されます。Azure AD allows any number of custom domains for the sign-in accounts. ただし、ユーザーを独自のブランドの Azure AD サインインページ (contoso.comなど) に直接誘導することもできます。However, you may want to accelerate your users straight to your own branded Azure AD sign-in page (such as contoso.com). サインイン アカウントのドメイン名を提示するには、以下の手順に従います。To suggest the domain name of the sign-in accounts, follow these steps.

https://resources.azure.com で、subscriptions > ** <subscription_name** > resourceGroups > **_ <resource_group_name> ** > providers > Microsoft.Web > sites > ** <app_name> ** > config > authsettings に移動します。In https://resources.azure.com, navigate to subscriptions > **<subscription_name_** > resourceGroups > **<resource_group_name>** > providers > Microsoft.Web > sites > **<app_name>** > config > authsettings.

[Edit] をクリックし、次のプロパティを変更し、 [Put] をクリックします。Click Edit, modify the following property, and then click Put. <domain_name> は使用するドメインで置き換えてください。Be sure to replace <domain_name> with the domain you want.

"additionalLoginParams": ["domain_hint=<domain_name>"]

この設定で、domain_hint クエリ文字列パラメーターがログイン リダイレクト URL に追加されます。This setting appends the domain_hint query string parameter to the login redirect URL.

重要

クライアントは、リダイレクト URL を受け取った後で domain_hint パラメーターを削除し、別のドメインでログインできます。It's possible for the client to remove the domain_hint parameter after receiving the redirect URL, and then login with a different domain. そのため、この機能は便利ですが、セキュリティ機能ではありません。So while this function is convenient, it's not a security feature.

ユーザーを承認または拒否するAuthorize or deny users

App Service は最も単純な承認ケース (つまり、認証されていない要求の拒否) を処理しますが、アプリでは、特定のユーザー グループだけにアクセスを制限するなど、よりきめ細かな承認動作が必要になる場合があります。While App Service takes care of the simplest authorization case (i.e. reject unauthenticated requests), your app may require more fine-grained authorization behavior, such as limiting access to only a specific group of users. 場合によっては、サインインしたユーザーに対してアクセスを許可または拒否するためのカスタム アプリケーション コードの記述が必要になります。In certain cases, you need to write custom application code to allow or deny access to the signed-in user. また、App Service やお使いの ID プロバイダーが、コードの変更を必要とせずにサポートできる場合もあります。In other cases, App Service or your identity provider may be able to help without requiring code changes.

サーバー レベル (Windows アプリのみ)Server level (Windows apps only)

Windows アプリでは、Web.config ファイルを編集して IIS Web サーバーの承認動作を定義できます。For any Windows app, you can define authorization behavior of the IIS web server, by editing the Web.config file. Linux アプリは、IIS を使用しないため、Web.config を使用して構成することはできません。Linux apps don't use IIS and can't be configured through Web.config.

  1. https://<app-name>.scm.azurewebsites.net/DebugConsole に移動しますNavigate to https://<app-name>.scm.azurewebsites.net/DebugConsole

  2. App Service ファイルのブラウザー エクスプローラーで、site/wwwroot に移動します。In the browser explorer of your App Service files, navigate to site/wwwroot. Web.config が存在しない場合は、 + > [新しいファイル] を選択して作成します。If a Web.config doesn't exist, create it by selecting + > New File.

  3. Web.config の鉛筆を選択して編集します。Select the pencil for Web.config to edit it. 次の構成コードを追加し、 [保存] をクリックします。Add the following configuration code and click Save. Web.config が既に存在する場合は、すべての内容を含めた <authorization> 要素を追加するだけです。If Web.config already exists, just add the <authorization> element with everything in it. 許可するアカウントを <allow> 要素に追加します。Add the accounts you want to allow in the <allow> element.

    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
       <system.web>
          <authorization>
            <allow users="user1@contoso.com,user2@contoso.com"/>
            <deny users="*"/>
          </authorization>
       </system.web>
    </configuration>
    

ID プロバイダー レベルIdentity provider level

ID プロバイダーによって特定のターンキー承認が提供される場合があります。The identity provider may provide certain turn-key authorization. 次に例を示します。For example:

アプリケーション レベルApplication level

他のいずれのレベルでも必要な承認が提供されない場合、またはお使いのプラットフォームまたは ID プロバイダーがサポートされていない場合、ユーザーの要求に基づいてユーザーを承認するカスタム コードを記述する必要があります。If either of the other levels don't provide the authorization you need, or if your platform or identity provider isn't supported, you must write custom code to authorize users based on the user claims.

構成バージョンの更新Updating the configuration version

認証および承認機能用の管理 API には、2 つのバージョンがあります。There are two versions of the management API for the Authentication / Authorization feature. Azure portal での "認証" エクスペリエンスには、V2 バージョンが必要です。The V2 version is required for the "Authentication" experience in the Azure portal. V1 の API が既に使用されているアプリは、いくつかの変更が行われた後に、V2 バージョンにアップグレードできます。An app already using the V1 API can upgrade to the V2 version once a few changes have been made. 具体的には、シークレット構成を、スロット固定のアプリケーション設定に移動する必要があります。Specifically, secret configuration must be moved to slot-sticky application settings. これは、アプリのポータルの [認証] セクションから自動的に実行されるようにすることができます。This can be done automatically from the "Authentication" section of the portal for your app.

警告

V2 に移行すると、Azure portal、Azure CLI、Azure PowerShell の既存のエクスペリエンスなど、一部のクライアントを介したアプリケーションに対する App Service の認証または承認機能の管理が無効になります。Migration to V2 will disable management of the App Service Authentication / Authorization feature for your application through some clients, such as its existing experience in the Azure portal, Azure CLI, and Azure PowerShell. これを元に戻すことはできません。This cannot be reversed.

V2 API では、V1 で行われていたように、個別のプロバイダーとして Microsoft アカウントを作成したり編集したりすることはできません。The V2 API does not support creation or editing of Microsoft Account as a distinct provider as was done in V1. むしろ、集中型 Microsoft ID プラットフォームを活用して、Azure AD と個人の両方の Microsoft アカウントを使用してユーザーをサインインさせます。Rather, it leverages the converged Microsoft Identity Platform to sign-in users with both Azure AD and personal Microsoft accounts. V2 API に切り替えるときは、V1 の Azure Active Directory 構成を使用して Microsoft ID プラットフォーム プロバイダーが構成されます。When switching to the V2 API, the V1 Azure Active Directory configuration is used to configure the Microsoft Identity Platform provider. V1 Microsoft アカウント プロバイダーは移行プロセスで持ち越されて、引き続き通常どおり動作しますが、新しい Microsoft ID プラットフォーム モデルに移行することをお勧めします。The V1 Microsoft Account provider will be carried forward in the migration process and continue to operate as normal, but it is recommended that you move to the newer Microsoft Identity Platform model. 詳細については、「Microsoft アカウント プロバイダーの登録のサポート」を参照してください。See Support for Microsoft Account provider registrations to learn more.

自動化された移行プロセスでは、プロバイダーのシークレットがアプリケーション設定内に移動され、構成の残りの部分は新しい形式に変換されます。The automated migration process will move provider secrets into application settings and then convert the rest of the configuration into the new format. 自動移行を使用するには:To use the automatic migration:

  1. ポータル内でアプリに移動し、 [認証] メニュー オプションを選択します。Navigate to your app in the portal and select the Authentication menu option.
  2. アプリが V1 モデルを使用して構成されている場合は、 [アップグレード] ボタンが表示されます。If the app is configured using the V1 model, you will see an Upgrade button.
  3. 確認プロンプトで説明を確認します。Review the description in the confirmation prompt. 移行を実行する準備ができたら、プロンプトで [アップグレード] をクリックします。If you are ready to perform the migration, click Upgrade in the prompt.

移行を手動で管理するManually managing the migration

次の手順では、上記で説明した自動バージョンを使用しない場合に、アプリケーションを V2 API に手動で移行することができます。The following steps will allow you to manually migrate the application to the V2 API if you do not wish to use the automatic version mentioned above.

シークレットをアプリケーション設定に移動Moving secrets to application settings

  1. V1 API を使用して既存の構成を取得します。Get your existing configuration by using the V1 API:

    # For Web Apps
    az webapp auth show -g <group_name> -n <site_name>
    
    # For Azure Functions
    az functionapp auth show -g <group_name> -n <site_name>
    

    結果として取得した JSON ペイロードで、構成した各プロバイダーに使用されているシークレット値をメモします。In the resulting JSON payload, make note of the secret value used for each provider you have configured:

    • AAD: clientSecretAAD: clientSecret
    • Google: googleClientSecretGoogle: googleClientSecret
    • Facebook: facebookAppSecretFacebook: facebookAppSecret
    • Twitter: twitterConsumerSecretTwitter: twitterConsumerSecret
    • Microsoft アカウント: microsoftAccountClientSecretMicrosoft Account: microsoftAccountClientSecret

    重要

    シークレット値は重要なセキュリティ資格情報であり、慎重に扱う必要があります。The secret values are important security credentials and should be handled carefully. これらの値を共有したり、ローカル マシン上に保持したりしないでください。Do not share these values or persist them on a local machine.

  2. 各シークレット値のスロット固定アプリケーション設定を作成します。Create slot-sticky application settings for each secret value. 各アプリケーション設定の名前を選択できます。You may choose the name of each application setting. この値は、前の手順で取得した値と一致しているか、その値を使用して作成した Key Vault シークレットを参照している必要があります。It's value should match what you obtained in the previous step or reference a Key Vault secret that you have created with that value.

    この設定を作成するには、Azure portal を使用するか、プロバイダーごとに次の方法を実行できます。To create the setting, you can use the Azure portal or run a variation of the following for each provider:

    # 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, Twitter example
    az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
    

    注意

    この構成のアプリケーション設定はスロット固定としてマークする必要があります。つまり、それらは、スロット スワップ操作中に環境間を移動しません。The application settings for this configuration should be marked as slot-sticky, meaning that they will not move between environments during a slot swap operation. これは、認証構成自体が環境に関連付けられているからです。This is because your authentication configuration itself is tied to the environment.

  3. authsettings.json という名前の新しい JSON ファイルを作成します。前に受け取った出力から各シークレット値を削除します。Create a new JSON file named authsettings.json.Take the output that you received previously and remove each secret value from it. シークレットが含まれていないことを確認して、残りの出力をファイルに書き込みます。Write the remaining output to the file, making sure that no secret is included. 場合によっては、空の文字列を含む配列が構成に含まれていることがあります。In some cases, the configuration may have arrays containing empty strings. microsoftAccountOAuthScopes がそうでないことを確認し、そうである場合は、その値を null に切り替えます。Make sure that microsoftAccountOAuthScopes does not, and if it does, switch that value to null.

  4. 前の手順で作成した各プロバイダーのアプリケーション設定名を指すプロパティを authsettings.json に追加します。Add a property to authsettings.json which points to the application setting name you created earlier for each provider:

    • AAD: clientSecretSettingNameAAD: clientSecretSettingName
    • Google: googleClientSecretSettingNameGoogle: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingNameFacebook: facebookAppSecretSettingName
    • Twitter: twitterConsumerSecretSettingNameTwitter: twitterConsumerSecretSettingName
    • Microsoft アカウント: microsoftAccountClientSecretSettingNameMicrosoft Account: microsoftAccountClientSecretSettingName

    この操作後のサンプル ファイルは、次のようになります。この場合は、AAD 用にのみ構成されています。An example file after this operation might look similar to the following, in this case only configured for AAD:

    {
        "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": "3197c8ed-2470-480a-8fae-58c25558ac9b",
            "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"
        }   
    }
    
  5. このファイルをアプリの新しい認証および承認構成として送信します。Submit this file as the new Authentication/Authorization configuration for your app:

    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
    
  6. この後もアプリが想定どおりに動作していることを確認します。Validate that your app is still operating as expected after this gesture.

  7. 前の手順で使用したファイルを削除します。Delete the file used in the previous steps.

これで、ID プロバイダーのシークレットをアプリケーション設定として格納するためにアプリが移行されました。You have now migrated the app to store identity provider secrets as application settings.

Microsoft アカウント プロバイダーの登録のサポートSupport for Microsoft Account provider registrations

既存の構成に Microsoft アカウント プロバイダーが含まれており、Azure Active Directory プロバイダーが含まれていない場合は、構成を Azure Active Directory プロバイダーに切り替えてから、移行を実行できます。If your existing configuration contains a Microsoft Account provider and does not contain an Azure Active Directory provider, you can switch the configuration over to the Azure Active Directory provider and then perform the migration. これを行うには、次の手順を実行します。To do this:

  1. Azure portal で [アプリの登録] に移動して、お使いの Microsoft アカウント プロバイダーに関連付けられている登録を見つけます。Go to App registrations in the Azure portal and find the registration associated with your Microsoft Account provider. [個人用アカウントからのアプリケーション] という見出しの下に表示されている場合があります。It may be under the "Applications from personal account" heading.
  2. その登録の [認証] ページに移動します。Navigate to the "Authentication" page for the registration. [リダイレクト URI] の下に、末尾が /.auth/login/microsoftaccount/callback のエントリが表示されます。Under "Redirect URIs" you should see an entry ending in /.auth/login/microsoftaccount/callback. この URI をコピーします。Copy this URI.
  3. コピーしたものと一致する新しい URI を追加します。ただし、末尾は /.auth/login/aad/callback にする必要があります。Add a new URI that matches the one you just copied, except instead have it end in /.auth/login/aad/callback. これにより、App Service の認証および承認構成でこの登録を使用できるようになります。This will allow the registration to be used by the App Service Authentication / Authorization configuration.
  4. アプリの App Service 認証および承認構成に移動します。Navigate to the App Service Authentication / Authorization configuration for your app.
  5. Microsoft アカウント プロバイダーの構成を収集します。Collect the configuration for the Microsoft Account provider.
  6. 前の手順で収集したクライアント ID とクライアント シークレットの値を指定し、"詳細" 管理モードを使用して Azure Active Directory プロバイダーを構成します。Configure the Azure Active Directory provider using the "Advanced" management mode, supplying the client ID and client secret values you collected in the previous step. 発行者の URL については、<authentication-endpoint>/<tenant-id>/v2.0 を使用し、 <authentication-endpoint>クラウド環境の認証エンドポイント (たとえば、グローバル Azure の場合、"https://login.microsoftonline.com") に置き換え、さらに、 <tenant-id>ディレクトリ (テナント) ID に置き換えます。For the Issuer URL, use Use <authentication-endpoint>/<tenant-id>/v2.0, and replace <authentication-endpoint> with the authentication endpoint for your cloud environment (e.g., "https://login.microsoftonline.com" for global Azure), also replacing <tenant-id> with your Directory (tenant) ID.
  7. 構成を保存したら、ブラウザーでサイトの /.auth/login/aad エンドポイントに移動し、サインイン フローを完了して、ログイン フローをテストします。Once you have saved the configuration, test the login flow by navigating in your browser to the /.auth/login/aad endpoint on your site and complete the sign-in flow.
  8. この時点で、構成は正常にコピーされましたが、既存の Microsoft アカウント プロバイダーの構成はそのまま残っています。At this point, you have successfully copied the configuration over, but the existing Microsoft Account provider configuration remains. それを削除する前に、アプリのすべての部分で、ログイン リンクなどを使用して Azure Active Directory プロバイダーが参照されていることを確認してください。アプリのすべての部分が想定どおりに動作することを確認します。Before you remove it, make sure that all parts of your app reference the Azure Active Directory provider through login links, etc. Verify that all parts of your app work as expected.
  9. AAD Azure Active Directory プロバイダーに対して機能することを検証したら、Microsoft アカウント プロバイダーの構成を削除できます。Once you have validated that things work against the AAD Azure Active Directory provider, you may remove the Microsoft Account provider configuration.

警告

AAD アプリの登録でサポートされているアカウントの種類を変更することにより、この 2 つの登録を集中させることができます。It is possible to converge the two registrations by modifying the supported account types for the AAD app registration. ただし、これにより、Microsoft アカウント ユーザーに対して新しい同意プロンプトが強制され、それらのユーザーの ID 要求の構造が異なるものになる場合があります。特に、新しいアプリ ID が使用されてから、sub で値が変化します。However, this would force a new consent prompt for Microsoft Account users, and those users' identity claims may be different in structure, sub notably changing values since a new App ID is being used. この方法は、十分に理解している場合を除き、推奨されません。This approach is not recommended unless thoroughly understood. 代わりに、V2 API でこの 2 つの登録に対するサポートが提供されるのを待つことをお勧めします。You should instead wait for support for the two registrations in the V2 API surface.

V2 への切り替えSwitching to V2

上記の手順を実行したら、Azure portal でアプリに移動します。Once the above steps have been performed, navigate to the app in the Azure portal. [認証 (プレビュー)] セクションを選択します。Select the "Authentication (preview)" section.

または、サイト リソースの下にある config/authsettingsv2 リソースに対して PUT 要求を行うこともできます。Alternatively, you may make a PUT request against the config/authsettingsv2 resource under the site resource. ペイロードのスキーマは、「ファイルを使用して構成する」セクションで取り込まれるものと同じです。The schema for the payload is the same as captured in the Configure using a file section.

ファイルを使用して構成する (プレビュー) Configure using a file (preview)

認証設定は、必要に応じて、デプロイによって提供されるファイルを使用して構成できます。Your auth settings can optionally be configured via a file that is provided by your deployment. これは、App Service の認証または承認の特定のプレビュー機能で必要になる場合があります。This may be required by certain preview capabilities of App Service Authentication / Authorization.

重要

アプリのペイロード、つまりこのファイルは、スロットと同様に環境間を移動する場合があることに注意してください。Remember that your app payload, and therefore this file, may move between environments, as with slots. 各スロットに異なるアプリ登録を固定したい場合はよくありますが、このような場合は、構成ファイルを使用する代わりに、標準の構成方法を使用し続ける必要があります。It is likely you would want a different app registration pinned to each slot, and in these cases, you should continue to use the standard configuration method instead of using the configuration file.

ファイルベースの構成の有効化Enabling file-based configuration

注意事項

プレビュー期間中、ファイルベースの構成を有効にすると、Azure portal、Azure CLI、Azure PowerShell などの一部のクライアントを介したアプリケーションの App Service の認証または承認機能の管理が無効になります。During preview, enabling file-based configuration will disable management of the App Service Authentication / Authorization feature for your application through some clients, such as the Azure portal, Azure CLI, and Azure PowerShell.

  1. 構成用の新しい JSON ファイルをプロジェクトのルートに作成します (Web/関数アプリでは D:\home\site\wwwroot にデプロイされます)。Create a new JSON file for your configuration at the root of your project (deployed to D:\home\site\wwwroot in your web / function app). ファイルベースの構成リファレンスに従って、必要な構成を入力します。Fill in your desired configuration according to the file-based configuration reference. 既存の Azure Resource Manager 構成を変更する場合は、必ず、authsettings コレクションにキャプチャされたプロパティを構成ファイルに変換してください。If modifying an existing Azure Resource Manager configuration, make sure to translate the properties captured in the authsettings collection into your configuration file.

  2. Azure Resource Manager API で Microsoft.Web/sites/<siteName>/config/authsettings にキャプチャされた既存の構成を変更します。Modify the existing configuration, which is captured in the Azure Resource Manager APIs under Microsoft.Web/sites/<siteName>/config/authsettings. これを変更するには、Azure Resource Manager テンプレートや、Azure Resource Explorer などのツールを使用できます。To modify this, you can use an Azure Resource Manager template or a tool like Azure Resource Explorer. authsettings コレクション内で、3 つのプロパティを設定する必要があります (他のプロパティは削除してもかまいません)。Within the authsettings collection, you will need to set three properties (and may remove others):

    1. enabled を "true" に設定しますSet enabled to "true"
    2. isAuthFromFile を "true" に設定しますSet isAuthFromFile to "true"
    3. authFilePath をファイルの名前に設定します ("auth.json" など)Set authFilePath to the name of the file (for example, "auth.json")

注意

authFilePath の形式は、プラットフォームによって異なります。The format for authFilePath varies between platforms. Windows では、相対パスと絶対パスの両方がサポートされます。On Windows, both relative and absolute paths are supported. 相対パスを使用することをお勧めします。Relative is recommended. Linux では、絶対パスのみが現在サポートされているため、設定の値は "/home/site/wwwroot/auth.json" または同様の値にする必要があります。For Linux, only absolute paths are supported currently, so the value of the setting should be "/home/site/wwwroot/auth.json" or similar.

この構成の更新を行うと、ファイルの内容を使用して、そのサイトでの App Service の認証または承認の動作が定義されます。Once you have made this configuration update, the contents of the file will be used to define the behavior of App Service Authentication / Authorization for that site. Azure Resource Manager 構成に戻りたい場合、isAuthFromFile を "false" に設定し直せば戻ることができます。If you ever wish to return to Azure Resource Manager configuration, you can do so by setting isAuthFromFile back to "false".

構成ファイル リファレンスConfiguration file reference

構成ファイルから参照されるシークレットがある場合、アプリケーション設定として保存する必要があります。Any secrets that will be referenced from your configuration file must be stored as application settings. 設定には任意の名前を付けることができます。You may name the settings anything you wish. 構成ファイルからの参照で同じキーを使用していることを確認してください。Just make sure that the references from the configuration file uses the same keys.

次の例では、ファイル内の可能な構成オプションを使い果たしています。The following exhausts possible configuration options within the file:

{
    "platform": {
        "enabled": <true|false>
    },
    "globalValidation": {
        "unauthenticatedClientAction": "RedirectToLoginPage|AllowAnonymous|Return401|Return403",
        "redirectToProvider": "<default provider alias>",
        "excludedPaths": [
            "/path1",
            "/path2"
        ]
    },
    "httpSettings": {
        "requireHttps": <true|false>,
        "routes": {
            "apiPrefix": "<api prefix>"
        },
        "forwardProxy": {
            "convention": "NoProxy|Standard|Custom",
            "customHostHeaderName": "<host header value>",
            "customProtoHeaderName": "<proto header value>"
        }
    },
    "login": {
        "routes": {
            "logoutEndpoint": "<logout endpoint>"
        },
        "tokenStore": {
            "enabled": <true|false>,
            "tokenRefreshExtensionHours": "<double>",
            "fileSystem": {
                "directory": "<directory to store the tokens in if using a file system token store (default)>"
            },
            "azureBlobStorage": {
                "sasUrlSettingName": "<app setting name containing the sas url for the Azure Blob Storage if opting to use that for a token store>"
            }
        },
        "preserveUrlFragmentsForLogins": <true|false>,
        "allowedExternalRedirectUrls": [
            "https://uri1.azurewebsites.net/",
            "https://uri2.azurewebsites.net/",
            "url_scheme_of_your_app://easyauth.callback"
        ],
        "cookieExpiration": {
            "convention": "FixedTime|IdentityDerived",
            "timeToExpiration": "<timespan>"
        },
        "nonce": {
            "validateNonce": <true|false>,
            "nonceExpirationInterval": "<timespan>"
        }
    },
    "identityProviders": {
        "azureActiveDirectory": {
            "enabled": <true|false>,
            "registration": {
                "openIdIssuer": "<issuer url>",
                "clientId": "<app id>",
                "clientSecretSettingName": "APP_SETTING_CONTAINING_AAD_SECRET",
            },
            "login": {
                "loginParameters": [
                    "paramName1=value1",
                    "paramName2=value2"
                ]
            },
            "validation": {
                "allowedAudiences": [
                    "audience1",
                    "audience2"
                ]
            }
        },
        "facebook": {
            "enabled": <true|false>,
            "registration": {
                "appId": "<app id>",
                "appSecretSettingName": "APP_SETTING_CONTAINING_FACEBOOK_SECRET"
            },
            "graphApiVersion": "v3.3",
            "login": {
                "scopes": [
                    "public_profile",
                    "email"
                ]
            },
        },
        "gitHub": {
            "enabled": <true|false>,
            "registration": {
                "clientId": "<client id>",
                "clientSecretSettingName": "APP_SETTING_CONTAINING_GITHUB_SECRET"
            },
            "login": {
                "scopes": [
                    "profile",
                    "email"
                ]
            }
        },
        "google": {
            "enabled": true,
            "registration": {
                "clientId": "<client id>",
                "clientSecretSettingName": "APP_SETTING_CONTAINING_GOOGLE_SECRET"
            },
            "login": {
                "scopes": [
                    "profile",
                    "email"
                ]
            },
            "validation": {
                "allowedAudiences": [
                    "audience1",
                    "audience2"
                ]
            }
        },
        "twitter": {
            "enabled": <true|false>,
            "registration": {
                "consumerKey": "<consumer key>",
                "consumerSecretSettingName": "APP_SETTING_CONTAINING TWITTER_CONSUMER_SECRET"
            }
        },
        "apple": {
            "enabled": <true|false>,
            "registration": {
                "clientId": "<client id>",
                "clientSecretSettingName": "APP_SETTING_CONTAINING_APPLE_SECRET"
            },
            "login": {
                "scopes": [
                    "profile",
                    "email"
                ]
            }
        },
        "openIdConnectProviders": {
            "<providerName>": {
                "enabled": <true|false>,
                "registration": {
                    "clientId": "<client id>",
                    "clientCredential": {
                        "clientSecretSettingName": "<name of app setting containing client secret>"
                    },
                    "openIdConnectConfiguration": {
                        "authorizationEndpoint": "<url specifying authorization endpoint>",
                        "tokenEndpoint": "<url specifying token endpoint>",
                        "issuer": "<url specifying issuer>",
                        "certificationUri": "<url specifying jwks endpoint>",
                        "wellKnownOpenIdConfiguration": "<url specifying .well-known/open-id-configuration endpoint - if this property is set, the other properties of this object are ignored, and authorizationEndpoint, tokenEndpoint, issuer, and certificationUri are set to the corresponding values listed at this endpoint>"
                    }
                },
                "login": {
                    "nameClaimType": "<name of claim containing name>",
                    "scopes": [
                        "openid",
                        "profile",
                        "email"
                    ],
                    "loginParameterNames": [
                        "paramName1=value1",
                        "paramName2=value2"
                    ],
                }
            },
            //...
        }
    }
}

特定の認証ランタイム バージョンにアプリをピン留めするPin your app to a specific authentication runtime version

認証/承認を有効にすると、機能の概要で説明されているように、プラットフォーム ミドルウェアが HTTP 要求パイプラインに挿入されます。When you enable Authentication / Authorization, platform middleware is injected into your HTTP request pipeline as described in the feature overview. このプラットフォーム ミドルウェアは、定期的なプラットフォームの更新の一環として、新機能と機能強化で定期的に更新されます。This platform middleware is periodically updated with new features and improvements as part of routine platform updates. 既定では、Web アプリまたは関数アプリは、このプラットフォーム ミドルウェアの最新バージョンで実行されます。By default, your web or function app will run on the latest version of this platform middleware. これらの自動更新は、常に下位互換性があります。These automatic updates are always backwards compatible. ただし、まれに、この自動更新によって Web アプリまたは関数アプリにランタイムの問題が発生することがあります。その場合は、以前のミドルウェア バージョンに一時的にロールバックすることができます。However, in the rare event that this automatic update introduces a runtime issue for your web or function app, you can temporarily roll back to the previous middleware version. この記事では、特定のバージョンの認証ミドルウェアにアプリを一時的にピン留めする方法について説明します。This article explains how to temporarily pin an app to a specific version of the authentication middleware.

自動および手動でのバージョンの更新Automatic and manual version updates

アプリの runtimeVersion 設定を設定することで、プラットフォーム ミドルウェアの特定のバージョンにアプリをピン留めすることができます。You can pin your app to a specific version of the platform middleware by setting a runtimeVersion setting for the app. 特定のバージョンに明示的にピン留めし直さない限り、アプリは常に最新バージョンで実行されます。Your app always runs on the latest version unless you choose to explicitly pin it back to a specific version. 一度にサポートされるバージョンはいくつかあります。There will be a few versions supported at a time. サポートされなくなった無効なバージョンにピン留めすると、アプリでは代わりに最新バージョンが使用されます。If you pin to an invalid version that is no longer supported, your app will use the latest version instead. 常に最新バージョンを実行するには、runtimeVersion を ~1 に設定します。To always run the latest version, set runtimeVersion to ~1.

現在のランタイム バージョンの表示と更新View and update the current runtime version

アプリで使用されるランタイム バージョンを変更できます。You can change the runtime version used by your app. 新しいランタイム バージョンは、アプリを再起動した後に有効になります。The new runtime version should take effect after restarting the app.

現在のランタイム バージョンの表示View the current runtime version

プラットフォーム認証ミドルウェアの現在のバージョンを表示するには、Azure CLI を使用するか、アプリ内にある組み込みバージョン HTTP エンドポイントのいずれか 1 つを経由します。You can view the current version of the platform authentication middleware either using the Azure CLI or via one of the built-in version HTTP endpoints in your app.

Azure CLI からFrom the Azure CLI

Azure CLI を使用して、az webapp auth show コマンドで現在のミドルウェア バージョンを表示します。Using the Azure CLI, view the current middleware version with the az webapp auth show command.

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

このコードでは、<my_app_name> をアプリの名前に置き換えます。In this code, replace <my_app_name> with the name of your app. また、<my_resource_group> をアプリのリソース グループの名前に置き換えます。Also replace <my_resource_group> with the name of the resource group for your app.

CLI 出力に runtimeVersion フィールドが表示されます。You will see the runtimeVersion field in the CLI output. 次の出力例のようになります。ここでは、わかりやすくするために抜粋されています。It will resemble the following example output, which has been truncated for clarity:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
バージョン エンドポイントからFrom the version endpoint

アプリで /.auth/version エンドポイントをクリックして、アプリが実行されている現在のミドルウェア バージョンを表示することもできます。You can also hit /.auth/version endpoint on an app also to view the current middleware version that the app is running on. 次の出力例のようになります。It will resemble the following example output:

{
"version": "1.3.2"
}

現在のランタイム バージョンの更新Update the current runtime version

Azure CLI を使用すると、az webapp auth update コマンドでアプリの runtimeVersion 設定を更新できます。Using the Azure CLI, you can update the runtimeVersion setting in the app with the az webapp auth update command.

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

<my_app_name> をご自分のアプリの名前に置き換えます。Replace <my_app_name> with the name of your app. また、<my_resource_group> をアプリのリソース グループの名前に置き換えます。Also replace <my_resource_group> with the name of the resource group for your app. また、<version> を 1.x ランタイムの有効なバージョン、または最新バージョンの ~1 に置き換えます。Also, replace <version> with a valid version of the 1.x runtime or ~1 for the latest version. さまざまなランタイム バージョンのリリース ノートを [こちら] (https://github.com/Azure/app-service-announcements) ) で検索して、ピン留め先となるバージョンを特定することができます。You can find the release notes on the different runtime versions [here] (https://github.com/Azure/app-service-announcements) to help determine the version to pin to.

このコマンドは、上記のコード サンプルの [テスト] をクリックすることで、Azure Cloud Shell から実行できます。You can run this command from the Azure Cloud Shell by choosing Try it in the preceding code sample. また、Azure CLI をローカルに使用して、az ログインを実行してサインインした後に、このコマンドを実行することもできます。You can also use the Azure CLI locally to execute this command after executing az login to sign in.

次のステップNext steps