add HTTP Bearer auth documentation

Author: zamronypj

configuration/index.md

@@ -14,17 +14,21 @@ Fano Framework provides `IAppConfiguration` interface for that purpose.
 
 ## IAppConfiguration
 
-`IAppConfiguration` interface provides two methods
+`IAppConfiguration` interface provides several methods,
 
-- `getString()` which accepts name and returns string value
-- `getInt()` which accept name returns integer value
-- `getBool()` which accept name returns boolean value
+- `getString()` accepts name and returns string value.
+- `getInt()` accepts name returns integer value.
+- `getBool()` accepts name returns boolean value.
+- `getFloat()` accepts name returns double value.
+- `has()` test if name is exists in configuration.
 
 ## Built-in IAppConfiguration implementation
 
-Fano Framework provides `TJsonFileConfig` and `TIniFileConfig` class which loads configuration data from JSON and INI file respectively. Also available `TNullConfig` which is null class implements `IAppConfiguration` interface.
+Fano Framework provides `TJsonFileConfig`, `TIniFileConfig`, `TEnvConfig` class which loads configuration data from JSON, INI file and environment variables respectively.
 
-Load config from JSON,
+Fano Framework also provides `TCompositeConfig` and `TNullConfig` class. First one is `IAppConfiguration` implementation with capability to combine two`IAppConfiguration` instance and latter is null class implements `IAppConfiguration` interface.
+
+### Load config from JSON
 
 ```
 var config : IAppConfiguration;
@@ -34,7 +38,7 @@ config := TJsonFileConfig.create(
 );
 ```
 
-Load config from INI,
+### Load config from INI
 
 ```
 var config : IAppConfiguration;
@@ -46,9 +50,36 @@ config := TIniFileConfig.create(
 ```
 Last parameter is name of default section to use. Read [INI file configuration](#ini-file-configuration) section in this document for more information.
 
-To be able to use `TJsonFileConfig` and `TIniFileConfig` class with [dependency container](/dependency-container), Fano Framework provides `TJsonFileConfigFactory` and `TIniFileConfigFactory` class which enables you to register above classes in container.
+### Load configuration from environment variables
+
+```
+var config : IAppConfiguration;
+...
+config := TEnvConfig.create();
+```
+
+### Combine multiple configurations as one
+
+`TCompositeConfig` allows you to use multiple configurations. In following setup,
+if configuration not found in environment variables, then it will try to find it in
+config.json.
+
+```
+var config : IAppConfiguration;
+...
+config := TCompositeConfig.create(
+    TEnvConfig.create(),
+    TJsonFileConfig.create(
+        getCurrentDir() + '/config/config.json'
+    )
+);
+```
+
+## Register config instance to dependency container
+
+To be able to use `TJsonFileConfig`, `TIniFileConfig`, `TEnvConfig`, `TCompositeConfig` and `TNullConfig` class with [dependency container](/dependency-container), Fano Framework provides `TJsonFileConfigFactory`, `TIniFileConfigFactory`, `TEnvConfigFactory`, `TCompositeConfigFactory` and `TNullConfigFactory` class which enables you to register above classes in container.
 
-Register JSON config
+### Register JSON config
 ```
 container.add(
     'config',
@@ -58,7 +89,7 @@ container.add(
 );
 ```
 
-Register INI config
+### Register INI config
 ```
 container.add(
     'config',
@@ -68,6 +99,26 @@ container.add(
 );
 ```
 
+### Register environment variable config
+```
+container.add(
+    'config',
+    TEnvConfigFactory.create()
+);
+```
+
+### Register composite configurations
+```
+container.add(
+    'config',
+    TCompositeConfigFactory.create(
+        TNullConfigFactory.create(),
+        TJsonFileConfigFactory.create(getCurrentDir() + '/config/config.json')
+    )
+);
+```
+
+### Retrieve configuration instance from dependency container
 
 To get configuration instance
 
@@ -76,6 +127,11 @@ var config : IAppConfiguration;
 ...
 config := container.get('config') as IAppConfiguration;
 ```
+or with array-like syntax
+
+```
+config := container['config'] as IAppConfiguration;
+```
 
 ## Read configuration data
 
@@ -123,6 +179,15 @@ var cookieMaxAge : integer;
 cookieMaxAge := config.getInt('cookie.maxAge');
 ```
 
+`getString()`, `getInt()`, `getBool()` and `getFloat()` methods accept second parameter
+if you want to use different value when key does not exist.
+
+```
+baseUrl := config.getString('baseUrl', 'https://example.com');
+```
+If key `baseUrl` is not found, it returns second parameter value.
+
+
 ## <a name="ini-file-configuration"></a>INI file configuration
 
 `TIniFileConfig` is thin wrapper of Free Pascal `TIniFile`. `TIniFile` cannot read data from INI file that has no section. Your INI file must contain at least one section which serve as default section. The last parameter of `TIniFileConfig`'s constructor expect name of default section. If you use `TIniFileConfigFactory`, by default it uses `fano` as default section if not specified. You can specify default section by calling `setDefaultSection()` method as shown in following code.

security/http-authentication/index.md

@@ -158,13 +158,62 @@ router.get('/', container['homeController'] as IRequestHandler)
     .add(container['digestAuthMiddleware'] as IMiddleware);
 ```
 
+## Handling Bearer Authentication with middleware
+
+Fano Framework provides implementation for bearer type HTTP authentication with
+`TBearerAuthMiddleware` middleware with purpose to simplify task to protect access of certain routes using Bearer HTTP authentication scheme.
+
+Constructor of `TBearerAuthMiddleware` expects three parameters,
+
+- Instance of `ITokenVerifier` interface which is responsible to perform actual token verification.
+- String of realm name.
+- String of credential key name where authenticated credential can be queried from request.
+
+Currently, Fano Framework supports JSON Web Token (JWT) verification only via `TJwtTokenVerifier`
+class which implements `ITokenVerifier` interface.
+
+After token is verified, credential info found in token is stored in request which later can be queried
+in controller using name you defined in credential key name.
+
+## Register Bearer Authentication middleware with container
+
+Fano Framework has `TBearerAuthMiddlewareFactory` class
+which allows you to register `TBearerAuthMiddleware` into service container.
+
+```
+container.add(
+    'bearerAuth',
+    TBearerAuthMiddlewareFactory.create()
+        .realm('fano-realm')
+        .verifier(container['tokenVerifier'] as ITokenVerifier)
+);
+```
+
+## Attach Bearer Auth middleware to application routes
+
+Attach bearer auth middleware instance to application routes, for example
+
+```
+router.get('/', container['homeController'] as IRequestHandler)
+    .add(container['bearerAuth'] as IMiddleware);
+```
+For every GET request to URL `/`, middleware will check token existence and verify
+if it is found. If token is not found or not verified, it returns HTTP 401 response
+with `WWW-Authenticate: Bearer realm="[realm name]"` header,
+where `[realm name]` is realm that you set above.
+
 ## Security consideration
 
 For Basic HTTP authentication scheme, username and password is transmitted as Base64-encoded string. It is prone to man in middle attack and it is must be used in conjunction with SSL/TLS.
 
 Digest HTTP authentication scheme is more computation expensive but can be used with or without SSL/TLS because password and other data is sent to server as MD5 hashed value. However, because MD5 hash is not cryptographically strong, you need to be cautious when use it without SSL/TLS.
 
-If your application is running behind reverse proxy, for example, with `mod_proxy_scgi` module, Apache does not pass `Authorization` header to application because of security concern.
+For Bearer HTTP authentication, token is credential. It must be used in conjunction with SSL/TLS
+to avoid man in middle attack. Token may or may not be encrypted. If you use
+unencrypted JWT token, do not store sensitive data in token.
+
+### Missing Authorization header
+If your application is running behind reverse proxy, for example, with `mod_proxy_scgi` module, Apache does not pass `Authorization` header to application because of security concern. This will cause all middlewares above return HTTP 401 as they can not find this header.
 
 In case, you have trusted network between Apache and your application, simple solution is to transform `Authorization` header into `HTTP_AUTHORIZATION` environment variable using `mod_rewrite` module.
 

security/password-hash/index.md

@@ -11,9 +11,9 @@ description: Password hash in Fano Framework
 
 ## Password hash and verification
 
-Fano Framework provides several password hash algorithm based on [HashLib4Pascal library](https://github.com/Xor-el/HashLib4Pascal).
+Fano Framework provides several password hash algorithm based on [HashLib4Pascal](https://github.com/Xor-el/HashLib4Pascal) and [BCrypt](https://github.com/viniciussanchez/bcrypt) libraries.
 
-Fano Framework provides simple wrapper for this library through `IPasswordHash` interface.
+Fano Framework provides simple wrapper for these libraries through `IPasswordHash` interface.
 
 ### Generate password hash
 
@@ -53,8 +53,7 @@ passwHash.salt('some random value');
 
 #### Cost
 To make generating password expensive, some password hash algorithm requires you to set number of iterations as cost of algorithm.
-Higher value usually means higher computation resources. You should think carefully about this value as this is trade-off between
-security and performance.
+Higher value usually means higher computation resources. You should think carefully about this value as this is trade-off between security and performance.
 
 To set cost, call `cost()` method with integer value for cost.
 This method returns current password hash instance.
@@ -64,15 +63,15 @@ passwHash.cost(1024);
 ```
 
 #### Memory cost
-Some algorithm employ memory cost.
+Some algorithm employs memory cost, such as Argon2i. For other, this value is ignored.
 
 To set memory cost, you call `memory()` method of `IPasswordHash` interface. This method returns current password hash instance.
 
 ```
 passwHash.memory(32);
 ```
 #### Paralleism
-Some algorithm employ paralleism cost.
+Some algorithm employs paralleism cost.
 
 To set paralleism cost, you call `paralleism()` method of `IPasswordHash` interface. This method returns current password hash instance.
 
@@ -97,7 +96,7 @@ passwHash.len(64);
 
 ## Available password hash implementations
 
-Currently, Fano Framework provides `IPasswordHash` implementation for [Argon2i](https://en.wikipedia.org/wiki/Argon2), [PBKDF2](https://tools.ietf.org/html/rfc2898), [Scrypt](https://tools.ietf.org/html/rfc7914) and SHA2.
+Currently, Fano Framework provides `IPasswordHash` implementation for [Argon2i](https://en.wikipedia.org/wiki/Argon2), [PBKDF2](https://tools.ietf.org/html/rfc2898), [Scrypt](https://tools.ietf.org/html/rfc7914), [BCrypt](https://en.wikipedia.org/wiki/Bcrypt) and SHA2.
 
 ### PBKDF2 password hash
 
@@ -124,6 +123,19 @@ container.add('passwHash', TArgon2iPasswordHashFactory.create());
 ```
 See PBKDF2 code above to retrieve password hash instance.
 
+You can set initial setting values for password hash instance, for example
+
+```
+container.add(
+    'passwHash',
+    TArgon2iPasswordHashFactory.create()
+        .cost(4)
+        .memory(32)
+        .paralleism(4)
+        .len(32)
+);
+```
+
 ### Scrypt password hash
 
 To use Scrypt password hash, you need to use `TScryptPasswordHash` class. You can register this class with dependency container using its factory class `TScryptPasswordHashFactory`.
@@ -133,6 +145,15 @@ To register password hash,
 container.add('passwHash', TScryptPasswordHashFactory.create());
 ```
 
+### BCrypt password hash
+
+To use BCrypt password hash, you need to use `TBcryptPasswordHash` class. You can register this class with dependency container using its factory class `TBcryptPasswordHashFactory`.
+
+To register password hash,
+```
+container.add('passwHash', TBcryptPasswordHashFactory.create());
+```
+
 ### SHA2 password hash
 
 While you are advised not to use SHA2 for password hash, Fano Framework provides `IPasswordHash` implementation for SHA1 256 bit and 512 bit using `TSHA2_256PasswordHash` and `TSHA2_512PasswordHash` class.