Authentication with JWT, OIDC, and OAuth 2.0 via PAM
This draft, intended for technical review under DOCS-5715, requires validation for technical accuracy. It includes generated text and code blocks and needs evaluation by a subject matter expert (SME) in this format. Please refrain from relying on any information on the page.
MariaDB Server supports modern authentication standards—including JSON Web Tokens (JWT), OpenID Connect (OIDC), and OAuth 2.0—through its pluggable authentication architecture.
By leveraging the operating system's PAM (Pluggable Authentication Modules) subsystem, MariaDB can integrate with external Identity Providers (IdPs) like AWS Cognito, Google Cloud Identity, and Azure AD without requiring proprietary database plugins. The database delegates the validation of tokens to the underlying OS security layer.
Prerequisites
Before proceeding, ensure the following components are available:
MariaDB Server (Active and running).
PAM Module: You must install a third-party PAM module corresponding to your desired authentication method (e.g.,
pam_oidc.so,pam_oauth2.so, orpam_jwt.so).Note: These are system-level libraries installed into
/lib/securityor/lib64/security. Ensure the module you choose is actively maintained and compatible with your OS.
Identity Provider (IdP): You must have your
Issuer URL,Client ID, andAudiencevalues ready from your provider (e.g., Google, Okta, Azure).
Configuration and Connection Workflow
How to bridge the operating system's authentication layer with MariaDB user management.
How Authentication Works
Before configuring the system, it is helpful to understand the handshake between the Client, the Database, and the Operating System.
Configure the PAM Service
You must define a PAM service that loads your chosen module. This file tells the operating system how to validate the credentials passed by MariaDB.
File: /etc/pam.d/mariadb
The specific flags below (like issuer or aud) are standard OIDC parameters. Consult your specific PAM module's documentation for exact flag syntax.
Ensure strict validation of the aud (Audience) parameter to confirm that tokens are issued exclusively for your database application, preventing the use of tokens intended for different applications.
Configure MariaDB Server
Once the OS is configured, you must enable the PAM plugin in MariaDB and create a user that utilizes it.
Log in to MariaDB as root.
Install the PAM Plugin:
Create the User: The
USINGclause specifies the service name (filename) in/etc/pam.d/.
Connect via Client
When connecting, the "Password" field is used to transmit the JWT or OIDC Token.
Troubleshooting
Authentication Failure: Check the system authentication logs.
Look for errors regarding "invalid audience," "expired token," or "issuer mismatch."
SELinux/AppArmor: If the database cannot access the PAM configuration, ensure your security context allows
mysqldto read from/etc/pam.d/.Username Mapping: By default, the MariaDB username must match the identity in the token (often the
suboremailclaim). Some PAM modules allow you to map these (e.g., mappinguser@example.comtouser); check your module'suser_templateor mapping documentation.
Last updated
Was this helpful?

