From 3f8e3a317e1bcce6ea2d1aee5249f107357dba97 Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Tue, 9 Apr 2024 16:08:56 +1200 Subject: [PATCH] DOC Linting --- .doclintrc | 1 + README.md | 71 ++------------------------------------- composer.json | 6 ++++ docs/en/index.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 97 insertions(+), 68 deletions(-) create mode 100644 .doclintrc create mode 100644 docs/en/index.md diff --git a/.doclintrc b/.doclintrc new file mode 100644 index 0000000..15a00f5 --- /dev/null +++ b/.doclintrc @@ -0,0 +1 @@ +/docs/en/ diff --git a/README.md b/README.md index 4bc1fd8..5ad4c08 100644 --- a/README.md +++ b/README.md @@ -13,78 +13,13 @@ For more information about TOTP, see [RFC 6238](https://tools.ietf.org/html/rfc6 ## Installation -```sh +```bash composer require silverstripe/totp-authenticator ``` -## Configuration +## Documentation -### Encryption key - -You will need to define an environment variable named `SS_MFA_SECRET_KEY` with a random secret key, which is used -for encrypting the TOTP secret. The authentication method will not be available for use until this is correctly defined. - -Please note that existing registered TOTP methods for users will not be usable on environments with different values -for `SS_MFA_SECRET_KEY` than they were registered in. - -There are many ways to create a random secret key, the easiest -is by executing a `php` command on the command line. The secret key length depends on your -specific information security controls, but 32 characters is a good baseline. - -``` -php -r 'echo substr(base64_encode(random_bytes(32)), 0, 32) . "\n";' -``` - -### TOTP secret length - -You can also configure the length of the TOTP secret. This is the code that is displayed to users when they register -to use TOTP, for example "alternatively, enter this code manually into your app." The default length is 16 characters. -If you do not want to support manual code entry in your project, you may want to increase the length in order to -increase the entropy of the TOTP secret, however removing the secret from the UI will require adjustments to the React -components. See the `RegisterHandler.secret_length` configuration property. - -```yaml -SilverStripe\TOTP\RegisterHandler: - secret_length: 64 -``` - -### TOTP code length - -If you want to change the length of the TOTP codes the application accepts, you can adjust `Method.code_length`. The -default length is 6 characters. - -```yaml -SilverStripe\TOTP\Method: - code_length: 10 -``` - -### User help link - -When this method is used on the website during the multi-factor login process, it may show a "find out more" link -to user documentation. You can disable this by nullifying the configuration property `RegisterHandler.user_help_link` -or you can change it to point to your own documentation instead: - -```yaml -SilverStripe\TOTP\RegisterHandler: - user_help_link: 'https://intranet.mycompany.com/help-docs/using-totp' -``` - -### TOTP issuer and label - -The TOTP "issuer" is the Silverstripe site name (set in SiteConfig) by default, and the "label" is the member's email -address by default. These are the values that show up in your authenticator app. You can change these if you need -to use something else, by writing an extension on `RegisterHandler`: - -```php -class MyTOTPRegisterHandlerExtension extends Extension -{ - public function updateTotp(\OTPHP\TOTPInterface $totp, \SilverStripe\Security\Member $member) - { - $totp->setLabel($member->getCustomTOTPLabel()); - $totp->setIssuer('My web project'); - } -} -``` +Read the [TOTP authenticator documentation](https://docs.silverstripe.org/en/optional_features/mfa/authentictors/totp). ## License diff --git a/composer.json b/composer.json index d23c219..7f965f6 100644 --- a/composer.json +++ b/composer.json @@ -22,6 +22,7 @@ "require-dev": { "phpunit/phpunit": "^9.6", "squizlabs/php_codesniffer": "^3", + "silverstripe/documentation-lint": "^1", "silverstripe/recipe-testing": "^3", "silverstripe/webauthn-authenticator": "^5", "silverstripe/frameworktest": "^1", @@ -41,6 +42,11 @@ "client/lang" ] }, + "config": { + "allow-plugins": { + "dealerdirect/phpcodesniffer-composer-installer": true + } + }, "minimum-stability": "dev", "prefer-stable": true } diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..a4c90b7 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,87 @@ +--- +title: TOTP authenticator +--- + +# TOTP authenticator + +## Installation + +```bash +composer require silverstripe/totp-authenticator +``` + +## Configuration + +### Encryption key + +You will need to define an environment variable named `SS_MFA_SECRET_KEY` with a random secret key, which is used +for encrypting the TOTP secret. The authentication method will not be available for use until this is correctly defined. + +Please note that existing registered TOTP methods for users will not be usable on environments with different values +for `SS_MFA_SECRET_KEY` than they were registered in. + +There are many ways to create a random secret key, the easiest +is by executing a `php` command on the command line. The secret key length depends on your +specific information security controls, but 32 characters is a good baseline. + +```bash +php -r 'echo substr(base64_encode(random_bytes(32)), 0, 32) . "\n";' +``` + +### TOTP secret length + +You can also configure the length of the TOTP secret. This is the code that is displayed to users when they register +to use TOTP, for example "alternatively, enter this code manually into your app." The default length is 16 characters. +If you do not want to support manual code entry in your project, you may want to increase the length in order to +increase the entropy of the TOTP secret, however removing the secret from the UI will require adjustments to the React +components. See the [`RegisterHandler.secret_length`](api:SilverStripe\MFA\BackupCode\RegisterHandler->secret_length) configuration property. + +```yml +SilverStripe\TOTP\RegisterHandler: + secret_length: 64 +``` + +### TOTP code length + +If you want to change the length of the TOTP codes the application accepts, you can adjust [`Method.code_length`](api:SilverStripe\TOTP\Method->code_length). The +default length is 6 characters. + +```yml +SilverStripe\TOTP\Method: + code_length: 10 +``` + +### User help link + +When this method is used on the website during the multi-factor login process, it may show a "find out more" link +to user documentation. You can disable this by nullifying the configuration property [`RegisterHandler.user_help_link`](api:SilverStripe\TOTP\RegisterHandler->user_help_link) +or you can change it to point to your own documentation instead: + +```yml +SilverStripe\TOTP\RegisterHandler: + user_help_link: 'https://intranet.mycompany.com/help-docs/using-totp' +``` + +### TOTP issuer and label + +The TOTP "issuer" is the Silverstripe site name (set in SiteConfig) by default, and the "label" is the member's email +address by default. These are the values that show up in your authenticator app. You can change these if you need +to use something else, by writing an extension on `RegisterHandler`: + +```php +// app/src/MFA/Extensions/MyTOTPRegisterHandlerExtension.php +namespace App\MFA\Extensions; + +use OTPHP\TOTPInterface; +use SilverStripe\Core\Extension; +use SilverStripe\Security\Member; + +class MyTOTPRegisterHandlerExtension extends Extension +{ + public function updateTotp(TOTPInterface $totp, Member $member) + { + $totp->setLabel($member->getCustomTOTPLabel()); + $totp->setIssuer('My web project'); + } +} +```