Merge pull request #278722 from craigshoemaker/swa/certificates

[Static Web Apps] Update: Custom authentication -> add Entra ID custom certificate

Author: prmerger-automator[bot]

articles/static-web-apps/authentication-custom.md

@@ -15,7 +15,7 @@ Azure Static Web Apps provides [managed authentication](authentication-authoriza
 
 - Custom authentication also allows you to [configure custom providers](./authentication-custom.md?tabs=openid-connect#configure-a-custom-identity-provider) that support [OpenID Connect](https://openid.net/connect/). This configuration allows the registration of multiple external providers.
 
-- Using any custom registrations disables all pre-configured providers.
+- Using any custom registrations disables all preconfigured providers.
 
 > [!NOTE]
 > Custom authentication is only available in the Azure Static Web Apps Standard plan.
@@ -24,7 +24,7 @@ Azure Static Web Apps provides [managed authentication](authentication-authoriza
 
 Custom identity providers are configured in the `auth` section of the [configuration file](configuration.md).
 
-To avoid putting secrets in source control, the configuration looks into [application settings](application-settings.yml#configure-application-settings) for a matching name in the configuration file. You may also choose to store your secrets in [Azure Key Vault](./key-vault-secrets.md).
+To avoid putting secrets in source control, the configuration looks into [application settings](application-settings.yml#configure-application-settings) for a matching name in the configuration file. You might also choose to store your secrets in [Azure Key Vault](./key-vault-secrets.md).
 
 # [Microsoft Entra ID](#tab/aad)
 
@@ -91,6 +91,50 @@ To configure which accounts can sign in, see [Modify the accounts supported by a
 > [!NOTE]
 > While the configuration section for Microsoft Entra ID is `azureActiveDirectory`, the platform aliases this to `aad` in the URL's for login, logout and purging user information. Refer to the [authentication and authorization](authentication-authorization.yml) section for more information.
 
+### Custom certificate
+
+Use the following steps to add a custom certificate to your Microsoft Entra ID app registration.
+
+1. If it isn't already, upload your certificate to a Microsoft Key Vault.
+
+1. Add a managed identity on your Static Web App.
+
+    For user assigned managed identities, set `keyVaultReferenceIdentity` property on your static site object to the `resourceId` of the user assigned managed identity.
+
+    Skip this step if your managed identity is system assigned.
+
+1. Grant the managed identity the following access policies:
+
+    - *Secrets*: **Get/List**
+    - *Certificates*: **Get/List**
+
+1. Update the auth config section of the `azureActiveDirectory` configuration section with a `clientSecretCertificateKeyVaultReference` value as shown in the following example:
+
+    ```json
+    {
+      "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": "*"
+            }
+          }
+        }
+      }
+    }
+    ```
+
+    Make sure to replace your values in for the placeholders surrounded by `<>`.
+
+    In the secret URI, specify the key vault name and certificate name. If you want to pin to a version, include the certificate version, otherwise omit the version to allow the runtime to select the newest version of the certificate.
+
+    Set `clientSecretCertificateThumbprint` equal to `*` to always pull the latest version of the certificates thumbprint.
+
 # [Apple](#tab/apple)
 
 To create the registration, begin by creating the following [application settings](application-settings.yml):
@@ -233,7 +277,7 @@ For more information on how to configure Twitter as an authentication provider,
 
 # [OpenID Connect](#tab/openid-connect)
 
-You can configure Azure Static Web Apps to use a custom authentication provider that adheres to the [OpenID Connect (OIDC) specification](https://openid.net/connect/). The following steps are required to use an custom OIDC provider.
+You can configure Azure Static Web Apps to use a custom authentication provider that adheres to the [OpenID Connect (OIDC) specification](https://openid.net/connect/). The following steps are required to use a custom OIDC provider.
 
 - One or more OIDC providers are allowed.
 - Each provider must have a unique name in the configuration.
@@ -250,7 +294,7 @@ Once the application is registered with the identity provider, create the follow
 | `MY_PROVIDER_CLIENT_ID` | The client ID generated by the authentication provider for your static web app. |
 | `MY_PROVIDER_CLIENT_SECRET` | The client secret generated by the authentication provider's custom registration for your static web app. |
 
-If you register additional providers, each one needs an associated client ID and client secret store in application settings.
+If you register other providers, each one needs an associated client ID and client secret store in application settings.
 
 > [!IMPORTANT]
 > Application secrets are sensitive security credentials. Do not share this secret with anyone, distribute it within a client application, or check into source control.
@@ -290,7 +334,7 @@ Once you have the registration credentials, use the following steps to create a
 
   - The provider name, `myProvider` in this example, is the unique identifier used by Azure Static Web Apps.
   - Make sure to replace `<PROVIDER_ISSUER_URL>` with the path to the _Issuer URL_ of the provider.
-  - The `login` object allows you to provide values for: custom scopes, login parameters, or custom claims.
+  - The `login` object allows you to provide values for: custom scopes, log in parameters, or custom claims.
 
 ---
 
@@ -303,7 +347,7 @@ Identity providers require a redirect URL to complete the login or logout reques
 | Login  | `https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback`  |
 | Logout | `https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback` |
 
-If you are using Microsoft Entra ID, use `aad` as the value for the `<PROVIDER_NAME_IN_CONFIG>` placeholder.
+If you're using Microsoft Entra ID, use `aad` as the value for the `<PROVIDER_NAME_IN_CONFIG>` placeholder.
 
 > [!Note]
 > These URLs are provided by Azure Static Web Apps to receive the response from the authentication provider, you don't need to create pages at these routes.
@@ -319,7 +363,7 @@ To use a custom identity provider, use the following URL patterns.
 | User details       | `/.auth/me`                              |
 | Purge user details | `/.auth/purge/<PROVIDER_NAME_IN_CONFIG>` |
 
-If you are using Microsoft Entra ID, use `aad` as the value for the `<PROVIDER_NAME_IN_CONFIG>` placeholder.
+If you're using Microsoft Entra ID, use `aad` as the value for the `<PROVIDER_NAME_IN_CONFIG>` placeholder.
 
 ## Manage roles
 
@@ -350,7 +394,7 @@ Invitations are specific to individual authorization-providers, so consider the
 | GitHub                 | username         |
 | Twitter                | username         |
 
-Do the following steps to create an invitation.
+Use the following steps to create an invitation.
 
 1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
 2. Under _Settings_, select **Role Management**.
@@ -391,7 +435,7 @@ When the user selects the link in the invitation, they're prompted to sign in wi
 As you remove a user, keep in mind the following items:
 
 - Removing a user invalidates their permissions.
-- Worldwide propagation may take a few minutes.
+- Worldwide propagation might take a few minutes.
 - If the user is added back to the app, the [`userId` changes](user-information.md).
 
 # [Function (preview)](#tab/function)