Azure Static Web Apps でのカスタム認証

[アーティクル]
2024/07/22

Azure Static Web Apps が提供するマネージド認証では、Azure が管理するプロバイダー登録が使用されます。登録の柔軟性を高めるため、既定値をカスタム登録でオーバーライドできます。

またカスタム認証により、OpenID Connect をサポートするカスタムプロバイダーを構成できます。この構成では、複数の外部プロバイダーを登録できます。
カスタム登録を使うと、事前構成済みのすべてのプロバイダーが無効になります。

注意

カスタム認証は、Azure Static Web Apps Standard プランでのみ使用できます。

カスタム ID プロバイダーを構成する

カスタム ID プロバイダーは、構成ファイルの auth セクションで構成されます。

ソース管理にシークレットが入り込まないようにするため、構成ではアプリケーション設定が調べられ、構成ファイルに一致する名前があるかどうかが確認されます。また、Azure Key Vault にシークレットを格納することも選択できます。

登録を作成するには、以下のアプリケーション設定の作成から始めます。

設定名	値
`AZURE_CLIENT_ID`	Microsoft Entra アプリ登録のアプリケーション (クライアント) ID。
`AZURE_CLIENT_SECRET_APP_SETTING_NAME`	Microsoft Entra アプリ登録のクライアントシークレットを保持するアプリケーション設定の名前。

次に、下記のサンプルを使用して、構成ファイルでプロバイダーを構成します。

Microsoft Entra プロバイダーは、2 つの異なるバージョンで提供されています。バージョン 1 では、ペイロードでユーザー情報を返すことができると、userDetailsClaim が明示的に定義されています。これに対してバージョン 2 では、既定でユーザー情報が返されます。それは openIdIssuer URL 内の v2.0 によって指定されます。

Microsoft Entra バージョン 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

<TENANT_ID> を Microsoft Entra テナント ID に置き換えてください。

Microsoft Entra バージョン 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

<TENANT_ID> を Microsoft Entra テナント ID に置き換えてください。

Microsoft Entra ID を構成する方法の詳細については、「App Service の認証と認可に関するドキュメント」で既存の登録の使用について参照してください。

サインインできるアカウントを構成する方法については、「アプリケーションによってサポートされるアカウントを変更する」と「Microsoft Entra アプリを Microsoft Entra テナントの一連のユーザーに制限する」を参照してください。

注意

Microsoft Entra ID の構成セクションは azureActiveDirectory ですが、プラットフォームでは、ログイン、ログアウト、ユーザー情報の消去のために、これを URL 内の aad にエイリアス化します。詳細については、認証と承認に関するセクションを参照してください。

カスタム証明書

Microsoft Entra ID のアプリ登録にカスタム証明書を追加するには、次の手順のようにします。

まだない場合は、Microsoft キーコンテナーに証明書をアップロードします。
静的 Web アプリでマネージド ID を追加します。

ユーザー割り当てマネージド ID の場合は、静的サイトオブジェクトの keyVaultReferenceIdentity プロパティを、ユーザー割り当てマネージド ID の resourceId に設定します。

マネージド ID がシステム割り当てである場合は、このステップをスキップします。
マネージド ID に次のアクセスポリシーを付与します。
- シークレット: 取得/一覧表示
- 証明書: 取得/一覧表示
次の例に示すように、azureActiveDirectory 構成セクションの認証構成セクションを clientSecretCertificateKeyVaultReference の値で更新します。
```
{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/common/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)",
          "clientSecretCertificateThumbprint": "*"
        }
      }
    }
  }
}
```
<> で囲まれたプレースホルダーを実際の値に必ず置き換えてください。

シークレット URI で、キーコンテナー名と証明書名を指定します。バージョンを固定する場合は、証明書のバージョンを含めます。それ以外の場合はバージョンを省略して、ランタイムが証明書の最新バージョンを選択できるようにします。

証明書の拇印の最新バージョンを常にプルするには、clientSecretCertificateThumbprint を * に設定します。

登録を作成するには、以下のアプリケーション設定の作成から始めます。

設定名	値
`APPLE_CLIENT_ID`	Apple クライアント ID。
`APPLE_CLIENT_SECRET_APP_SETTING_NAME`	Apple クライアントシークレットを保持するアプリケーション設定の名前。

次に、下記のサンプルを使用して、構成ファイルでプロバイダーを構成します。

{
  "auth": {
    "identityProviders": {
      "apple": {
        "registration": {
          "clientIdSettingName": "APPLE_CLIENT_ID",
          "clientSecretSettingName": "APPLE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Apple を認証プロバイダーとしてを構成する方法の詳細については、App Service の認証/認可に関する記事を参照してください。

登録を作成するには、以下のアプリケーション設定の作成から始めます。

設定名	値
`FACEBOOK_APP_ID`	Facebook アプリケーション ID。
`FACEBOOK_APP_SECRET_APP_SETTING_NAME`	Facebook アプリケーションシークレットを保持するアプリケーション設定の名前。

次に、下記のサンプルを使用して、構成ファイルでプロバイダーを構成します。

{
  "auth": {
    "identityProviders": {
      "facebook": {
        "registration": {
          "appIdSettingName": "FACEBOOK_APP_ID",
          "appSecretSettingName": "FACEBOOK_APP_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Facebook を認証プロバイダーとしてを構成する方法の詳細については、App Service の認証/認可に関する記事を参照してください。

登録を作成するには、以下のアプリケーション設定の作成から始めます。

設定名	値
`GITHUB_CLIENT_ID`	GitHub クライアント ID。
`GITHUB_CLIENT_SECRET_APP_SETTING_NAME`	GitHub クライアントシークレットを保持するアプリケーション設定の名前。

次に、下記のサンプルを使用して、構成ファイルでプロバイダーを構成します。

{
  "auth": {
    "identityProviders": {
      "github": {
        "registration": {
          "clientIdSettingName": "GITHUB_CLIENT_ID",
          "clientSecretSettingName": "GITHUB_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

登録を作成するには、以下のアプリケーション設定の作成から始めます。

設定名	値
`GOOGLE_CLIENT_ID`	Google クライアント ID。
`GOOGLE_CLIENT_SECRET_APP_SETTING_NAME`	Google クライアントシークレットを保持するアプリケーション設定の名前。

次に、下記のサンプルを使用して、構成ファイルでプロバイダーを構成します。

{
  "auth": {
    "identityProviders": {
      "google": {
        "registration": {
          "clientIdSettingName": "GOOGLE_CLIENT_ID",
          "clientSecretSettingName": "GOOGLE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Google を認証プロバイダーとしてを構成する方法の詳細については、App Service の認証/認可に関する記事を参照してください。

登録を作成するには、以下のアプリケーション設定の作成から始めます。

設定名	Value
`X_CONSUMER_KEY`	X のコンシューマーキー。
`X_CONSUMER_SECRET_APP_SETTING_NAME`	X のコンシューマーシークレットを保持するアプリケーション設定の名前。

次に、下記のサンプルを使用して、構成ファイルでプロバイダーを構成します。

{
  "auth": {
    "identityProviders": {
      "twitter": {
        "registration": {
          "consumerKeySettingName": "X_CONSUMER_KEY",
          "consumerSecretSettingName": "X_CONSUMER_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

X を認証プロバイダーとして構成する方法の詳細については、App Service の認証または許可に関するドキュメントを参照してください。

OpenID Connect (OIDC) 仕様に準拠するカスタム認証プロバイダーを使用するように、Azure Static Web Apps を構成できます。カスタム OIDC プロバイダーを使うには、次の手順が必要です。

1 つ以上の OIDC プロバイダーを使用できます。
各プロバイダーには、構成内で一意の名前が必要です。
既定のリダイレクトターゲットとして使用できるプロバイダーは 1 つのみです。

アプリケーションを ID プロバイダーに登録する

アプリケーションの詳細を ID プロバイダーに登録する必要があります。アプリケーションのクライアント ID とクライアントシークレットを生成するために必要な手順については、プロバイダーにお問い合わせください。

アプリケーションが ID プロバイダーに登録されたら、静的 Web アプリのアプリケーション設定内に、以下のアプリケーションシークレットを作成します。

設定名	値
`MY_PROVIDER_CLIENT_ID`	お使いの静的 Web アプリの認証プロバイダーによって生成されたクライアント ID。
`MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME`	静的 Web アプリの認証プロバイダーのカスタム登録によって生成されたクライアントシークレットを保持するアプリケーション設定の名前。

他のプロバイダーを登録する場合は、それぞれに関連付けられているクライアント ID とクライアントシークレットストアが、アプリケーション設定内に必要です。

重要

アプリケーションシークレットは機密性の高いセキュリティ資格情報です。このシークレットを他のユーザーと共有したり、クライアントアプリケーション内で配布したり、ソース管理にチェックインしたりしないでください。

登録資格情報を取得したら、次の手順に従ってカスタム登録を作成します。

プロバイダーの OpenID Connect メタデータが必要になります。この情報は、多くの場合、プロバイダーの "発行者の URL" の末尾に /.well-known/openid-configuration が付いた構成メタデータドキュメントを介して公開されます。この構成 URL を収集します。

authの auth セクションに、OICD プロバイダーの構成ブロックとプロバイダー定義を追加します。

{
  "auth": {
    "identityProviders": {
      "customOpenIdConnectProviders": {
        "myProvider": {
          "registration": {
            "clientIdSettingName": "MY_PROVIDER_CLIENT_ID",
            "clientCredential": {
              "clientSecretSettingName": "MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME"
            },
            "openIdConnectConfiguration": {
              "wellKnownOpenIdConfiguration": "https://<PROVIDER_ISSUER_URL>/.well-known/openid-configuration"
            }
          },
          "login": {
            "nameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
            "scopes": [],
            "loginParameterNames": []
          }
        }
      }
    }
  }
}

プロバイダー名 (この例では myProvider) は、Azure Static Web Apps によって使用される一意の識別子です。
<PROVIDER_ISSUER_URL> は、必ず、プロバイダーの "発行者 URL" のパスに置き換えます。
login オブジェクトを使うと、カスタムスコープ、ログインパラメーター、またはカスタム要求の値を指定できます。

認証コールバック

ID プロバイダーには、ログインまたはログアウトの要求を完了するためにリダイレクト URL が必要です。ほとんどのプロバイダーでは、コールバック URL を許可リストに追加する必要があります。次のエンドポイントは、リダイレクト先として使用できます。

Type	URL パターン
ログイン	`https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback`
Logout	`https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback`

Microsoft Entra ID を使用している場合は、 <PROVIDER_NAME_IN_CONFIG> プレースホルダーの値として aad を使用します。

注意

これらの URL は、認証プロバイダーからの応答を受信するために Azure Static Web Apps により提供されます。これらのルートでページを作成する必要はありません。

カスタム ID プロバイダーを使用するには、次の URL パターンを使用します。

アクション	パターン
ログイン	`/.auth/login/<PROVIDER_NAME_IN_CONFIG>`
Logout	`/.auth/logout`
ユーザーの詳細	`/.auth/me`
ユーザーの詳細の削除	`/.auth/purge/<PROVIDER_NAME_IN_CONFIG>`

Microsoft Entra ID を使用している場合は、 <PROVIDER_NAME_IN_CONFIG> プレースホルダーの値として aad を使用します。

ロールの管理

静的 Web アプリにアクセスするすべてのユーザーは、1 つまたは複数のロールに属しています。ユーザーは、以下の 2 つの組み込みロールに属することができます。

匿名: すべてのユーザーは自動的に "匿名" ロールに属します。
認証済み: サインインしているすべてのユーザーは、認証済みロールに属します。

組み込みロール以外にカスタムロールをユーザーに割り当て、staticwebapp.config.json ファイルで参照することができます。

招待
Function (preview)

ユーザーをロールに追加する

ユーザーをロールに追加するには、ユーザーを特定のロールに関連付けることができる招待を生成します。ロールは、staticwebapp.config.json ファイル内で定義および管理されます。

招待状の作成

招待は個々の承認プロバイダーに固有であるため、サポートするプロバイダーを選択する際には、アプリのニーズを考慮してください。プロバイダーによって、ユーザーの電子メールアドレスが公開される場合もあれば、サイトのユーザー名のみが提示される場合もあります。

承認プロバイダー	公開
Microsoft Entra ID	メールアドレス
GitHub	username
x	username

招待を作成するには、次の手順のようにします。

Azure portal 上で Static Web Apps リソースに移動します。
[設定] で [ロール管理] を選択します。
[招待] を選びます。
オプションの一覧から [承認プロバイダー] を選択します。
[Invitee details]\(招待者の詳細\) ボックスに、受信者のユーザー名または電子メールアドレスを追加します。
- GitHub および X の場合はユーザー名を入力します。それ以外の場合は、受信者の電子メールアドレスを入力します。
[ドメイン] ドロップダウンメニューから静的サイトのドメインを選択します。
- 選択されたドメインは、招待に表示されるドメインになります。サイトに関連付けられているカスタムドメインがある場合は、そのカスタムドメインを選択します。
[ロール] ボックスにロール名のコンマ区切りの一覧を追加します。
招待が有効なまま維持される最大時間数を入力します。
- 指定できる最大上限は、168 時間 (7 日間) です。
[Generate] \(生成) を選択します。
[Invite link]\(招待リンク\) ボックスからリンクをコピーします。
アクセス権を付与するユーザーに招待リンクを電子メールで送信します。

ユーザーが招待のリンクを選択すると、該当のアカウントでサインインするように求められます。正常にサインインが行われると、選択されたロールにユーザーが関連付けられます。

注意事項

ルート規則が、選択された認証プロバイダーと競合しないようにしてください。ルート規則によってプロバイダーがブロックされると、ユーザーは招待を承諾することができなくなります。

ロールの割り当てを更新する

Azure portal 上で Static Web Apps リソースに移動します。
[設定] で [ロール管理] を選択します。
ユーザーを一覧から選びます。
[ロール] ボックスで、ロールの一覧を編集します。
[更新] を選択します。

ユーザーを削除する

Azure portal 上で Static Web Apps リソースに移動します。
[設定] で [ロール管理] を選択します。
一覧上でユーザーを探します。
そのユーザーの行のチェックボックスをオンにします。
削除を選択します。

ユーザーを削除する際には、以下の点に注意してください。

ユーザーを削除すると、そのユーザーのアクセス許可は無効になります。
世界中に反映されるには、数分かかる場合があります。
ユーザーがアプリに再び追加される場合、userId は変更されます。

組み込みの招待システムを使用する代わりに、サーバーレス機能を使用し、ユーザーがサインインするときにロールをプログラムでユーザーに割り当てることができます。

関数にカスタムロールを割り当てるには、ユーザーが ID プロバイダーで正常に認証されるたびに自動的に呼び出される API 関数を定義します。関数には、プロバイダーからユーザーの情報が渡されます。関数は、ユーザーに割り当てられているカスタムロールの一覧を返す必要があります。

この関数の使用例を次に示します。

データベースに対してクエリを実行し、ユーザーに割り当てるロールを決定する
Microsoft Graph API を呼び出して、Active Directory グループメンバーシップに基づいてユーザーのロール割を決定する
ID プロバイダーによって返されたクレームに基づいてユーザーのロールを決定する

注意

関数を使用してロールを割り当てることができるのは、カスタム認証が構成されている場合のみです。

この機能を有効にすると、組み込みの招待システムを介して割り当てられたすべてのロールは無視されます。

ロールを割り当てる関数を構成する

ロールの割り当て機能として API 関数を使用するように Static Web Apps を構成するには、アプリケーションの構成ファイルのセクションにrolesSourceプロパティauthを追加します。 rolesSource プロパティの値は API 関数へのパスです。

{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      // ...
    }
  }
}

注意

構成が完了すると、外部の HTTP 要求からロール割り当て関数にアクセスできなくなります。

ロールを割り当てる関数を作成する

アプリの構成で rolesSource プロパティを定義した後で、指定したパスの静的 Web アプリに API 関数を追加します。マネージド関数アプリを使用することも、独自の関数アプリを取り入れることもできます。

ユーザーが ID プロバイダーで正常に認証されるたびに、POST メソッドによって、指定した関数が呼び出されます。この関数によって、プロバイダーからのユーザー情報を含む JSON オブジェクトが要求本文に渡されます。 ID プロバイダーによっては、関数でユーザー ID を使用して API 呼び出しを行うために使用できる accessToken もユーザー情報に含まれている場合があります。

Microsoft Entra ID のペイロードの例を次に示します:

{
  "identityProvider": "aad",
  "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "userDetails": "ellen@contoso.com",
  "claims": [
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
          "val": "Contoso"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
          "val": "Ellen"
      },
      {
          "typ": "name",
          "val": "Ellen Contoso"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier",
          "val": "7da753ff-1c8e-4b5e-affe-d89e5a57fe2f"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          "val": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/tenantid",
          "val": "3856f5f5-4bae-464a-9044-b72dc2dcde26"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "ver",
          "val": "1.0"
      }
  ],
  "accessToken": "eyJ0eXAiOiJKV..."
}

関数は、ユーザーの情報を使用して、ユーザーに割り当てるロールを決定できます。関数は、ユーザーに割り当てるカスタムロール名のリストを含む JSON 本文を含む HTTP 200 応答を返す必要があります。

たとえば、ユーザーに Reader と Contributor のロールを割り当てるには、次の応答を返します。

{
  "roles": [
    "Reader",
    "Contributor"
  ]
}

ユーザーに他のロールを割り当てたくない場合は、空の roles 配列を返します。

詳細については、「チュートリアル: 関数と Microsoft Graph を使用してカスタムロールを割り当てる」を参照してください。

次のステップ

プログラムを使用してユーザーロールを設定する

次の方法で共有

Azure Static Web Apps でのカスタム認証

カスタム ID プロバイダーを構成する

Microsoft Entra バージョン 1

Microsoft Entra バージョン 2

カスタム証明書

アプリケーションを ID プロバイダーに登録する

認証コールバック

ロールの管理

ユーザーをロールに追加する

招待状の作成

ロールの割り当てを更新する

ユーザーを削除する

ロールを割り当てる関数を構成する

ロールを割り当てる関数を作成する

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Static Web Apps でのカスタム認証

カスタム ID プロバイダーを構成する

Microsoft Entra バージョン 1

Microsoft Entra バージョン 2

カスタム証明書

認証コールバック

ログイン、ログアウト、ユーザーの詳細

ロールの管理

ユーザーをロールに追加する

招待状の作成

ロールの割り当てを更新する

ユーザーを削除する

次のステップ

フィードバック

その他のリソース