This documentation assumes that you have completed through step 9 from the Installing mojoPortal documentation.

Due to an older bug, you will need mojoPortal v4.0.0 to make this work with providers other than Keycloak.

OpenID Connect (OIDC) Authentication in mojoPortal

mojoPortal includes built-in support for external authentication and role synchronization using OpenID Connect (OIDC) / OAuth 2.0 (Authorization Code Flow). When enabled, OIDC replaces the standard local Forms authentication workflow, redirecting login, registration, password recovery, and logout actions to your external Identity Provider (IdP) such as Keycloak, Auth0, Entra ID, or Duende IdentityServer.

---

1. Architecture Overview

The OIDC integration consists of five main components:

• AppConfig.OAuthConfiguration : Reads the OAuth:* configuration settings from user.config or Web.config and exposes AppConfig.OAuth.Configured .
• OidcService : Initialized at application startup in Global.Application_Start . Manages OIDC discovery metadata ( DiscoveryCache ), JSON Web Key caching ( JsonWebKeyCache ), authorization URL generation, token exchange, token refresh, JWT validation, and PageUrlService link overrides.
• ExternalLoginController : An MVC controller registered by RouteRegistrar.RegisterRoutes that handles the OIDC authorization callback ( /ExternalLogin/Callback ), single sign-out ( /ExternalLogin/Logout ), and error display ( /ExternalLogin/Error ).
• AuthHandlerHttpModule : Hooks into the ASP.NET pipeline asynchronously ( AuthenticateRequestAsync ) to validate token cookies on each request, auto-provision local SiteUser accounts on first login, and set HttpContext.Current.User to a mojoPrincipal backed by mojoIdentity .
• mojoRoleProvider : Synchronizes user roles from the OIDC Access Token's resource_access claim with local mojoPortal site roles.

---

2. Identity Provider (IdP) Requirements

Configure your OIDC Identity Provider client with the following settings:

Some documentation to providers that you might be using: 

• Keycloak
• Microsoft Entra ID ("Create an app registration in Azure" section)
• Google Identity
• Amazon 

---

3. Configuration ( user.config )

To enable OIDC, add the following three keys to your <appSettings> in user.config:

<!-- Base URL of your OIDC Identity Provider / Realm -->
<add key="OAuth:Authority" value="https://idp.example.com/realms/my-realm" />

<!-- Client ID registered in your Identity Provider -->
<add key="OAuth:ClientId" value="my-client-id" />

<!-- Client Secret generated by your Identity Provider -->
<add key="OAuth:ClientSecret" value="your-client-secret" />

Optional Redirect Configuration

By default, after a successful login callback without a specific returnurl , mojoPortal redirects to the site root ( ~/ ). You can customize this destination in user.config :

<add key="LoginRedirectLink" value="~/my-dashboard" />

---

4. Required Token Claims & User Auto-Provisioning

On every authenticated request, AuthHandlerHttpModule.AuthenticateRequestAsync reads claims from the Identity Token ( ExternalLogin:IdentityToken cookie) to identify or create the mojoPortal user:

First-Time Login Provisioning

When a user authenticates via OIDC and their email does not yet exist in the current site's database:

1. A new SiteUser is created with LoginName and Email set to the email claim, Name set to name , and a randomly generated encoded password.
2. Existing newsletter subscriptions matching the email are claimed via NewsletterHelper.ClaimExistingSubscriptions .
3. Registered UserRegisteredHandlerProvider events are fired.

---

5. Role Synchronization

When AppConfig.OAuth.Configured is enabled, mojoRoleProvider.GetRolesAndSetCookieInternal bypasses standard role cookies and instead synchronizes roles from the Access Token's resource_access claim (the standard Keycloak client-role claim format):

{
	"resource_access": {
		"easy-image": {
			"roles": [
				"Admins",
				"Content Publishers"
			]
		}
	}
}

How Role Sync Works

1. mojoRoleProvider reads the resource_access claim from Global.OidcService.AccessToken and deserializes it into mojoRoleProvider.ResourceAccess .
2. Adding Roles: Any role listed in the token that the user does not currently have in mojoPortal—provided a role with that exact RoleName already exists in the mojoPortal site—is granted via Role.AddUser .
3. Removing Roles: Any mojoPortal role currently assigned to the user that is not present in the token's role array is removed from the user via Role.RemoveUser .

---

6. Authentication & Session Lifecycle

1. Link Overrides & Page Redirects:
   • OidcService overrides PageUrlService links so all standard mojoPortal login, registration, and logout controls point to the OIDC endpoints.
   • Direct requests to /Secure/Login.aspx and /Secure/RecoverPassword.aspx automatically redirect to the IdP's authorization_endpoint .
   • Direct requests to /Secure/Register.aspx automatically redirect to the IdP's registration_endpoint (from discovery metadata).
2. Cookies & Automatic Token Refresh:
   • OidcService.SetTokenCookies stores three persistent cookies: ExternalLogin:AccessToken , ExternalLogin:IdentityToken , and ExternalLogin:RefreshToken .
   • On each request, OidcService.IsAuthenticated validates ExternalLogin:AccessToken . If SecurityTokenExpiredException is thrown, it automatically calls GetTokensByRefreshToken using ExternalLogin:RefreshToken and updates all three cookies.
3. Single Sign-Out:
   • Clicking Log Out routes to ExternalLoginController.Logout , which calls OidcService.Logout to expire the three ExternalLogin:* cookies and redirect the browser to the IdP's end_session_endpoint with id_token_hint and post_logout_redirect_uri .

---

7. Troubleshooting

• Redirected to /ExternalLogin/Error with an Incident Number:
  • Check the mojoPortal system log ( Data/currentlog.config or System Log in Admin) for (Incident <Guid>) . ExternalLoginController.Callback logs the exact validation failure message.
  • The most common cause is an aud (Audience) mismatch in the Access Token—verify that your IdP includes OAuth:ClientId in the Access Token's aud claim.
• User logs in at IdP, returns to mojoPortal, but remains unauthenticated:
  • Check the mojoPortal log for messages from AuthHandlerHttpModule :
    • "User tried to authenticate but no email claim was found in the identity token." -> Ensure your IdP includes the email claim in the Identity Token even when only the openid scope is requested.
    • "User tried to authenticate but no name claim was found in the identity token." -> Ensure the name (full name) claim is mapped into the Identity Token for new users.