OAuth Client & OpenID Connect SSO | OAuth/OIDC Login
Enables Single Sign-On (SSO) authentication for Drupal using OAuth 2.0 and OpenID Connect compliant identity providers such as Microsoft Entra ID (Azure AD), Google, Keycloak, Okta, and many more.
miniorange_oauth_client
Install
composer require 'drupal/miniorange_oauth_client:^5.0'
composer require 'drupal/miniorange_oauth_client:^4.0'
Overview
The miniOrange OAuth/OIDC Client module transforms your Drupal site into an OAuth 2.0 / OpenID Connect client, enabling seamless Single Sign-On (SSO) with external identity providers. Users can authenticate using their existing credentials from providers like Microsoft Entra ID (Azure AD), Azure B2C, AWS Cognito, Google, Discord, Keycloak, Okta, Salesforce, and many other OAuth/OpenID compliant servers.
The module implements the OAuth 2.0 Authorization Code Grant flow, exchanging authorization codes for access tokens and retrieving user information from the identity provider's userinfo endpoint. It supports attribute mapping to synchronize user data between the OAuth provider and Drupal user profiles.
The free version allows configuration of one OAuth provider and login of existing Drupal users. Premium and Enterprise versions add features like auto-user creation, multiple OAuth providers, advanced role mapping, OpenID Connect support, domain restrictions, page restrictions, and login analytics.
Features
- OAuth 2.0 and OpenID Connect (OIDC) Single Sign-On authentication
- Pre-configured templates for 20+ popular OAuth providers (Azure AD, Google, GitHub, Keycloak, Okta, etc.)
- Authorization Code Grant flow with CSRF protection via state parameter
- Configurable OAuth endpoints (Authorization, Token, UserInfo)
- Basic attribute mapping for email and username from OAuth server
- Test Configuration feature to verify OAuth setup and view received attributes
- Login link automatically added to Drupal login form when OAuth is enabled
- Flexible client credentials transmission (via HTTP header or request body)
- HTTPS callback URL enforcement option for providers requiring secure callbacks
- Configuration export to JSON file for backup and migration
- Debug logging with downloadable log files for troubleshooting
- Client secret encryption using AES-256-CBC for secure storage
- Custom login link text with dynamic app name placeholder support
Use Cases
Corporate Single Sign-On with Microsoft Entra ID (Azure AD)
Organizations using Microsoft 365 or Azure can enable employees to log into their Drupal intranet or public website using their existing corporate Microsoft credentials. Users click the SSO link on the Drupal login page and are redirected to Microsoft's login page. After authentication, they are automatically logged into Drupal with their user account matched by email address.
Social Login with Google
Allow website visitors to register and log in using their Google accounts. This simplifies the registration process and improves conversion rates by eliminating the need to create and remember new credentials. The module retrieves the user's email from Google to match or create their Drupal account.
Centralized Authentication with Keycloak
Organizations running Keycloak as their identity management solution can integrate Drupal as a client application. This enables single sign-on across all company applications, centralized user management, and consistent access control policies. Keycloak handles authentication while Drupal trusts the tokens it receives.
Customer Portal with Okta
SaaS companies using Okta for customer identity management can allow their customers to access a Drupal-based knowledge base or support portal using their existing Okta credentials. This provides a seamless experience and maintains security controls defined in Okta.
Developer Community with GitHub
Open source projects or developer communities can enable contributors to log in using their GitHub accounts. This is particularly relevant for Drupal-based documentation sites or developer portals where most users already have GitHub accounts.
Gaming Community with Discord
Gaming communities using Discord for communication can integrate Discord authentication with their Drupal community site. Members use their Discord credentials to access forums, galleries, and member-only content.
Enterprise B2B Portal with Salesforce
Companies using Salesforce for CRM can enable partners and customers to log into a Drupal partner portal using their Salesforce Community credentials. This maintains a unified identity across business systems and simplifies access management.
Tips
- Always run 'Perform Test Configuration' after changing OAuth settings to verify the connection works correctly
- Use the debug logging feature when troubleshooting by enabling it in Sign In Settings - logs appear in Reports > Recent log messages
- Export your configuration after setup using the Backup feature to easily restore or migrate settings
- The callback URL displayed in the module must be registered exactly as shown in your OAuth provider's application settings
- For Azure AD, use the Application (client) ID as Client ID and create a client secret in Certificates & secrets
- When using Google OAuth, enable the Google+ API and configure the OAuth consent screen in Google Cloud Console
- Clear Drupal cache after making configuration changes if the login link doesn't appear immediately
- The module adds login links to the standard Drupal login form automatically - no theme changes required
- For custom login link placement, create a block with an anchor tag pointing to /moLogin
- Client secrets are encrypted in the database - if migrating, use the export/import feature rather than copying database values
Technical Details
Admin Pages 8
/admin/config/people/miniorange_oauth_client/config_clc
Main configuration page for setting up OAuth/OpenID Connect provider settings. Configure your identity provider's endpoints, client credentials, and login behavior.
/admin/config/people/miniorange_oauth_client/mapping
Configure how attributes from the OAuth server are mapped to Drupal user fields. Map email, username, and custom attributes.
/admin/config/people/miniorange_oauth_client/Settings
Configure debugging, auto-user creation, page restrictions, domain restrictions, and custom redirect URLs.
/admin/config/people/miniorange_oauth_client/LoginReports
View SSO login analytics and user authentication history (Enterprise feature only).
/admin/config/people/miniorange_oauth_client/licensing
View feature comparison between Free, Standard, Premium, and Enterprise plans with pricing and upgrade options.
/admin/config/people/miniorange_oauth_client/backup
Export current OAuth configuration to JSON file or import configuration from a previously exported file.
/admin/config/people/miniorange_oauth_client/requestDemo
Request a 7-day trial of the premium/enterprise version features.
/admin/config/people/miniorange_oauth_client/CustomerSupportClient
Contact miniOrange support for technical help, demo scheduling, or sales inquiries.
Permissions 1
Hooks 2
hook_help
Provides help text for the module on the help page at admin/help/miniorange_oauth_client
hook_form_user_login_form_alter
Alters the Drupal user login form to add OAuth SSO login link when OAuth is configured and enabled
Troubleshooting 8
Ensure that 'Enable Login with OAuth' is checked in the Configure OAuth tab. Also verify that an OAuth provider is fully configured with all required endpoints and client credentials.
This CSRF protection error indicates the state parameter doesn't match. Clear browser cookies, ensure session handling is working correctly, and verify the callback URL matches exactly what's configured in your OAuth provider.
The email attribute is not mapped correctly. Run Test Configuration again and select the correct attribute that contains the email address from the dropdown in the test results window.
In the free version, users must already exist in Drupal with a matching email address. Create the user account first, or upgrade to Standard/Premium/Enterprise for auto-user creation.
Check that the Token Endpoint URL is correct. Verify the Client ID and Client Secret match your OAuth provider. Try changing the 'Send Client ID and secret in' setting between Header and Body.
The PHP cURL extension must be installed and enabled. Contact your hosting provider or server administrator to enable php-curl.
Enable the 'Enforce HTTPS Callback URL' checkbox in the Configure OAuth tab. This will generate an HTTPS callback URL even if your site is accessed via HTTP.
Ensure you click the 'Done' button in the test configuration popup after selecting the email attribute. If the popup closes unexpectedly, check browser popup blockers.
Security Notes 8
- Client secrets are encrypted using AES-256-CBC with the site's private key before storage in the database
- The OAuth state parameter is used to prevent CSRF attacks - it's generated with random data and validated on callback
- Session-based state comparison ensures the callback originates from the same user who initiated the login
- HTTPS callback URL enforcement is available for OAuth providers that require secure connections
- Email addresses are validated using filter_var() with FILTER_VALIDATE_EMAIL before user lookup
- All user output is escaped using Html::escape() to prevent XSS attacks
- The module uses Drupal's HTTP client rather than raw cURL for better security integration
- Page caching is disabled on the login form to ensure fresh SSO links are always displayed