Questo esempio mostra come creare una API .NET 8, protetta da autenticazione integrata con Entra ID, e come chiamarla da una web part SPFx passando il contesto dell'utente usando le delegate permission.
Nella SharePoint Admin approvare i permessi dell'App Registration
Creare una App Registration in Entra ID
Andare in Entra ID sulla pagina delle App Registration creare una nuova app New registration e inserire:
Name / Display name = SgartSPFxDelegateDemoApp2
Supported accounnt type = Accounts in this organizational directory only (sgart only - Single tenant)
Redirect URI = vuoto
Premere Register
description Andare in Expose an API:
Premere Add
in Application ID URI accettare il default composto da api://<clientId>
Premere Save
Application ID URI
Attenzione non cambiare il formato del parametro Application ID URI, accettare il default.
Aggiungere uno scope con nome user_impersonation
Premere Add a scope
Scope name = user_impersonation
Who can consent? = Admins only
Admin consent display name = qualsiasi testo
Admin consent descripton = qualsiasi testo
State = Enabled
Premere Add scope
Scope
Il nome dello scope può essere scelto liberamente.
il nuovo scope sarà simile al seguente, salvo il guid che cambia ad ogni app registration api://78ed870c-xxxx-xxxx-xxxx-db65722fb9d4/user_impersonation Scope Per quanto rigurada le API permissions, mantenere il default Delegate / Microsoft Graph / User.Read'API permissions La registrazione della app è finita, copiarsi i valori di:
Display Name
Application (client) ID
Directory (tenant) ID
Application ID URI
Creare una API in .NET 8
Aprire Visual Studio 2022 e creare un nuovo progetto ASP.NET Core Web API con il framework .NET 8.
Gli step per configurare l'API autenticata sono:
In Program.cs aggiungere l'autenticazione
In Program.cs aggiungere il middleware Cors
in appsettings.json aggiungere la sezione AzureAd con i relativi parametri dell'app registration e il valore Cors
Creare un controller protetto con [Authorize]
C#: Programm.cs
var builder = WebApplication.CreateBuilder(args);
...
var settingsSection = builder.Configuration.GetSection(AppSettings.KEY_NAME);
builder.Services.Configure<AppSettings>(settingsSection);
...
builder.Services
.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
...
var app = builder.Build();
...
app.UseCors(policy =>
{
string[] urls = settingsSection.Get<AppSettings>()?.Cors ?? throw new Exception("appsettings Cors is null");
policy.WithOrigins(urls)
.AllowAnyMethod()
.AllowAnyHeader();
});
Nella SharePoint Admin approvare i permessi dell'App Registration
Questo è uno step molto importante.
Affinchè la chiamata alla custom API funzioni è necessario installare la web part nel tenant per approvare le permission specificate nel file package-solution.json.
Caricare il package nell'admin di SharePoint Online nell'App Cataloghttps://tenantName.sharepoint.com/sites/AppCatalog/_layouts/15/tenantAppCatalog.aspx/manageApps (sostituire TenantName).App Catalog fare l'upload del package nell'App Catalog, comparirà questo popup per abilitare la solutionEnable appsubito dopo compare un altro popup con l'avviso per approvare le autorizzazioniWarning permissionspremendo Go to API access page si va alla pagina API access, selezionare la permission e approvarlaAPI access approve A questo punto il setup di tutte le parti e completo, si può fare debug della soluzions SPFx con
DOS / Batch file
gulp serve
Nota: per il debug non è necessario fare l'upload della solution ad ogni modifica ne installare la app nel sito. L'installazione è servita solo per poter approvare le permission utilizzate. Si può tranquillamente utilizzare la pagina del workbench ( https://sgart.sharepoint.com/_layouts/15/workbench.aspx ) per le normali attività di debug.
Nei passaggi precedenti, ho sottolineato che, nella creazione della App Registration, il parametro Application ID Uri non doveva essere modificato rispetto al default proposto.
Nel claims che viene passato all'API non ci sono le informazioni relative ai gruppi di appartenenza.
Se dovessero servire, si può modificare l'app registration andando in Token configuration, Add groups claim. Qui configurare la tipologia di gruppi che servono e premere AddGroups
Le informazioni saranno disponibili dopo pochi secondi facendo refresh della pagina.
Le informazioni dei gruppi, presenti nel claims utente, saranno tipo questi:
ovvero con il guid del gruppo, che è l'identificativo univoco del gruppo, non il nome.
Ridurre il numero di gruppi
Se i gruppi sono molti, e si vuole includere nel claims solo un sottoinsieme necessari per l'applicativo, si può procedere in questo modo.
In Token configuration / Add groups claim selezionare solo:
Groups assigned to the application (recommended for large enterprise companies to avoid exceeding the limit on the number of groups a token can emit)
In Customize token properties by type lasciare il default proposto Group ID.Groups assigned to the application Successivamente andare in Enterprise applications, selezionare la app SgartSPFxDelegateDemoApp2, andare in Users and groups e premere Add user/groups e aggiungere i gruppi che si vuole esporre nei claims.
Ovviamente, i gruppi selezionati, saranno presenti nei claims solo se l'utente appartiene allo specifico gruppo.