Autenticación personalizada en Azure Static Web Apps

Azure Static Web Apps proporciona autenticación administrada que usa registros de proveedor administrados por Azure. Para habilitar más flexibilidad sobre el registro, puede reemplazar los valores predeterminados por un registro personalizado.

• La autenticación personalizada también le permite configurar proveedores personalizados que admitan OpenID Connect. Esta configuración permite el registro de varios proveedores externos.

• El uso de registros personalizados deshabilita todos los proveedores preconfigurados.

Nota:

La autenticación personalizada solo está disponible en el plan Estándar de Azure Static Web Apps.

Configuración de un proveedor de identidades personalizados

Los proveedores de identidad personalizados se configuran en la sección auth del archivo de configuración.

Para evitar colocar secretos en el control de código fuente, la configuración busca en la configuración de la aplicación un nombre coincidente en el archivo de configuración. También puede optar por almacenar los secretos en Azure Key Vault.

Microsoft Entra ID

Para crear el registro, empiece por crear la siguiente configuración de la aplicación:

Nombre de la opción de configuración	Valor
AZURE_CLIENT_ID	Id. de aplicación (cliente) para el registro de aplicaciones de Microsoft Entra.
`AZURE_CLIENT_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de cliente para el registro de aplicaciones de Microsoft Entra.

Use el ejemplo siguiente para configurar el proveedor en el archivo de configuración.

Los proveedores de Microsoft Entra están disponibles en dos versiones diferentes. La versión 1 define explícitamente userDetailsClaim, que permite que la carga devuelva información del usuario. Por el contrario, la versión 2 devuelve información del usuario de forma predeterminada y la designa con v2.0 en la dirección URL openIdIssuer.

Microsoft Entra versión 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"
        }
      }
    }
  }
}

Asegúrese de reemplazar <TENANT_ID> por el id. de inquilino de Microsoft Entra.

Microsoft Entra versión 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"
        }
      }
    }
  }
}

Asegúrese de reemplazar <TENANT_ID> por el id. de inquilino de Microsoft Entra.

Para más información sobre cómo configurar Microsoft Entra ID, consulte la documentación sobre autenticación y autorización de App Service relacionada con el uso de un registro existente.

Para configurar qué cuentas pueden iniciar sesión, consulte Modificación de las cuentas compatibles con una aplicación y Restricción de la aplicación de Microsoft Entra a un conjunto de usuarios de un inquilino de Microsoft Entra.

Nota:

Aunque la sección de configuración de Microsoft Entra ID es azureActiveDirectory, la plataforma lo asocia a aad en las direcciones URL para iniciar sesión, cerrar sesión y purgar información del usuario. Consulte la sección de autenticación y autorización para obtener más información.

Certificado personalizado

Siga estos pasos para agregar un certificado personalizado al registro de la aplicación Microsoft Entra ID.

1. Si el certificado aún no está cargado, cárguelo en un almacén de claves de Microsoft.

2. Agregue una identidad administrada en la aplicación web estática.

   En el caso de las identidades administradas asignadas por el usuario, establezca la propiedad keyVaultReferenceIdentity en el objeto de sitio estático al resourceId de la identidad administrada asignada por el usuario.

   Omita este paso si la identidad administrada está asignada por el sistema.

3. Conceda a la identidad administrada las siguientes directivas de acceso:

   • Secretos: Get/List
   • Certificados: Get/List

4. Actualice la sección de configuración de autenticación de la sección de configuración azureActiveDirectory con un valor clientSecretCertificateKeyVaultReference como se muestra en el ejemplo siguiente:

   {
     "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": "*"
           }
         }
       }
     }
   }
   

   Asegúrese de reemplazar los valores para los marcadores de posición rodeados por <>.

   En el identificador URI del secreto, especifique el nombre del almacén de claves y el nombre del certificado. Si desea anclar a una versión, incluya la versión del certificado; de lo contrario, omita la versión para permitir que el entorno de ejecución seleccione la versión más reciente del certificado.

   Establezca clientSecretCertificateThumbprint igual a * para extraer siempre la versión más reciente de la huella digital de los certificados.

Manzana

Para crear el registro, empiece por crear la siguiente configuración de la aplicación:

Nombre de la opción de configuración	Valor
APPLE_CLIENT_ID	Identificador de cliente de Apple
APPLE_CLIENT_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de cliente de Apple.

Use el ejemplo siguiente para configurar el proveedor en el archivo de configuración.

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

Para más información sobre cómo configurar Apple como proveedor de autenticación, consulte la documentación sobre autenticación y autorización de App Service.

Facebook

Para crear el registro, empiece por crear la siguiente configuración de la aplicación:

Nombre de la opción de configuración	Valor
FACEBOOK_APP_ID	Identificador de la aplicación Facebook
FACEBOOK_APP_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de la aplicación de Facebook.

Use el ejemplo siguiente para configurar el proveedor en el archivo de configuración.

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

Para más información sobre cómo configurar Facebook como proveedor de autenticación, consulte la documentación sobre autenticación y autorización de App Service.

GitHub

Para crear el registro, empiece por crear la siguiente configuración de la aplicación:

Nombre de la opción de configuración	Valor
GITHUB_CLIENT_ID	Identificador de cliente de GitHub
GITHUB_CLIENT_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de cliente de GitHub.

Use el ejemplo siguiente para configurar el proveedor en el archivo de configuración.

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

Google

Para crear el registro, empiece por crear la siguiente configuración de la aplicación:

Nombre de la opción de configuración	Valor
GOOGLE_CLIENT_ID	Identificador de cliente de Google
GOOGLE_CLIENT_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de cliente de Google.

Use el ejemplo siguiente para configurar el proveedor en el archivo de configuración.

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

Para más información sobre cómo configurar Google como proveedor de autenticación, consulte la documentación sobre autenticación y autorización de App Service.

X

Para crear el registro, empiece por crear la siguiente configuración de la aplicación:

Nombre de la opción de configuración	Valor
X_CONSUMER_KEY	Clave de consumidor de X.
X_CONSUMER_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de consumidor de X.

Use el ejemplo siguiente para configurar el proveedor en el archivo de configuración.

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

Para más información sobre cómo configurar X como proveedor de autenticación, consulte la documentación sobre autenticación y autorización de App Service.

OpenID Connect

Puede configurar Azure Static Web Apps para usar un proveedor de autenticación personalizado que cumpla la especificación OpenID Connect (OIDC). Los pasos siguientes son necesarios para usar un proveedor de OIDC personalizado.

• Se permiten uno o varios proveedores de OIDC.
• Cada proveedor debe tener un nombre único en la configuración.
• Solo un proveedor puede actuar como destino de redirección predeterminado.

Registro de la aplicación con el proveedor de identidades

Es necesario registrar los detalles de la aplicación con un proveedor de identidades. Consulte con el proveedor los pasos necesarios para generar un identificador de cliente y un secreto de cliente para la aplicación.

Una vez que se ha registrado la aplicación con el proveedor de identidades, cree los siguientes secretos de aplicación en la configuración de la aplicación de la aplicación web estática:

Nombre de la opción de configuración	Valor
MY_PROVIDER_CLIENT_ID	Identificador de cliente generado por el proveedor de autenticación de la aplicación web estática
MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME	Nombre de la configuración de la aplicación que contiene el secreto de cliente generado por el registro personalizado del proveedor de autenticación para la aplicación web estática.

Si registra otros proveedores, cada uno de ellos necesita un id. de cliente asociado y un almacén de secretos de cliente en la configuración de la aplicación.

Importante

Los secretos de aplicación son credenciales de seguridad confidenciales. No comparta este secreto con nadie, distribúyalo dentro de una aplicación cliente o insértelo en el control de código fuente.

Una vez que tenga las credenciales de registro, siga estos pasos para crear un registro personalizado.

1. Necesita los metadatos de OpenID Connect para el proveedor. A menudo, esta información se expone a través de un documento de metadatos de configuración, que es la dirección URL del emisor del proveedor con el sufijo /.well-known/openid-configuration. Obtenga esta dirección URL de configuración.

2. Agregue una sección auth del archivo de configuración con un bloque de configuración para los proveedores de OIDC y la definición del proveedor.

   {
     "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": []
             }
           }
         }
       }
     }
   }
   

• El nombre del proveedor, myProvider en este ejemplo, es el identificador único que usa Azure Static Web Apps.
• Recuerde reemplazar <PROVIDER_ISSUER_URL> por la ruta de acceso a la URL del emisor del proveedor.
• El objeto login le permite proporcionar valores para: ámbitos personalizados, parámetros de inicio de sesión o notificaciones personalizadas.

Devoluciones de llamada de autenticación

Los proveedores de identidad personalizados requieren una dirección URL de redireccionamiento para completar la solicitud de inicio o cierre de sesión. La mayoría de los proveedores requieren que agregue las direcciones URL de devolución de llamada a una lista de permitidos. Los siguientes puntos de conexión están disponibles como destinos de redirección.

Tipo	Patrón de URL
Iniciar sesión	https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback
Logout	https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback

Si usa Microsoft Entra ID, use aad como valor para el marcador de posición <PROVIDER_NAME_IN_CONFIG>.

Nota:

Estas direcciones URL las proporciona Azure Static Web Apps para recibir la respuesta del proveedor de autenticación, no es necesario que cree páginas en estas rutas.

Inicio de sesión, cierre de sesión y detalles del usuario

Para usar un proveedor de identidad personalizado, use los siguientes patrones de dirección URL.

Action	Patrón
Iniciar sesión	/.auth/login/<PROVIDER_NAME_IN_CONFIG>
Logout	/.auth/logout
Detalles de usuario	/.auth/me
Purga de los detalles del usuario	/.auth/purge/<PROVIDER_NAME_IN_CONFIG>

Si usa Microsoft Entra ID, use aad como valor para el marcador de posición <PROVIDER_NAME_IN_CONFIG>.

Administrar roles

Cada usuario que tiene acceso a una aplicación web estática pertenece a uno o varios roles. Existen dos roles integrados a los que los usuarios pueden pertenecer:

• anónimo: todos los usuarios pertenecen automáticamente al rol anónimo.
• autenticado: todos los usuarios que inician sesión pertenecen al rol autenticado.

Además de los roles integrados, puede crear asignar roles personalizados a los usuarios y hacer referencia a ellos en el archivo staticwebapp.config.json.

Invitaciones

Adición de un usuario a un rol

Para agregar un usuario a un rol, genere invitaciones que le permitan asociar usuarios a roles concretos. Los roles se definen y mantienen en el archivo staticwebapp.config.json.

Crear una invitación

Las invitaciones son específicas de los proveedores de autorización individuales; por lo tanto, tenga en cuenta las necesidades de la aplicación al seleccionar los proveedores que se van a admitir. Algunos proveedores exponen la dirección de correo electrónico de los usuarios, mientras que otros solo proporcionan el nombre de usuario del sitio.

Proveedor de autorización	Expone
Microsoft Entra ID	Dirección de correo electrónico
GitHub	username
X	username

Use estos pasos para crear una invitación.

1. Vaya a un recurso de Static Web Apps en Azure Portal.
2. En Configuración, seleccione Administración de roles.
3. Seleccione Invitar.
4. Seleccione un Proveedor de autorización de la lista de opciones.
5. Agregue el nombre de usuario o la dirección de correo electrónico del destinatario en el cuadro Invitee details (Detalles del invitado).
   • En GitHub y X, escriba el nombre de usuario. Para todos los demás, escriba la dirección de correo electrónico del destinatario.
6. Seleccione el dominio del sitio estático del menú desplegable Dominio.
   • El dominio que seleccione será el dominio que aparezca en la invitación. Si tiene un dominio personalizado asociado a su sitio, elíjalo.
7. Agregue una lista separada por comas de nombres de rol en el cuadro Rol.
8. Especifique el número máximo de horas que desea que la invitación siga siendo válida.
   • El límite máximo posible es 168 horas, es decir, siete días.
9. Seleccione Generar.
10. Copie el vínculo del cuadro Vínculo de invitación.
11. Envíe el vínculo de invitación por correo electrónico al usuario al que va a conceder acceso.

Cuando el usuario seleccione el vínculo de la invitación, se le solicitará que inicie sesión con su cuenta correspondiente. Con la sesión iniciada correctamente, los roles seleccionados se asocian al usuario.

Precaución

Asegúrese de que las reglas de ruta no entren en conflicto con los proveedores de autenticación seleccionados. Bloquear un proveedor con una regla de ruta impide a los usuarios aceptar invitaciones.

Actualización de las asignaciones de roles

1. Vaya a un recurso de Static Web Apps en Azure Portal.
2. En Configuración, seleccione Administración de roles.
3. Seleccione el usuario en la lista.
4. Edite la lista de roles en el cuadro Rol.
5. Seleccione Actualizar.

Quitar usuario

1. Vaya a un recurso de Static Web Apps en Azure Portal.
2. En Configuración, seleccione Administración de roles.
3. Busque el usuario en la lista.
4. Active la casilla en la fila del usuario.
5. Seleccione Eliminar.

Al quitar un usuario, tenga en cuenta los elementos siguientes:

• Al quitar un usuario, se invalidan sus permisos.
• La propagación mundial puede tardar unos minutos.
• Si se vuelve a agregar el usuario a la aplicación, userId cambia.

Función (versión preliminar)

En lugar de usar el sistema de invitaciones integrado, puede usar una función sin servidor para asignar roles a los usuarios mediante programación cuando inicien sesión.

Para asignar roles personalizados en una función, puede definir una función de API a la que se llama automáticamente después de cada vez que un usuario se autentica correctamente con un proveedor de identidades. A la función se le pasa la información del usuario del proveedor. Debe devolver una lista de roles personalizados asignados al usuario.

Entre los usos de ejemplo de esta función se incluyen los siguientes:

• Consulta de una base de datos para determinar qué roles se deben asignar a un usuario
• Llame a Microsoft Graph API para determinar los roles de un usuario en función de su pertenencia a un grupo de Active Directory
• Determinación de los roles de un usuario en función de las notificaciones devueltas por el proveedor de identidades

Nota:

La capacidad de asignar roles a través de una función solo está disponible cuando se configura la autenticación personalizada.

Cuando esta característica está habilitada, se omiten los roles asignados a través del sistema de invitaciones integrado.

Configuración de una función para asignar roles

Para configurar Static Web Apps con el fin de que use una función de API como función de asignación de roles, agregue una propiedad rolesSource a la sección auth del archivo de configuración de la aplicación. El valor de la propiedad rolesSource es la ruta a la función de API.

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

Nota:

Una vez configurada, las solicitudes HTTP externas ya no pueden acceder a la función de asignación de roles.

Creación de una función para asignar roles

Después de definir la propiedad rolesSource en la configuración de la aplicación, agregue una función de API en la aplicación web estática en la ruta de acceso especificada. Puede usar una aplicación de función administrada o traer su propia aplicación de funciones.

Cada vez que un usuario se autentica correctamente con un proveedor de identidades, el método POST llama a la función especificada. A la función pasa un objeto JSON en el cuerpo de la solicitud que contiene la información del usuario procedente del proveedor. Para algunos proveedores de identidades, la información del usuario también incluye un objeto accessToken que la función puede usar para realizar llamadas API mediante la identidad del usuario.

Consulte la siguiente carga de ejemplo de 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..."
}

La función puede usar la información del usuario para determinar qué roles asignar al usuario. Debe devolver una respuesta HTTP 200 con un cuerpo JSON que contenga una lista de nombres de rol personalizados que se asignarán al usuario.

Por ejemplo, para asignar el usuario a los roles Reader y Contributor, devuelva la siguiente respuesta:

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

Si no desea asignar más roles al usuario, devuelva una matriz roles vacía.

Para obtener más información, consulte Tutorial: asignación de roles personalizados con una función y Microsoft Graph.

Pasos siguientes

Administración de roles de usuario mediante programación