> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/server/reference/plugins/authentication-plugins/authentication-plugin-tls-certificate.md).

# Authentication Plugin - tls\_certificate

The tls\_certificate authentication plugin authenticates an account by its TLS client certificate alone, with no password, requiring the certificate subject to match REQUIRE SUBJECT.

{% hint style="info" %}
This plugin is available from MariaDB Enterprise Server 12.3. It is not included in MariaDB Community Server.
{% endhint %}

The `tls_certificate` authentication plugin authenticates a user from the TLS client certificate presented during the connection handshake. No password is involved at any point: the account holds no password, none is sent, and none is checked.

The account is identified by the certificate's subject Distinguished Name (DN), which must be pinned on the account with a [`REQUIRE SUBJECT`](/docs/server/reference/sql-statements/account-management-sql-statements/create-user.md) clause. The plugin refuses to authenticate an account that was not created with `REQUIRE SUBJECT`.

### Description

The plugin itself does no certificate validation. Signature checking, expiry, and revocation (CRL/OCSP) are all handled by the server's TLS layer during the handshake, before the plugin runs. The plugin's only check is that the account carries a `REQUIRE SUBJECT` clause; enforcing that clause is likewise the server's job.

### Installing

The plugin is built into MariaDB Enterprise Server and enabled by default. There is no `INSTALL SONAME` step, and no separate package to install.

No client-side change is needed either. The plugin accepts any standard client authentication plugin, so existing clients and connectors connect without modification — they simply need to present the certificate.

### Example

Create an account whose subject DN matches the client certificate, and grant it as usual:

```sql
CREATE USER 'alice'@'%'
  IDENTIFIED VIA tls_certificate
  REQUIRE SUBJECT '/CN=alice/O=Example Ltd/C=FI';
```

`IDENTIFIED WITH` is accepted as a synonym for `IDENTIFIED VIA`.

The client connects with its key pair and no password:

```bash
mariadb --user=alice \
        --ssl-ca=/etc/ssl/ca.pem \
        --ssl-cert=/etc/ssl/alice-cert.pem \
        --ssl-key=/etc/ssl/alice-key.pem
```

If the certificate subject does not match, or the account has no `REQUIRE SUBJECT` clause, the connection fails with a standard access-denied error — the plugin defines no error code of its own:

```
ERROR 1698 (28000): Access denied for user 'alice'@'localhost'
```

For the mechanics of subject matching (case sensitivity, field order, and the issuer-pinning caveat), see [Matching the Certificate Subject](/docs/server/reference/sql-statements/account-management-sql-statements/create-user.md#matching-the-certificate-subject) under `CREATE USER`.

## Account Management Behavior

Because these accounts authenticate with no password, several password-related features do not apply:

* [`PASSWORD EXPIRE`](/docs/server/reference/sql-statements/account-management-sql-statements/alter-user.md) and `password_lifetime` have no effect — the expiry check is skipped for a connection that used no password. Use `ACCOUNT LOCK`, which is enforced normally, to disable such an account.
* A `USING` or `AS` clause is accepted and stored, but the plugin never reads it, so it has no effect. `SET PASSWORD` on these accounts is rejected.

{% hint style="warning" %}
An account created with `IDENTIFIED VIA tls_certificate` but **without** `REQUIRE SUBJECT` is created successfully and cannot connect. The plugin API offers no hook at `CREATE USER` time for a passwordless plugin, so no warning can be raised. Add the clause with [`ALTER USER`](/docs/server/reference/sql-statements/account-management-sql-statements/alter-user.md) and the account works.
{% endhint %}

When several authentication methods are combined with `OR`, the first one that succeeds wins. An account given both `tls_certificate` and a password method can therefore log in with the password alone if `REQUIRE SUBJECT` is absent. Requiring *both* a valid certificate and a password needs multi-factor authentication (several plugins combined with `AND`), which is not yet available.

## Options

The plugin adds no system variables and no status variables. The only option is the standard plugin activation option.

### `tls_certificate`

* Description: Controls how the server should treat the plugin when the server starts up.
  * Valid values are:
    * `OFF` - Disables the plugin without removing it from the [mysql.plugin](/docs/server/reference/system-tables/the-mysql-database-tables/mysql-plugin-table.md) table.
    * `ON` - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
    * `FORCE` - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
    * `FORCE_PLUS_PERMANENT` - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with [UNINSTALL SONAME](/docs/server/reference/sql-statements/administrative-sql-statements/plugin-sql-statements/uninstall-soname.md) or [UNINSTALL PLUGIN](/docs/server/reference/sql-statements/administrative-sql-statements/plugin-sql-statements/uninstall-plugin.md) while the server is running.
  * See [Plugin Overview: Configuring Plugin Activation at Server Startup](/docs/server/reference/plugins/plugin-overview.md#configuring-plugin-activation-at-server-startup) for more information.
* Command line: `--tls-certificate=value`, or equivalently `--plugin-tls-certificate=value`
* Data Type: `enumerated`
* Default Value: `ON`
* Valid Values: `OFF`, `ON`, `FORCE`, `FORCE_PLUS_PERMANENT`
* Introduced: MariaDB Enterprise Server 12.3

{% hint style="info" %}
On the command line and in configuration files, MariaDB treats `-` and `_` in an option name as equivalent, so `--plugin-tls_certificate` works as well. Option names are always printed with hyphens, which is why `mariadbd --help --verbose` lists `--plugin-tls-certificate` even though the plugin is named `tls_certificate` in SQL.
{% endhint %}

## See Also

* [Pluggable Authentication Overview](/docs/server/reference/plugins/authentication-plugins/pluggable-authentication-overview.md)
* [CREATE USER](/docs/server/reference/sql-statements/account-management-sql-statements/create-user.md)
* [ALTER USER](/docs/server/reference/sql-statements/account-management-sql-statements/alter-user.md)
* [Securing Connections for Client and Server](/docs/server/security/encryption/data-in-transit-encryption/securing-connections-for-client-and-server.md)
* [SSL/TLS System Variables](/docs/server/security/encryption/data-in-transit-encryption/ssltls-system-variables.md)

<sub>*This page is licensed: CC BY-SA / Gnu FDL*</sub>

{% @marketo/form formId="4316" %}