DOC Update docs

Author: emteknetnz

README.md

@@ -383,38 +383,41 @@ The `x-csrf-token` header is available as a constant on `RestApiEndpoint::CSRF_T
 
 ## API token<a name="readme-api-token"></a>
 
-API's can be setup to allow members to authenticate with an `x-api-token` HTTP header instead of having to log in to the CMS.
+Non-public API's can be configured to allow members to authenticate using an HTTP header instead of having to log in to the CMS.
 
-If API authenticate is used, the member will be logged in only for the duration of the request i.e. they will be logged out before the JSON response is returned.
+If API authentication is used, the user will be logged in only for the duration of the request i.e. they will be logged out before the JSON response is returned.
+
+This module provides a permission "Use an API token" which is `API_TOKEN_AUTHENTICATION` which must be assigned to a group that users using API tokens must belong to. The endpoints `ALLOW_API_ACCESS` config must be set to `true`.
+
+When a user and endpoint is set up to allow using an API token, pass an `x-api-token` header with the value of the API Token to authenticate. Note that API token authentication will bypass MFA if it was set up for that user.
+
+### Setting up an API user and group using the CMS
+
+#### Creating the API user and group
 
-### Creating groups and users in the CMS
 1. Log in to the CMS as an administrator
+1. Go to the Security section
 1. Create a new group called "API Users"
-1. In the Permissions tab (top right), tick "Use an API token" - this is the label for the permission code `API_TOKEN_AUTHENTICATION`
+1. Click on the Permissions tab (top right)
+1. Tick "Use an API token" - this is the label for the permission code `API_TOKEN_AUTHENTICATION`
 1. Save the Group
 1. Click "Add Member"
 1. Create a new user with a "First name" of "api-user", an Email of "api-user@example.com", and a long random password
 1. Assign them to the "Api Users" group
 1. Tick the "Generate new API token" checkbox and click "Save"
 1. Copy the API token that is generated - you will only be shown this once
 
-### Additional member permissions
-1. The "api-user" still needs to pass all necessary permissions checks for the API to work
-1. You can either update the "API Users" group to have the necessary permissions, or
-1. Set the api end point `RestApiEndoint::CHECK_CAN_METHODS` to `RestApiEndoint::NONE` though if you do this you *MUST* ensure that the API `RestApiEndoint::ACCESS` is set to a permission code, not merely `RestApiEndpoint::LOGGED_IN`.
+#### Additional group permissions
+
+The "api-user" still needs to pass all necessary permissions checks for the API to work i.e. so that `canView()` checks still pass. You can either:
+- Update the "API Users" group to have the necessary permissions, or
+- Set the endpoints `CHECK_CAN_METHODS` to `NONE` though you *MUST* ensure that the API `ACCESS` is set to a permission code that is only assigned to dedicated api users.
 
-### Update endpoint $api_config
-1. Set `RestApiEndpoint::ALLOW_API_ACCESS` to `true`
-1. Set `RestApiEndpoint::ACCESS` to `ApiTokenPermissionProvider::API_TOKEN_AUTHENTICATION` for the strictest access control (recommended). Note the API can still be accessed without a API token if the member with the "Use an API token" logs in the the CMS.
-1. Alternatively, set this to `RestApiEndpoint::LOGGED_IN` to allow any logged in user to use the API, including without an API token, though to use the API member must be in a group with the "Use an API token" permission in order to authenticate
-1. Run `dev/build flush=1` for the configuration to take effect
+### Programmatically updating a users API token
 
-### Using the API token authentication
-1. Pass an `x-api-token` header with the value of the API Token
+Programmatically update a users API token with `$member->refreshApiToken();` followed by `$member->write();`. The returned value is the unencrypted API token. The members `ApiToken` field will be the encrypted API token.
 
-### Programatically updating a members ApiToken
-1. Call `$member->refreshApiToken()`. The returned value is the unencrypted API token. The members `ApiToken` field will be the encrypted API token.
-1. Call `$member->write()`
+Note that for newly created users, `$member->write()` must be called at least once before calling `$member->refreshApiToken();` to ensure that the API token is properly encrypted.
 
 ## Extension hooks<a name="readme-extension-hooks"></a>
 

src/Controllers/RestApiEndpoint.php

@@ -14,7 +14,6 @@
 use SilverStripe\Security\Permission;
 use stdClass;
 use emteknetnz\RestApi\Exceptions\RestApiEndpointConfigException;
-use emteknetnz\RestApi\PermissionProviders\ApiTokenPermissionProvider;
 use SilverStripe\ORM\DataObjectSchema;
 use SilverStripe\ORM\ValidationException;
 use SilverStripe\Security\SecurityToken;
@@ -49,6 +48,8 @@ abstract class RestApiEndpoint extends Controller
     public const DELIMITER = '_';
     public const CREATE_EDIT_DELETE_ACTION = 'CREATE_EDIT_DELETE_ACTION';
     public const VIEW_CREATE_EDIT_DELETE_ACTION = 'VIEW_CREATE_EDIT_DELETE_ACTION';
+    // permissions
+    public const API_TOKEN_AUTHENTICATION = 'API_TOKEN_AUTHENTICATION';
     // other constants
     public const CSRF_TOKEN_HEADER = 'x-csrf-token';
     public const API_TOKEN_HEADER = 'x-api-token';
@@ -140,7 +141,7 @@ private function authenticateWithApiToken(): void
         if ($apiToken) {
             $this->currentLoggedInMember = Security::getCurrentUser();
             // find members in groups with the API_TOKEN_AUTHENTICATION permission
-            $groups = Permission::get_groups_by_permission(ApiTokenPermissionProvider::API_TOKEN_AUTHENTICATION);
+            $groups = Permission::get_groups_by_permission(self::API_TOKEN_AUTHENTICATION);
             $members = [];
             foreach ($groups as $group) {
                 foreach ($group->Members() as $member) {

src/Extensions/ApiTokenMemberExtension.php

@@ -2,7 +2,7 @@
 
 namespace emteknetnz\RestApi\Extensions;
 
-use emteknetnz\RestApi\PermissionProviders\ApiTokenPermissionProvider;
+use emteknetnz\RestApi\Controllers\RestApiEndpoint;
 use SilverStripe\Core\Extension;
 use SilverStripe\Forms\CheckboxField;
 use SilverStripe\Forms\FieldList;
@@ -40,7 +40,7 @@ public function updateCMSFields(FieldList $fields): void
         // Never show the encrypted API token database field
         $fields->removeByName('ApiToken');
         // Check the user is allowed to use API tokens
-        $code = ApiTokenPermissionProvider::API_TOKEN_AUTHENTICATION;
+        $code = RestApiEndpoint::API_TOKEN_AUTHENTICATION;
         if (!Permission::checkMember($member, $code)) {
             return;
         }

src/PermissionProviders/ApiTokenPermissionProvider.php

@@ -3,15 +3,16 @@
 namespace emteknetnz\RestApi\PermissionProviders;
 
 use SilverStripe\Security\PermissionProvider;
+use emteknetnz\RestApi\Controllers\RestApiEndpoint;
 
+// This exists as a standalone class rather than simply putting it on RestApiEndpoint because that is an abstract
+// class which cannot be instantiated and therefore cannot be used as a permission provider.
 class ApiTokenPermissionProvider implements PermissionProvider
 {
-    public const API_TOKEN_AUTHENTICATION = 'API_TOKEN_AUTHENTICATION';
-
     public function providePermissions()
     {
         return [
-            self::API_TOKEN_AUTHENTICATION => 'Use an API token',
+            RestApiEndpoint::API_TOKEN_AUTHENTICATION => 'Use an API token',
         ];
     }
 }

tests/Controllers/RestApiEndpointTest.php

@@ -18,7 +18,6 @@
 use emteknetnz\RestApi\Exceptions\RestApiEndpointConfigException;
 use SilverStripe\Security\SecurityToken;
 use emteknetnz\RestApi\Tests\Controllers\RestApiTest\TestVersionedExtension;
-use emteknetnz\RestApi\PermissionProviders\ApiTokenPermissionProvider;
 use SilverStripe\Security\Group;
 use SilverStripe\Security\Member;
 use SilverStripe\Security\Permission;
@@ -58,6 +57,8 @@ class RestApiEndpointTest extends FunctionalTest
     public const DELIMITER = '_';
     public const CREATE_EDIT_DELETE_ACTION = 'CREATE_EDIT_DELETE_ACTION';
     public const VIEW_CREATE_EDIT_DELETE_ACTION = 'VIEW_CREATE_EDIT_DELETE_ACTION';
+    // permissions
+    public const API_TOKEN_AUTHENTICATION = 'API_TOKEN_AUTHENTICATION';
     // other consts
     public const CSRF_TOKEN_HEADER = 'x-csrf-token';
     public const API_TOKEN_HEADER = 'x-api-token';
@@ -372,7 +373,7 @@ public function provideCsrfToken(): array
     public function testApiTokenAuthentication(bool $allowApiToken, int $expectedStatusCode)
     {
         $this->setConfig(self::ALLOW_API_TOKEN, $allowApiToken);
-        $code = ApiTokenPermissionProvider::API_TOKEN_AUTHENTICATION;
+        $code = self::API_TOKEN_AUTHENTICATION;
         // update config to use api token authentication
         $this->setConfig(self::ACCESS, $code);
         // create a group + member