Implementing Custom Authentication Providers in Microsoft Power Pages

Introduction

Microsoft Power Pages provides out-of-the-box integration with several common identity providers (IdPs), such as Entra ID B2C and various social logins. However, specific enterprise requirements often necessitate integrating with custom or non-standard identity providers.

This involves configuring Power Pages to trust and communicate with an external IdP using established authentication protocols like OpenID Connect (OIDC), OAuth 2.0, or SAML 2.0.

In this article, I will show you how to do it!

Supported Authentication Protocols

Power Pages uses industry-standard protocols for external authentication. For custom configurations, familiarity with the following is essential:

• OpenID Connect (OIDC) 1.0: An identity layer built on OAuth 2.0. It is a modern, widely supported protocol ideal for conveying user identity information securely. It is often the preferred choice for new custom integrations.
• OAuth 2.0: An authorization framework. While OIDC utilizes OAuth 2.0, direct OAuth 2.0 configuration might be used in specific scenarios, although OIDC is generally more appropriate for user login.
• SAML 2.0: An XML-based standard commonly used in enterprise federation scenarios, particularly with services like Active Directory Federation Services (ADFS).

The target custom IdP must support one of these protocols for direct integration. Systems using non-standard protocols may require an intermediary service (e.g., Azure AD B2C custom policies, API gateway) to translate authentication flows into a Power Pages-compatible protocol.

Configuration Process: OpenID Connect Example

The configuration involves coordinated setup steps within the external IdP and Power Pages. The following details the process using OpenID Connect:

1. External Identity Provider Configuration:

The specific steps vary depending on the IdP software or service, but generally involve:

Application Registration: Register the Power Pages portal as a client application or relying party within the IdP.

Redirect URI Configuration: Define the exact callback URL where the IdP will redirect the user’s browser after successful authentication. Power Pages requires this URL in the format https://<yourportaldomain>/signin-<providername>. <yourportaldomain> is the domain of the Power Pages site, and <providername> is a unique identifier chosen for this configuration (e.g., CustomOIDCProvider). This URI must be registered precisely within the IdP.

Client Credentials Generation: The IdP will issue a Client ID (a public identifier for the Power Pages application) and a Client Secret (a confidential key for secure back-channel communication). Secure management of the Client Secret is paramount.

Scope Definition: Specify the permissions (scopes) the Power Pages site can request. The openid scope is mandatory for OIDC. profile and email scopes are commonly included to retrieve basic user information. Custom scopes defined by the IdP may also be required.

Endpoint Identification: Record the IdP’s Authority URL and, preferably, the Metadata endpoint URL (typically found at /.well-known/openid-configuration relative to the authority). The metadata endpoint allows Power Pages to dynamically discover other necessary endpoints (authorization, token, userinfo).

2. Power Pages Site Settings Configuration:

Configuration within Power Pages is managed via Site Settings, accessible through the Portal Management model-driven application. Create or modify the following settings, adhering strictly to the naming convention Authentication/OpenIdConnect/[ProviderName]/[SettingName], replacing [ProviderName] with the identifier used in the Redirect URI (e.g., CustomOIDCProvider).

• Authentication/OpenIdConnect/[ProviderName]/Authority: The base URL identifier for the OIDC IdP. (e.g., https://sso.customprovider.com/identity)
• Authentication/OpenIdConnect/[ProviderName]/ClientId: The Client ID obtained from the IdP.
• Authentication/OpenIdConnect/[ProviderName]/ClientSecret: The Client Secret obtained from the IdP. Consider secure storage mechanisms like Azure Key Vault where feasible, although entry as a Site Setting is standard.
• Authentication/OpenIdConnect/[ProviderName]/RedirectUri: The specific Redirect URI registered within the IdP. (e.g., https://contosoportal.powerappsportals.com/signin-CustomOIDCProvider). Explicit definition ensures alignment.
• Authentication/OpenIdConnect/[ProviderName]/MetadataAddress: The URL for the IdP’s OIDC discovery document. Using this setting simplifies configuration by allowing Power Pages to auto-discover endpoints. (e.g., https://sso.customprovider.com/identity/.well-known/openid-configuration)
• Authentication/OpenIdConnect/[ProviderName]/Scope: A space-separated string of scopes to be requested. Must include openid. (e.g., openid email profile)
• Authentication/OpenIdConnect/[ProviderName]/ResponseType: Typically code for the OIDC Authorization Code flow. Consult IdP documentation if a different flow (e.g., implicit) is required.
• Authentication/OpenIdConnect/[ProviderName]/ResponseMode: Commonly form_post for web applications. Verify the expected mode with the IdP documentation.

3. Provider Activation and User Record Mapping:

Configure settings related to user registration and the linking of external identities to Dataverse Contact records:

• Authentication/Registration/Enabled: Set to true to permit new user registrations via external IdPs. If false, only pre-existing or invited users can authenticate.
• Authentication/Login/Enabled: Set to true to globally enable login via configured external IdPs.
• Claim Mapping: Define how claims received from the IdP’s ID token or UserInfo endpoint map to attributes of the Dataverse Contact entity. This is essential for identifying users and populating their profiles.
  • Authentication/OpenIdConnect/[ProviderName]/ClaimsMapping/emailaddress1: Specifies the IdP claim containing the user’s unique email address (e.g., email, upn). This is typically used as the primary identifier for finding or creating Contact records.
  • Authentication/OpenIdConnect/[ProviderName]/ClaimsMapping/firstname: Maps to the claim holding the user’s given name (e.g., given_name).
  • Authentication/OpenIdConnect/[ProviderName]/ClaimsMapping/lastname: Maps to the claim holding the user’s family name (e.g., family_name).
  • Additional claims can be mapped to other Contact attributes using the pattern: Authentication/OpenIdConnect/[ProviderName]/ClaimsMapping/[contact_attribute_logical_name] = IdP_Claim_Name.

4. User Interface Configuration:

• Authentication/OpenIdConnect/[ProviderName]/Caption: Defines the display text for the login button associated with this custom provider on the sign-in page. (e.g., “Login with Company SSO”).

Testing and Diagnostics

Thorough testing and systematic troubleshooting are critical:

Cache Invalidation: After modifying Site Settings, clear the Power Pages server-side cache via the administrative interface (/_services/about) to ensure changes take effect.

Browser Developer Tools: Utilize the Network tab (F12) to trace the HTTP requests and responses during the authentication flow. Monitor redirects between Power Pages and the IdP, inspect parameters, and check for HTTP errors.

identity Provider Logs: Review diagnostic logs provided by the external IdP. These logs often contain specific error messages regarding malformed requests, invalid credentials, or mismatched URIs.

Configuration Verification: Methodically verify all configuration parameters (URLs, Client ID, Client Secret, Redirect URIs, claim names) on both the Power Pages and IdP sides. Case sensitivity and exact syntax are crucial.

Incremental Testing: Begin with a minimal OIDC configuration to establish the basic authentication redirect. Once successful, progressively add claim mappings and other optional settings.

Alternative Protocols: SAML 2.0 and OAuth 2.0

The configuration process for SAML 2.0 and generic OAuth 2.0 providers follows a similar pattern but utilizes different Site Setting prefixes (Authentication/SAML2/[ProviderName]/... or Authentication/OAuth2/[ProviderName]/...) and protocol-specific parameters.

• SAML 2.0: Requires configuration of settings like ServiceProviderIdentifier, IdentityProviderIdentifier, AssertionConsumerServiceUrl, and potentially URLs for IdP metadata or specific SSO endpoints.
• OAuth 2.0: Involves settings for AuthorizationEndpoint, TokenEndpoint, and potentially UserInformationEndpoint.

If you have any questions, write a comment or contact me on linked in!