Orchard Core OpenID Connect - Prompt Templates

Module Overview

The OrchardCore.OpenId module provides a complete OpenID Connect and OAuth 2.0 implementation for Orchard Core applications. It is built on top of OpenIddict and supports acting as an authorization server, a resource server, or integrating with external identity providers. Enable the relevant sub-features depending on your scenario:

OrchardCore.OpenId — Core services and shared infrastructure.
OrchardCore.OpenId.Server — Authorization server endpoints (authorize, token, logout, userinfo).
OrchardCore.OpenId.Client — External provider integration (Azure AD, Google, etc.).
OrchardCore.OpenId.Validation — Token validation for resource servers / APIs.

OpenID Connect Server Configuration

You are an Orchard Core expert. Configure the OpenID Connect authorization server.

Guidelines

Enable the OrchardCore.OpenId.Server feature before configuring server settings.
Choose appropriate flows based on client type: authorization code for web apps, client credentials for service-to-service.
Always use HTTPS in production for all endpoint URIs.
Configure token lifetimes according to your security requirements.
The server settings can be configured via the admin UI under Security → OpenID Connect → Server Settings, or through recipe steps.

Server Settings via Migration

public sealed class OpenIdServerMigrations : DataMigration
{
    private readonly IOpenIdServerService _serverService;

    public OpenIdServerMigrations(IOpenIdServerService serverService)
    {
        _serverService = serverService;
    }

    public async Task<int> CreateAsync()
    {
        var settings = await _serverService.GetSettingsAsync();

        settings.AllowAuthorizationCodeFlow = true;
        settings.AllowClientCredentialsFlow = true;
        settings.AllowRefreshTokenFlow = true;
        settings.UseRollingRefreshTokens = true;
        settings.AuthorizationEndpointPath = "/connect/authorize";
        settings.TokenEndpointPath = "/connect/token";
        settings.LogoutEndpointPath = "/connect/logout";
        settings.UserinfoEndpointPath = "/connect/userinfo";

        await _serverService.UpdateSettingsAsync(settings);

        return 1;
    }
}

Client Application Registration

Guidelines

Every client must have a unique ClientId.
Confidential clients (server-side apps) must have a ClientSecret.
Public clients (SPAs, native apps) must not store secrets; use authorization code flow with PKCE.
Set ConsentType to Explicit when user consent should be prompted, or Implicit for trusted first-party apps.
Specify only the redirect URIs your application actually uses.
Assign the minimum required scopes and roles to each client.

Client Registration via Migration

public sealed class OpenIdClientMigrations : DataMigration
{
    private readonly IOpenIdApplicationManager _applicationManager;

    public OpenIdClientMigrations(IOpenIdApplicationManager applicationManager)
    {
        _applicationManager = applicationManager;
    }

    public async Task<int> CreateAsync()
    {
        await _applicationManager.CreateAsync(new OpenIdApplicationDescriptor
        {
            ClientId = "my-web-app",
            DisplayName = "My Web Application",
            ClientSecret = "your-client-secret-here",
            ClientType = OpenIddictConstants.ClientTypes.Confidential,
            ConsentType = OpenIddictConstants.ConsentTypes.Implicit,
            Permissions =
            {
                OpenIddictConstants.Permissions.Endpoints.Authorization,
                OpenIddictConstants.Permissions.Endpoints.Token,
                OpenIddictConstants.Permissions.Endpoints.Logout,
                OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode,
                OpenIddictConstants.Permissions.GrantTypes.RefreshToken,
                OpenIddictConstants.Permissions.ResponseTypes.Code,
                OpenIddictConstants.Permissions.Scopes.Email,
                OpenIddictConstants.Permissions.Scopes.Profile,
                OpenIddictConstants.Permissions.Scopes.Roles,
                OpenIddictConstants.Permissions.Prefixes.Scope + "api",
            },
            RedirectUris = { new Uri("https://myapp.example.com/signin-oidc") },
            PostLogoutRedirectUris = { new Uri("https://myapp.example.com/signout-callback-oidc") },
        });

        return 1;
    }
}

Authorization Flows

Authorization Code Flow

The recommended flow for server-side web applications. The client exchanges an authorization code for tokens at the token endpoint.

Enable AllowAuthorizationCodeFlow in server settings.
The client must have GrantTypes.AuthorizationCode and ResponseTypes.Code permissions.
Always pair with refresh tokens for long-lived sessions.

Client Credentials Flow

Used for machine-to-machine communication where no user context is needed.

Enable AllowClientCredentialsFlow in server settings.
The client must be confidential and have GrantTypes.ClientCredentials permission.
Tokens issued via client credentials do not contain user claims.

Implicit Flow

Primarily used for legacy SPAs. Prefer authorization code flow with PKCE for new applications.

Enable AllowImplicitFlow in server settings.
The client must have GrantTypes.Implicit and either ResponseTypes.IdToken or ResponseTypes.IdTokenToken permissions.

Token Endpoint and Validation

The token endpoint (/connect/token by default) issues access tokens, identity tokens, and refresh tokens.

Guidelines

Access tokens are short-lived by default. Use refresh tokens for session continuity.
Configure AccessTokenLifetime and RefreshTokenLifetime in server settings.
Enable rolling refresh tokens (UseRollingRefreshTokens) to rotate refresh tokens on each use.
Token validation on resource servers uses the OrchardCore.OpenId.Validation feature.

Scopes and Claims

Registering Custom Scopes

public sealed class OpenIdScopeMigrations : DataMigration
{
    private readonly IOpenIdScopeManager _scopeManager;

    public OpenIdScopeMigrations(IOpenIdScopeManager scopeManager)
    {
        _scopeManager = scopeManager;
    }

    public async Task<int> CreateAsync()
    {
        await _scopeManager.CreateAsync(new OpenIdScopeDescriptor
        {
            Name = "api",
            DisplayName = "API Access",
            Description = "Grants access to the application API endpoints.",
            Resources = { "my-resource-server" },
        });

        return 1;
    }
}

Standard Scopes

openid — Required for all OpenID Connect requests. Returns a sub claim.
profile — Returns user profile claims (name, family_name, etc.).
email — Returns email and email_verified claims.
roles — Returns role membership claims.
phone — Returns phone number claims.

External Authentication Providers

The OrchardCore.OpenId.Client feature enables federated sign-in with external identity providers.

Guidelines

Configure external providers via admin UI under Security → OpenID Connect → Client Settings.
Each provider requires a ClientId, ClientSecret (for confidential providers), and an Authority URI.
Map external claims to Orchard Core user properties as needed.
Supported providers include Azure AD, Azure AD B2C, Google, Microsoft, and any standard OpenID Connect provider.

External Provider Setup via Startup

public sealed class ExternalProviderStartup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication()
            .AddOpenIdConnect("AzureAD", "Azure Active Directory", options =>
            {
                options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
                options.ClientId = "your-azure-client-id";
                options.ClientSecret = "your-azure-client-secret";
                options.ResponseType = OpenIdConnectResponseType.Code;
                options.SaveTokens = true;
                options.Scope.Add("openid");
                options.Scope.Add("profile");
                options.Scope.Add("email");
                options.TokenValidationParameters.NameClaimType = "name";
            });
    }
}

JWT Bearer Token Authentication for APIs

Enable JWT bearer authentication to protect API endpoints using tokens issued by the OpenID Connect server.

Guidelines

Enable the OrchardCore.OpenId.Validation feature on the resource server.
Configure the validation settings to point to the authorization server's authority URI.
Use [Authorize] attributes on API controllers to enforce authentication.
The validation feature supports both local validation (same application as server) and remote validation (separate resource server).

API Controller with JWT Authentication

[ApiController]
[Route("api/[controller]")]
[Authorize(AuthenticationSchemes = OpenIddictValidationAspNetCoreDefaults.AuthenticationScheme)]
public sealed class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        var userId = User.FindFirstValue(OpenIddictConstants.Claims.Subject);
        return Ok(new { Message = "Authenticated", UserId = userId });
    }

    [HttpGet("admin")]
    [Authorize(Roles = "Administrator")]
    public IActionResult GetAdmin()
    {
        return Ok(new { Message = "Admin access granted" });
    }
}

Validation Settings via Migration

public sealed class OpenIdValidationMigrations : DataMigration
{
    private readonly IOpenIdValidationService _validationService;

    public OpenIdValidationMigrations(IOpenIdValidationService validationService)
    {
        _validationService = validationService;
    }

    public async Task<int> CreateAsync()
    {
        var settings = await _validationService.GetSettingsAsync();

        settings.Authority = new Uri("https://auth.example.com");
        settings.Audience = "my-resource-server";

        await _validationService.UpdateSettingsAsync(settings);

        return 1;
    }
}

Recipe Steps for OpenID Configuration

Use recipe steps to declaratively configure OpenID Connect settings, applications, and scopes during site setup or deployment.

OpenID Server Settings Recipe Step

{
  "steps": [
    {
      "name": "OpenIdServerSettings",
      "AllowAuthorizationCodeFlow": true,
      "AllowClientCredentialsFlow": true,
      "AllowRefreshTokenFlow": true,
      "UseRollingRefreshTokens": true,
      "AuthorizationEndpointPath": "/connect/authorize",
      "TokenEndpointPath": "/connect/token",
      "LogoutEndpointPath": "/connect/logout",
      "UserinfoEndpointPath": "/connect/userinfo"
    }
  ]
}

OpenID Application Recipe Step

{
  "steps": [
    {
      "name": "OpenIdApplication",
      "ClientId": "spa-client",
      "DisplayName": "Single Page Application",
      "ClientType": "public",
      "ConsentType": "implicit",
      "AllowAuthorizationCodeFlow": true,
      "AllowRefreshTokenFlow": true,
      "RequireProofKeyForCodeExchange": true,
      "RedirectUris": "https://spa.example.com/callback",
      "PostLogoutRedirectUris": "https://spa.example.com/logout-callback",
      "AllowedScopes": [
        "openid",
        "profile",
        "email",
        "api"
      ]
    }
  ]
}

OpenID Scope Recipe Step

{
  "steps": [
    {
      "name": "OpenIdScope",
      "ScopeName": "api",
      "DisplayName": "API Access",
      "Description": "Grants access to protected API endpoints.",
      "Resources": "my-resource-server"
    }
  ]
}

OpenID Validation Settings Recipe Step

{
  "steps": [
    {
      "name": "OpenIdValidationSettings",
      "Authority": "https://auth.example.com",
      "Audience": "my-resource-server"
    }
  ]
}

Admin UI Configuration

OpenID settings are managed through the admin dashboard:

Security → OpenID Connect → Server Settings — Configure authorization server endpoints, supported flows, and token lifetimes.
Security → OpenID Connect → Applications — Register and manage client applications.
Security → OpenID Connect → Scopes — Define custom scopes and associated resources.
Security → OpenID Connect → Client Settings — Configure external identity providers for federated login.
Security → OpenID Connect → Validation Settings — Configure token validation for resource server scenarios.