Autenticazione personalizzata in App Web statiche di Azure

Articolo
07/26/2024

App Web statiche di Azure fornisce un'autenticazione gestita che usa le registrazioni dei provider gestite da Azure. Per consentire una maggiore flessibilità sulla registrazione, è possibile eseguire l'override delle impostazioni predefinite con una registrazione personalizzata.

L'autenticazione personalizzata consente anche di configurare provider personalizzati che supportano OpenID Connect. Questa configurazione consente la registrazione di più provider esterni.
L'uso di registrazioni personalizzate disabilita tutti i provider preconfigurati.

Nota

L'autenticazione personalizzata è disponibile solo nel piano Standard di App Web statiche di Azure.

Configurare un provider di identità personalizzato

I provider di identità personalizzati vengono configurati nella sezione auth del file di configurazione.

Per evitare di inserire segreti nel controllo del codice sorgente, la configurazione cerca nelle impostazioni dell'applicazione un nome corrispondente nel file di configurazione. È anche possibile scegliere di archiviare i segreti in Azure Key Vault.

Per creare la registrazione, iniziare creando le impostazioni dell'applicazione seguenti:

Nome dell'impostazione	Valore
`AZURE_CLIENT_ID`	ID applicazione (client) per la registrazione dell'app Microsoft Entra.
`AZURE_CLIENT_SECRET_APP_SETTING_NAME	Nome dell'impostazione dell'applicazione che contiene il segreto client per la registrazione dell'app Microsoft Entra.

Usare quindi l'esempio seguente per configurare il provider nel file di configurazione.

I provider Microsoft Entra sono disponibili in due versioni diverse. La versione 1 definisce in modo esplicito l'oggetto userDetailsClaim, che consente al payload di restituire le informazioni dell'utente. La versione 2, invece, restituisce le informazioni dell'utente per impostazione predefinita ed è indicata con v2.0 nell'URL openIdIssuer.

Microsoft Entra versione 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"
        }
      }
    }
  }
}

Assicurarsi di sostituire <TENANT_ID> con l'ID tenant di Microsoft Entra.

Microsoft Entra versione 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"
        }
      }
    }
  }
}

Assicurarsi di sostituire <TENANT_ID> con l'ID tenant di Microsoft Entra.

Per altre informazioni su come configurare Microsoft Entra ID, vedere la documentazione relativa all'autenticazione/autorizzazione del servizio app sull'uso di una registrazione esistente.

Per configurare gli account che possono accedere, vedere Modificare gli account supportati da un'applicazione e Limitare l'app Microsoft Entra a un gruppo di utenti in un tenant di Microsoft Entra.

Nota

Sebbene la sezione di configurazione per Microsoft Entra ID sia azureActiveDirectory, la piattaforma ne associa l'alias a aad negli URL per l'accesso, la disconnessione e l'eliminazione delle informazioni dell'utente. Per altre informazioni, vedere la sezione Autenticazione e autorizzazione.

Certificato personalizzato

Seguire questa procedura per aggiungere un certificato personalizzato alla registrazione dell'app Microsoft Entra ID.

Se questa operazione non è stata ancora eseguita, caricare il certificato in un Microsoft Key Vault.
Aggiungere un'identità gestita nell'app Web statica.

Per le identità gestite assegnate dall'utente, impostare la proprietà keyVaultReferenceIdentity nell'oggetto del sito statico sul valore resourceId dell'identità gestita assegnata dall'utente.

Ignorare questo passaggio se l'identità gestita è assegnata dal sistema.
Concedere all'identità gestita i criteri di accesso seguenti:
- Segreti: Get/List
- Certificati: Get/List
Aggiornare la sezione di configurazione dell'autenticazione della sezione di configurazione azureActiveDirectory con un valore clientSecretCertificateKeyVaultReference, come illustrato nell'esempio seguente:
```
{
  "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": "*"
        }
      }
    }
  }
}
```
Assicurarsi di sostituire i segnaposto racchiusi tra <> con i propri valori.

Nell'URI del segreto specificare il nome dell'insieme di credenziali delle chiavi e il nome del certificato. Se si vuole aggiungere a una versione, includere la versione del certificato, altrimenti omettere la versione per consentire al runtime di selezionare la versione più recente del certificato.

Impostare clientSecretCertificateThumbprint uguale a * per eseguire sempre il pull della versione più recente dell'identificazione personale dei certificati.

Per creare la registrazione, iniziare creando le impostazioni dell'applicazione seguenti:

Nome dell'impostazione	Valore
`APPLE_CLIENT_ID`	ID client Apple.
`APPLE_CLIENT_SECRET_APP_SETTING_NAME`	Nome dell'impostazione dell'applicazione che contiene il segreto client Apple.

Usare quindi l'esempio seguente per configurare il provider nel file di configurazione.

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

Per altre informazioni su come configurare Apple come provider di autenticazione, vedere la documentazione relativa all'autenticazione/autorizzazione del servizio app.

Per creare la registrazione, iniziare creando le impostazioni dell'applicazione seguenti:

Nome dell'impostazione	Valore
`FACEBOOK_APP_ID`	ID applicazione Facebook.
`FACEBOOK_APP_SECRET_APP_SETTING_NAME`	Nome dell'impostazione dell'applicazione che contiene il segreto dell'applicazione Facebook.

Usare quindi l'esempio seguente per configurare il provider nel file di configurazione.

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

Per altre informazioni su come configurare Facebook come provider di autenticazione, vedere la documentazione relativa all'autenticazione/autorizzazione del servizio app.

Per creare la registrazione, iniziare creando le impostazioni dell'applicazione seguenti:

Nome dell'impostazione	Valore
`GITHUB_CLIENT_ID`	ID client GitHub.
`GITHUB_CLIENT_SECRET_APP_SETTING_NAME`	Nome dell'impostazione dell'applicazione che contiene il segreto client GitHub.

Usare quindi l'esempio seguente per configurare il provider nel file di configurazione.

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

Per creare la registrazione, iniziare creando le impostazioni dell'applicazione seguenti:

Nome dell'impostazione	Valore
`GOOGLE_CLIENT_ID`	ID client Google.
`GOOGLE_CLIENT_SECRET_APP_SETTING_NAME`	Nome dell'impostazione dell'applicazione che contiene il segreto client Google.

Usare quindi l'esempio seguente per configurare il provider nel file di configurazione.

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

Per altre informazioni su come configurare Google come provider di autenticazione, vedere la documentazione relativa all'autenticazione/autorizzazione del servizio app.

Per creare la registrazione, iniziare creando le impostazioni dell'applicazione seguenti:

Nome dell'impostazione	Valore
`X_CONSUMER_KEY`	Chiave consumer X.
`X_CONSUMER_SECRET_APP_SETTING_NAME`	Nome dell'impostazione dell'applicazione che contiene il segreto consumer X.

Usare quindi l'esempio seguente per configurare il provider nel file di configurazione.

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

Per altre informazioni su come configurare X come provider di autenticazione, vedere la documentazione relativa all'autenticazione/autorizzazione di servizio app.

È possibile configurare App Web statiche di Azure per l'uso di un provider di autenticazione personalizzato conforme alla specifica OpenID Connect (OIDC). Per usare un provider OIDC personalizzato, sono necessari i passaggi seguenti.

Sono consentiti uno o più provider OIDC.
Ogni provider deve avere un nome univoco nella configurazione.
Solo un provider può fungere da destinazione di reindirizzamento predefinita.

Registrare l'applicazione con il provider di identità

È necessario registrare i dettagli dell'applicazione con un provider di identità. Rivolgersi al provider per quanto riguarda i passaggi necessari per generare un ID client e un segreto client per l'applicazione.

Dopo aver registrato l'applicazione con il provider di identità, creare i segreti dell'applicazione seguenti nelle impostazioni dell'applicazione dell'app Web statica:

Nome dell'impostazione	Valore
`MY_PROVIDER_CLIENT_ID`	ID client generato dal provider di autenticazione per l'app Web statica.
`MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME`	Nome dell'impostazione dell'applicazione che contiene il segreto client generato dalla registrazione personalizzata del provider di autenticazione per l'app Web statica.

Se si registrano altri provider, ognuno di essi deve avere un ID client e un archivio segreti client associati nelle impostazioni dell'applicazione.

Importante

I segreti dell'applicazione sono credenziali di sicurezza sensibili. Non condividerli con altri, non distribuirli all'interno di un'applicazione client né archiviarli nel controllo del codice sorgente.

Dopo aver ottenuto le credenziali di registrazione, seguire questa procedura per creare una registrazione personalizzata.

Sono necessari i metadati OpenID Connect per il provider. Queste informazioni vengono spesso esposte tramite un documento di metadati di configurazione, ovvero l'URL dell'autorità di certificazione del provider con il suffisso /.well-known/openid-configuration. Raccogliere questo URL di configurazione.

Aggiungere una sezione auth del file di configurazione con un blocco di configurazione per i provider OIDC e la definizione del provider.

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

Il nome del provider, myProvider in questo esempio, è l'identificatore univoco usato da App Web statiche di Azure.
Assicurarsi di sostituire <PROVIDER_ISSUER_URL> con il percorso dell'URL dell'autorità di certificazione del provider.
L'oggetto login consente di specificare valori per: ambiti personalizzati, parametri di accesso o attestazioni personalizzate.

Callback di autenticazione

I provider di identità richiedono un URL di reindirizzamento per completare la richiesta di accesso o disconnessione. La maggior parte dei provider richiede l'aggiunta degli URL di callback a un elenco di elementi consentiti. Gli endpoint seguenti sono disponibili come destinazioni di reindirizzamento.

Type	Modello URL
Account di accesso	`https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback`
Disconnessione	`https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback`

Se si usa Microsoft Entra ID, usare aad come valore per il segnaposto <PROVIDER_NAME_IN_CONFIG>.

Nota

Questi URL vengono forniti da App Web statiche di Azure per ricevere la risposta dal provider di autenticazione; non è necessario creare pagine in queste route.

Per usare un provider di identità personalizzato, usare i modelli di URL seguenti.

Azione	Modello
Account di accesso	`/.auth/login/<PROVIDER_NAME_IN_CONFIG>`
Disconnessione	`/.auth/logout`
Dettagli utente	`/.auth/me`
Eliminazione dei dettagli utente	`/.auth/purge/<PROVIDER_NAME_IN_CONFIG>`

Se si usa Microsoft Entra ID, usare aad come valore per il segnaposto <PROVIDER_NAME_IN_CONFIG>.

Gestire i ruoli

Ogni utente che accede a un'app Web statica appartiene a uno o più ruoli. Esistono due ruoli predefiniti a cui gli utenti possono appartenere:

anonimo: tutti gli utenti appartengono automaticamente al ruolo anonimo.
autenticato: tutti gli utenti connessi appartengono al ruolo autenticato.

Oltre ai ruoli predefiniti, è possibile assegnare ruoli personalizzati agli utenti e farvi riferimento nel file staticwebapp.config.json.

Inviti
Funzione (anteprima)

Aggiungere un utente a un ruolo

Per aggiungere un utente a un ruolo, si generano inviti che consentono di associare gli utenti a ruoli specifici. I ruoli vengono definiti e gestiti nel file staticwebapp.config.json.

Creazione di un invito

Gli inviti sono specifici dei singoli provider di autorizzazioni, quindi occorre valutare le esigenze dell'app quando si selezionano i provider da supportare. Alcuni provider espongono l'indirizzo di posta elettronica di un utente, mentre altri forniscono solo il nome utente del sito.

Provider di autorizzazione	Elementi esposti
Microsoft Entra ID	Indirizzo di posta elettronica
GitHub	username
X	username

Per creare un invito, seguire questa procedura.

Nel portale di Azure passare a una risorsa di App Web statiche.
In Impostazioni selezionare Gestione ruoli.
Selezionare Invita.
Selezionare un Provider di autorizzazione dall'elenco di opzioni.
Aggiungere il nome utente o l'indirizzo di posta elettronica del destinatario nella casella Dettagli dell'invitato.
- Per GitHub e X immettere il nome utente. Per tutti gli altri, immettere l'indirizzo di posta elettronica del destinatario.
Selezionare il dominio del sito statico dal menu a discesa Dominio.
- Il dominio selezionato è il dominio che verrà visualizzato nell'invito. Se al sito è associato un dominio personalizzato, scegliere il dominio personalizzato.
Aggiungere un elenco delimitato da virgole di nomi di ruolo nella casella Ruolo.
Immettere il numero massimo di ore di validità per l'invito.
- Il limite massimo consentito è 168 ore, ovvero sette giorni.
Selezionare Genera.
Copiare il collegamento dalla casella Collegamento di invito.
Inviare il collegamento di invito tramite posta elettronica all'utente a cui si vuole concedere l'accesso.

Quando l'utente seleziona il collegamento nell'invito, gli viene richiesto di accedere con l'account corrispondente. Una volta eseguito correttamente l'accesso, l'utente viene associato ai ruoli selezionati.

Attenzione

Assicurarsi che le regole di route non siano in conflitto con i provider di autenticazione selezionati. Il blocco di un provider con una regola di route impedisce agli utenti di accettare gli inviti.

Aggiornare le assegnazioni di ruolo

Nel portale di Azure passare a una risorsa di App Web statiche.
In Impostazioni selezionare Gestione ruoli.
Selezionare l'utente nell'elenco.
Modificare l'elenco dei ruoli nella casella Ruolo.
Selezionare Aggiorna.

Rimuovi utente

Nel portale di Azure passare a una risorsa di App Web statiche.
In Impostazioni selezionare Gestione ruoli.
Individuare l'utente nell'elenco.
Selezionare la casella di controllo sulla riga dell'utente.
Selezionare Elimina.

Quando si rimuove un utente, tenere presente quanto segue:

La rimozione di un utente invalida le autorizzazioni associate.
La propagazione in tutto il mondo potrebbe richiedere alcuni minuti.
Se l'utente viene aggiunto nuovamente all'app, il valore di userId verrà modificato.

Anziché usare il sistema di inviti predefinito, è possibile usare una funzione serverless per assegnare i ruoli agli utenti a livello di codice al momento dell'accesso.

Per assegnare ruoli personalizzati in una funzione, è possibile definire una funzione API che viene chiamata automaticamente ogni volta che un utente esegue correttamente l'autenticazione con un provider di identità. Alla funzione vengono passate le informazioni dell'utente dal provider. Deve restituire un elenco di ruoli personalizzati assegnati all'utente.

Gli usi di esempio di questa funzione includono:

Eseguire una query su un database per determinare quali ruoli devono essere assegnati a un utente
Chiamare l'API Microsoft Graph per determinare i ruoli di un utente in base all'appartenenza al gruppo di Active Directory
Determinare i ruoli di un utente in base alle attestazioni restituite dal provider di identità

Nota

La possibilità di assegnare ruoli tramite una funzione è disponibile solo quando è configurata l'autenticazione personalizzata.

Quando questa funzionalità è abilitata, tutti i ruoli assegnati tramite il sistema di inviti predefinito vengono ignorati.

Configurare una funzione per l'assegnazione dei ruoli

Per configurare App Web statiche in modo da usare una funzione API come funzione di assegnazione di ruolo, aggiungere una proprietà rolesSource alla sezione auth del file di configurazione dell'app. Il valore della proprietà rolesSource è il percorso della funzione API.

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

Nota

Una volta configurata, la funzione di assegnazione di ruolo non è più accessibile da richieste HTTP esterne.

Creare una funzione per l'assegnazione dei ruoli

Dopo aver definito la proprietà rolesSource nella configurazione dell'app, aggiungere una funzione API nell'app Web statica nel percorso specificato. È possibile usare un'app per le funzioni gestita o un'app per le funzioni personale.

Ogni volta che un utente esegue correttamente l'autenticazione con un provider di identità, il metodo POST chiama la funzione specificata. La funzione passa un oggetto JSON nel corpo della richiesta che contiene le informazioni dell'utente provenienti dal provider. Per alcuni provider di identità, le informazioni dell'utente includono anche un oggetto accessToken che la funzione può usare per effettuare chiamate API usando l'identità dell'utente.

Vedere il payload di esempio seguente da Microsoft Entra ID:

{
  "identityProvider": "aad",
  "userId": "72137ad3-ae00-42b5-8d54-aacb38576d76",
  "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": "72137ad3-ae00-42b5-8d54-aacb38576d76"
      },
      {
          "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 funzione può usare le informazioni dell'utente per determinare quali ruoli assegnare all'utente. Deve restituire una risposta HTTP 200 con un corpo JSON contenente un elenco di nomi di ruolo personalizzati da assegnare all'utente.

Ad esempio, per assegnare all'utente i ruoli Reader e Contributor, restituire la risposta seguente:

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

Se non si desidera assegnare altri ruoli all'utente, restituire una matrice roles vuota.

Per altre informazioni, vedere Esercitazione: Assegnare ruoli personalizzati con una funzione e Microsoft Graph.

Passaggi successivi

Impostare i ruoli utente a livello di codice

Condividi tramite

Autenticazione personalizzata in App Web statiche di Azure

Configurare un provider di identità personalizzato

Microsoft Entra versione 1

Microsoft Entra versione 2

Certificato personalizzato

Registrare l'applicazione con il provider di identità

Callback di autenticazione

Gestire i ruoli

Aggiungere un utente a un ruolo

Creazione di un invito

Aggiornare le assegnazioni di ruolo

Rimuovi utente

Configurare una funzione per l'assegnazione dei ruoli

Creare una funzione per l'assegnazione dei ruoli

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Autenticazione personalizzata in App Web statiche di Azure

Configurare un provider di identità personalizzato

Microsoft Entra versione 1

Microsoft Entra versione 2

Certificato personalizzato

Callback di autenticazione

Accesso, disconnessione e dettagli utente

Gestire i ruoli

Aggiungere un utente a un ruolo

Creazione di un invito

Aggiornare le assegnazioni di ruolo

Rimuovi utente

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive