Skip to content

Authentication

Overview

When visiting a web-page or requesting an HTTP service, one must often authenticate to prove the identity of the person (or agent) making the request. There are multiple techniques for authentication.

Background

Setup

The CiviCRM installer stores randomly-generated private keys in civicrm.settings.php. On older sites that predated this install step, the keys might be missing, resulting in an error message like:

Failed to find key by ID or tag (SIGN)

To fix this, copy and past the code generated by this key generater helper into your civicrm.settings.php file.

Identity

Identities in CiviCRM are defined in two ways:

  • CMS User
  • CiviCRM Contact

Most CMS users have a corresponding CiviCRM contact record; however, the relationship is not a strict 1-1. Here are a few permutations to consider:

CMS User CiviCRM Contact Example
Defined Defined A staff member logs in and uses CiviCRM administration UI. (Note: The link between user<=>contact is stored in civicrm_uf_match.)
Defined Not defined A new CMS user has been created. However, they have never logged in. The CMS and Civi records have not been synchronized yet.
Not defined Not defined An anonymous person browses brochure information.
Not defined Defined A contituent receives a targeted email and opens a link to update their profile.

When a CMS user has been authenticated, this will be flagged using the CMS's preferred API. (Thus, on D7, global $account refers to the authenticated user. On WP, wp_get_current_user() refers to the authenticated user.)

When a CiviCRM contact has been authenticated, this will be flagged in CRM_Core_Session as the userID.

Browser Authentication

CiviCRM is a browser-based application that integrates with other browser-based applications (Drupal, WordPress, Joomla, Backdrop, etc).

The most familiar authentication technique is to login through the web-browser. For example, the user may navigate to Drupal's /user/login or WordPress's /wp-admin/, fill in credentials, and initialize an authenticated session.

Subsequently, the user may request any CiviCRM web-page, and it recognizes their identity.

In this way, CiviCRM can be chameleon - adapting to whichever web-based authentication process is available on the local deployment.

Service Authentication

CiviCRM also acts as a web-service provider. It offers APIv3 REST and APIv4 REST to remote applications (mobile apps, enterprise integrations, and so on). The core extension "Authx" (v5.36+) defines a portable protocol for CiviCRM service authentication.

Key features:

  • Support consistent authentication protocols, regardless of the CMS (Drupal, WordPress, Joomla, Backdrop)
  • Integrate with CMS authentication, ensuring that Civi contact records are matched with CMS user records
  • Accept multiple types of credentials (username/password, API key, JSON Web Token)
  • Accept credentials through different data-flows (HTTP headers, HTTP parameters, login forms)

The remainder of this chapter explores portable authentication options for web services.

Credentials

TIP: The site administrator may enable or disable support for certain types of credentials. See also: Settings

To authenticate, one presents a credential to prove their identity. Here are a few common types of credentials:

  • Username/Password: The most familiar type of credential, consisting of a username and a secret password.
  • API Key: A unique, random code assigned for this person or agent. It may be used indefinitely -- until someone deletes/revokes/replaces it. (See also: Sysadmin Guide: Setup: API Keys)
  • JSON Web Token (JWT): A dynamic, digitally-signed token which identifies this person. A JWT does not require any persistent storage, and it will expire automatically.

    How do you generate a JSON web token?

    If you are developing a patch or extension for CiviCRM, then you may generate a sign-in token as follows:

    $token = Civi::service('crypto.jwt')->encode([
      'exp' => time() + 5*60,       // Expires in 5 minutes
      'sub' => 'cid:203',           // Subject (contact ID)
      'scope' => 'authx',           // Allow general authentication
    ]);
    

    This example $token will be valid for login during the next five minutes.

Flows

TIP: The site administrator may enable or disable support for certain flows. See also: Settings

There are two general dataflows for HTTP authentication:

  • Stateless / Ephemeral: The client submits a singular HTTP request (such as an API call) which includes credentials. The request is authenticated and processed, and then it is forgotten.
  • Stateful / Persistent / Session: The client makes a request for a persistent session, attaching the contact ID and/or user ID. These will be used in subsequent requests.

For each general flow, we have a few variations.

Flow Name Description
Stateless Common Header
(header)
The credential is submitted with an HTTP header (Authorization: <credential>).
Stateless X-Header
(xheader)
The credential is submitted with a custom HTTP header (X-Civi-Auth: <credential>). This header is otherwise identical to Authorization:.
Stateless Parameter
(param)
The credential is submitted with an HTTP GET or POST parameter (?_authx=<credential>)
Stateless Legacy REST
(legacyrest)
The credential is submitted with a pair of HTTP parameters (?key=MY_SITE_KEY&api_key=MY_API_KEY). This is only valid for the route civicrm/ajax/rest.
Stateful Login session (login) The client explicitly logs in (POST /civicrm/authx/login) which creates a session and cookie.
Stateful Auto session (auto) The clients submits a GET request for any page (?_authx=<credential>&_authxSes=1). The session is initialized. The user redirects to original page.
What is <credential>?

In all cases, the <credential> is formatted per RFC-7617 ("Basic") or RFC-6750 ("Bearer"). For example:

  • Common Header: Authorization: Basic dXNlcjpwYXNz or Authorization: Bearer ZYXW9876
  • X-Header: X-Civi-Auth: Basic dXNlcjpwYXNz or X-Civi-Auth: Bearer ZYXW9876
  • Parameter: ?_authx=Basic+dXNlcjpwYXNz or ?_authx=Bearer+ZYXW9876
What's the difference between Common Header and X-Header?

The common Authorization: header is easier to integrate with external applications. However, this could be a double-edged sword - some environments may have extra or conflicted rules in how to handle Authorization:.

The custom header X-Civi-Auth: may require a little extra work for the downstream application. However, it is likely to bypass any middleware conflicts.

How do I test authentication?

You may send a request to /civicrm/authx/id, e.g.

curl -v 'https://example.com/civicrm/authx/id?_authx=Bearer+ZYXW9876'

If successful, it will respond with a JSON document describing the authenticated user:

> HTTP/1.1 200 OK
> Content-Type: application/json

{"contact_id":"202","user_id":"1","flow":"param","cred":"bearer"}
How do I manage an explicit session?

To login, submit the credential to /civicrm/authx/login. For example, this will login with username and password::

curl -v -X POST 'http://example.com/civicrm/authx/login' -d '_authx=Basic+dXNlcjpwYXNz'

If successful, it will respond with a session cookie and a summary of the logged-in user:

> HTTP/1.1 200 OK
> Set-Cookie: SESS1234=abcd1234; expires=Sat, 08-May-2021 12:28:19 GMT; Max-Age=2000000; path=/; domain=.example.com; HttpOnly
> Content-Type: application/json

{"contact_id":"202","user_id":"1","flow":"login","cred":"pass"}

You may now request any HTTP resources. Simply pass the Cookie in each HTTP request.

To logout, POST a request to /civicrm/authx/logout.

Guards

TIP: The site administrator may enable or disable support for certain types of guards. See also: Settings

A guard limits access to AuthX authentication services. By default, a user who presents a password or API key will only be authenticated if they can pass one of these guards:

How can I send the site key?

The site key can be passed with either:

  • X-Header: X-Civi-Key: 1234abc
  • Parameter: ?_authxSiteKey=1234abc
Why support both guards?

Traditional dataflows using APIv3 REST required the site-key as a guard. However, this is difficult to administer. The permission-guard is a more manageable alternative. Of course, we do not want to break backward-compatibility.

Do guards really prevent misuse?

Sort of.

Strictly, no. Regardless of how the user authenticates, the user will end up with the same permissions, so they can access the same records/actions/APIs/screens. Whether the user authenticates through a CMS login-form or AuthX, the upper-bound of malicious behavior is the same.

But there are still reasons why an administrator might limit access to AuthX, e.g.

  • They only wish to allow skilled/administrative users to make connections with off-the-shelf applications.
  • They wish to impose tighter rules (e.g. stricter password requirements) on users who have AuthX access.

Settings

For each authentication flow, one may toggle support for different credentials and user-links. Here is the default configuration:

Setting (Default) Description Version
authx_guards
(['site_key', 'perm'])
List of guards that permit authentication. If blank, then no guards are required. 5.36
authx_param_cred
(['jwt'])
List of credential-types that will be accepted via ?_authx parameters 5.36
authx_param_user
(optional)
Is it important to load a CMS user? (require, optional, ignore) 5.36
authx_header_cred
(['jwt'])
List of credential-types that will be accepted via Authorization: header 5.36
authx_header_user
(optional)
Is it important to load a CMS user? (require, optional, ignore) 5.36
authx_xheader_cred
(['jwt'])
List of credential-types that will be accepted via X-Civi-Auth: header 5.36
authx_xheader_user
(optional)
Is it important to load a CMS user? (require, optional, ignore) 5.36
authx_legacyrest_cred
(['jwt', 'api_key'])
List of credential-types that will be accepted via ?key=&api_key= parameters 5.47
authx_legacyrest_user
(require)
Is it important to load a CMS user? (require, optional, ignore) 5.47
authx_login_cred
(['jwt'])
List of credential-types that will be accepted on POST /civicrm/authx/login 5.36
authx_login_user
(require)
Is it important to load a CMS user? (require, optional, ignore) 5.36
authx_auto_cred
(['jwt'])
List of credential-types that will be accepted via ?_authx=...&_authxSes=1 parameters 5.36
authx_auto_user
(require)
Is it important to load a CMS user? (require, optional, ignore) 5.36
Example: Relax all settings to permit testing

The default settings are fairly restrictive. If you will be doing testing or development, then you might relax a number of settings:

cv ev 'Civi::settings()->set("authx_guards", []);'
cv ev 'Civi::settings()->set("authx_param_cred", ["jwt", "api_key", "pass"]);'
cv ev 'Civi::settings()->set("authx_header_cred", ["jwt", "api_key", "pass"]);'
cv ev 'Civi::settings()->set("authx_xheader_cred", ["jwt", "api_key", "pass"]);'
cv ev 'Civi::settings()->set("authx_login_cred", ["jwt", "api_key", "pass"]);'
cv ev 'Civi::settings()->set("authx_auto_cred", ["jwt", "api_key", "pass"]);'