From: Tim Otten Date: Fri, 12 Feb 2021 20:50:54 +0000 (-0800) Subject: authx - Draft README and info.xml X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=9e99ef4ac3062e47877cfa8199e6ce0cf4c2e906;p=civicrm-core.git authx - Draft README and info.xml --- diff --git a/ext/authx/README.md b/ext/authx/README.md index dec2a88cdd..478414b320 100644 --- a/ext/authx/README.md +++ b/ext/authx/README.md @@ -1,44 +1,97 @@ -# authx - -![Screenshot](/images/screenshot.png) - -(*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 -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=`) + * __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=`) 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=&_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 *) diff --git a/ext/authx/info.xml b/ext/authx/info.xml index 5534ad5c22..cfd4bdfce2 100644 --- a/ext/authx/info.xml +++ b/ext/authx/info.xml @@ -1,8 +1,8 @@ authx - FIXME - FIXME + AuthX + Extended authentication module AGPL-3.0 Tim Otten