-# authx
-
-
-
-(*FIXME: In one or two paragraphs, describe what the extension does and why one would download it. *)
-
-The extension is licensed under [AGPL-3.0](LICENSE.txt).
-
-## Requirements
-
-* PHP v7.0+
-* CiviCRM (*FIXME: Version number*)
-
-## Installation (Web UI)
-
-This extension has not yet been published for installation via the web UI.
-
-## Installation (CLI, Zip)
-
-Sysadmins and developers may download the `.zip` file for this extension and
-install it with the command-line tool [cv](https://github.com/civicrm/cv).
-
-```bash
-cd <extension-dir>
-cv dl authx@https://github.com/FIXME/authx/archive/master.zip
+# AuthX
+
+The AuthX extension provides support for additional authentication protocols on CiviCRM pages.
+This is useful for automated testing and developing multi-modal pageflows (eg email => HTTP).
+
+## Overview
+
+There are two general flows of authentication:
+
+* __Ephemeral / Stateless__: The client submits a singlular request (such as an API call) which includes credentials. The request is authenticated and processed, but then it is abandoned.
+ There are a couple flavors of stateless authentication:
+ * __Parameter (`param`)__: The credential is submitted with an HTTP GET or POST parameter (`?_authx=<credential>`)
+ * __Common Header (`header`)__: The credential is submitted with an HTTP (`Authorization:`). Depending on the credential, this will use either `Basic` or `Bearer`.
+ The standard header is easier to integrate with external applications; however, other features or plugins in the CMS may interfere with correct operation.
+ * __X-Header (`xheader`)__: The credential is again submitted with an HTTP header (`X-Civi-Auth:`). The header behaves the same as the common header. The
+ differing name means that clients must specifically support it, but it also reduces the odsd of interference.
+* __Persistent / Stateful__: The client makes a request for a persistent session, attaching the contact ID and/or user ID. These will be used in subsequent requests.
+ * __End-point session (`endpoint`)__: The client submits an explicit authentication request (`POST /civicrm/authx/login?_authx=<credential>`) which creates a session and cookie.
+ The authenticated session endures until one logs out (`/civicrm/authx/logout`).
+ * __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.
+
+Each flow may (configurably) accept any of these credentials:
+
+* __JSON Web Tokens (`jwt`)__: These tokens must be generated by Civi using a cryptographic signing key and expiration time.
+ The client submits the token as its sole credential.
+* __API Key (`api_key`)__: The user configures a value for `civicrm_contact.api_key`. The client submits
+ the token as its sole credential.
+* __Username/Password (`pass`)__: The client submits the username and password for a CMS user.
+
+CiviCRM `Contact` records are often linked to CMS `User` records -- but not always. There are different ways to approach this matching:
+
+* __Ignore__: Ignore any related `User` accounts. From a CMS perspective, the user is anonymous.
+* __Optional__: If there is a correlated CMS `User`, then load it. If there isn't, leave the CMS user as anonymous.
+* __Require__: Only allow authentication if proceed if there is a correlated user account.
+
+## Configuration
+
+For each authentication flow, one may toggle support for different credentials and user-links. Here is the default configuration:
+
+* Ephemeral: Parameter flow
+ * Accepted credentials (`authx_param_cred`): `['jwt']`
+ * User link (`authx_param_user`): `'optional'`
+* Ephemeral: Common header flow
+ * Accepted credentials (`authx_header_cred`): `['jwt']`
+ * User link (`authx_header_user`): `'optional'`
+* Ephemeral: X header flow
+ * Accepted credentials (`authx_xheader_cred`): `['jwt']`
+ * User link (`authx_xheader_user`): `'optional'`
+* Persistent: End-point session flow
+ * Accepted credentials (`authx_endpoint_cred`): `['jwt']`
+ * User link (`authx_endpoint_user`): `require`
+* Persistent: Auto session flow
+ * Accepted credentials (`authx_auto_cred`): `['paramalogin']` for Joomla, and `[]` for all others
+ * User link (`authx_auto_user`): `require`
+
+## Quirks and Compatibility
+
+Some modes may not be supported in some environments. For example:
+
+* __Joomla, WordPress__: Creates extraneous sessions (e.g. even if the request is for stateless authentication).
+* __WordPress__: The default `.htaccess` in WordPress may obscure the common `Authorization:` header. Fix this by adding:
+ ```
+ SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
+ ```
+
+## Examples
+
+### JSON Web Token
+
+```php
+// First, on the server, prepare a token
+$token = Civi::service('authx.jwt')->create([
+ 'contact_id' => 123,
+ 'ttl' => 5*60*60,
+]);
+
+// Next, on the client, use this same token
+$options = ['http' => [
+ 'method' => 'GET',
+ 'header' => 'Authorization: Bearer '.$token
+]];
+$context = stream_context_create($options);
+$response = file_get_contents($url, false, $context);
```
-## Installation (CLI, Git)
+### Username and Password
-Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git) repo for this extension and
-install it with the command-line tool [cv](https://github.com/civicrm/cv).
-
-```bash
-git clone https://github.com/FIXME/authx.git
-cv en authx
+```php
+$auth = base64_encode("username:password");
+$context = stream_context_create([
+ "http" => [
+ "header" => "Authorization: Basic $auth"
+ ]
+]);
+$homepage = file_get_contents("http://example.com/file", false, $context );
```
-
-## Usage
-
-(* FIXME: Where would a new user navigate to get started? What changes would they see? *)
-
-## Known Issues
-
-(* FIXME *)
projects / civicrm-core.git / commitdiff