Entra ID redirect URIs and sign-in
此内容尚不支持你的语言。
Web apps that sign users in need redirect URIs, also called callback URIs, registered on their Microsoft Entra ID registration. Aspire registers redirect URIs on registrations that it creates. For an existing registration, the redirect URI methods throw, so add the URIs in the Authentication settings of the Microsoft Entra admin center instead.
Aspire doesn’t discover redirect URIs on its own. The callback path is configured by the app that signs users in, so you supply it in the AppHost and it must match the app’s configuration.
Derive redirect URIs from an endpoint
Section titled “Derive redirect URIs from an endpoint”Pass an endpoint and one or more callback paths so the redirect URIs follow the resource’s endpoint instead of hard-coded values.
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const entraWeb = await builder.addEntraIdApplication("entra-web");
const web = await builder.addDotnetProject("web", "../Web/Web.csproj");await web.withExternalHttpEndpoints();await web.withReference(entraWeb);
await entraWeb.withRedirectUris(await web.getEndpoint("https"), { callbackPaths: ["/signin-oidc", "/signout-callback-oidc"],});
await builder.build().run();var builder = DistributedApplication.CreateBuilder(args);
var entraWeb = builder.AddEntraIdApplication("entra-web");
var web = builder.AddDotnetProject("web", "../Web/Web.csproj") .WithExternalHttpEndpoints() .WithReference(entraWeb);
entraWeb.WithRedirectUris(web.GetEndpoint("https"), "/signin-oidc", "/signout-callback-oidc");
// After adding all resources, run the app...builder.Build().Run();The scheme, host, and port come from the endpoint, and the behavior depends on the mode:
- When you run the AppHost, Aspire waits for the endpoint to be allocated and then uses the endpoint’s finalized browser URL. This includes friendly
*.dev.localhostnames and URL customizations. The registration receives the real URL even when ports are assigned randomly. - When you publish or deploy, the URI is
https://plus the host of the resource’s compute environment, plus the callback path. The deployed endpoint must have TLS enabled. If it doesn’t, generating the infrastructure fails with an error that asks you to use an HTTPS endpoint or an explicit redirect URI. In Azure Container Apps, the endpoint must also be an external HTTP or HTTPS endpoint, for example by callingWithExternalHttpEndpoints. - Each callback path must start with
/, and at least one path is required.
If the registered URI doesn’t match the URL that the browser uses, supply explicit redirect URIs.
Use a host parameter
Section titled “Use a host parameter”When only the host name varies per environment, such as a custom domain supplied at deployment time, pass a parameter for the host and the fixed callback paths. Each URI is https://{host}{path}, so don’t include a scheme or path in the parameter value. This and the remaining examples on this page continue the previous example and use its builder and entraWeb variables.
const webHost = await builder.addParameter("web-host");
await entraWeb.withRedirectUris(webHost, { callbackPaths: ["/signin-oidc", "/signout-callback-oidc"],});var webHost = builder.AddParameter("web-host");
entraWeb.WithRedirectUris(webHost, "/signin-oidc", "/signout-callback-oidc");Use literal or parameter URIs
Section titled “Use literal or parameter URIs”When the externally visible URL differs from the endpoint, such as behind a gateway, reverse proxy, or custom domain, supply the full URIs. A parameter without callback paths holds comma-separated full URIs.
Aspire passes literal and parameter URIs to Microsoft Entra ID as they are, and Microsoft Entra ID enforces its redirect URI restrictions. Register only exact https:// URIs of hosts that you control, except http://localhost for local development, and don’t use wildcards. Values that you supply for a host parameter are trusted the same way, so restrict who can set them.
const redirectUris = await builder.addParameter("web-redirect-uris");
await entraWeb.withRedirectUris("https://localhost:7123/signin-oidc");await entraWeb.withRedirectUris(redirectUris);var redirectUris = builder.AddParameter("web-redirect-uris");
entraWeb .WithRedirectUris("https://localhost:7123/signin-oidc") .WithRedirectUris(redirectUris);Literal and parameter-backed URIs can be mixed and are registered in call order. In a parameter value, separate URIs with commas, without spaces. A URI can’t contain a comma. In TypeScript, call withRedirectUris repeatedly to add more than one value.
Keep browser origins consistent
Section titled “Keep browser origins consistent”Ordinary endpoint references resolve to the allocated address, which can differ from the *.dev.localhost URL that the browser shows. For settings that must match the browser URL, such as a CORS allow list, read the endpoint’s PrimaryBrowserOrigin or BrowserOrigins property instead. Redirect URIs use the same primary browser origin.
Enable ID-token issuance
Section titled “Enable ID-token issuance”ID-token issuance through implicit and hybrid flows is disabled by default. Enable it when your app’s OpenID Connect sign-in flow requests an ID token directly from the authorization endpoint.
await entraWeb.withIdTokenIssuance();entraWeb.WithIdTokenIssuance();WithIdTokenIssuance enables only ID-token issuance, not implicit access-token issuance. It isn’t needed for authorization-code-only flows. For an existing registration, the method throws, so select ID tokens (used for implicit and hybrid flows) in the registration’s Authentication settings instead.
For new production apps, prefer the authorization code flow with PKCE, and configure a client credential when the app redeems codes.
Choose a sign-in audience
Section titled “Choose a sign-in audience”By default, only accounts in the app’s home tenant can sign in. When the registration’s Supported account types setting allows other accounts, call WithSignInAudience with the matching value.
import { EntraIdSignInAudience } from './.aspire/modules/aspire.mjs';
await entraWeb.withSignInAudience(EntraIdSignInAudience.AzureADMultipleOrgs);entraWeb.WithSignInAudience(EntraIdSignInAudience.AzureADMultipleOrgs);| Sign-in audience | Who can sign in | TenantId value that apps receive |
|---|---|---|
AzureADMyOrg (default) | Accounts in the home tenant | The home tenant ID |
AzureADMultipleOrgs | Accounts in any Microsoft Entra tenant | organizations |
AzureADandPersonalMicrosoftAccount | Accounts in any Microsoft Entra tenant and personal Microsoft accounts | common |
PersonalMicrosoftAccount | Personal Microsoft accounts only | consumers |
For the audiences other than AzureADMyOrg, apps also receive the home tenant ID as AppHomeTenantId. Microsoft.Identity.Web needs it when the app acquires tokens as itself. Always pass the home tenant ID, not organizations, common, or consumers, when you reference an existing registration.
For registrations that Aspire creates, WithSignInAudience also sets the registration’s supported account types. For existing registrations, it configures only the apps that reference the registration, so set the matching account types in the Microsoft Entra admin center.
Target a sovereign cloud
Section titled “Target a sovereign cloud”Use WithInstance to point referencing apps at a sovereign cloud such as Azure Government. The instance must be an absolute HTTPS URL without a query string or fragment.
await entraWeb.withInstance("https://login.microsoftonline.us/");entraWeb.WithInstance("https://login.microsoftonline.us/");The built-in Microsoft Graph, Azure Resource Manager, and Azure Storage APIs use their global-cloud URLs. In a sovereign cloud, define the API yourself with the cloud’s resource URI and base URL, and request its permissions by ID. For an example, see Call Microsoft Graph and other first-party APIs.