Docs / Integration

Connect your own app

First check the provider with its starter client. Then use the configuration’s values in the app you are building.

Before copying an example

1. Choose your configuration in the editor and add or edit its client. A browser SPA is a public client with PKCE and no secret; a server application can use a confidential client with a development secret.
2. Register the exact callback URL your library uses: ASP.NET Core defaults to /signin-oidc; the SPA and Node examples below use /callback. Register your app’s sign-out callback too if it uses one.
3. Use the client ID and scopes from that client. Copy the authority and discovery values from Connect your app; replace every placeholder below.

Connection examples

Every configuration has its own issuer. Use the discovery URL with any standards-compliant OIDC library.

# Discovery (Generic and Microsoft profiles)
https://app.heyidentity.dev/t/{tenantRouteId}/c/{configurationId}/.well-known/openid-configuration

# Entra ID authority (Microsoft profile): Instance = https://app.heyidentity.dev/, TenantId = {configurationId}
https://app.heyidentity.dev/{configurationId}/v2.0

ASP.NET Core

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
    options.Authority = "https://app.heyidentity.dev/t/{tenantRouteId}/c/{configurationId}";
    options.ClientId = "my-app";
    options.ClientSecret = "my-app-secret";
    options.ResponseType = "code";
    options.Scope.Add("email");
    options.MapInboundClaims = false;                     // keep "roles" and "name" as issued
    options.TokenValidationParameters.NameClaimType = "name";
    options.TokenValidationParameters.RoleClaimType = "roles";
});

Browser SPA (oidc-client-ts)

import { UserManager } from 'oidc-client-ts';

const userManager = new UserManager({
  authority: 'https://app.heyidentity.dev/t/{tenantRouteId}/c/{configurationId}',
  client_id: 'my-spa',                      // public client: PKCE, no secret
  redirect_uri: `${location.origin}/callback`,
  scope: 'openid profile email',
});
await userManager.signinRedirect();

Node.js (openid-client)

import * as client from 'openid-client';

const config = await client.discovery(
  new URL('https://app.heyidentity.dev/t/{tenantRouteId}/c/{configurationId}'),
  'my-app',
  'my-app-secret',
);
const verifier = client.randomPKCECodeVerifier();
const url = client.buildAuthorizationUrl(config, {
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
  code_challenge: await client.calculatePKCECodeChallenge(verifier),
  code_challenge_method: 'S256',
});

Your tenant route ID and configuration ID are shown on your management page after signup. The live demo uses public demo configurations you can try right away.

Step-by-step: Entra ID apps without a tenant, Playwright and CI tests, role-based authorization, failed sign-ins, signing key rotation (Pro).

Verify the connection in your app

1. Apply the settings in your development environment, start the app and initiate its sign-in action.
2. Complete the callback in that app using the library’s callback handler. For oidc-client-ts, the callback route calls userManager.signinRedirectCallback(); ASP.NET Core’s OIDC middleware handles its callback. The Node application must keep its verifier/state in its own session and validate/exchange the response using its library.
3. Confirm your app shows the expected signed-in identity. Check the issuer, audience and roles/claims you rely on; try another configured user to verify access changes.
4. If the callback is rejected, compare its full URL with the client’s registered redirect URI. If token validation fails, check authority, audience, client ID and the profile-specific guidance.

A successful Test sign-in in the editor is useful provider evidence. The integration is verified when your own client completes its callback and checks its received identity.