Update doc [skip ci].

Author: vuongxuongminh

.gitattributes

@@ -2,6 +2,7 @@
 
 /assets export-ignore
 /tests export-ignore
+/src/Resources/doc export-ignore
 /.gitattributes export-ignore
 /.github export-ignore
 /.gitignore export-ignore

README.md

@@ -7,9 +7,12 @@
 
 ## About
 
-This bundle provides JWT authentication for request forwarded by Istio sidecar. 
+The Symfony bundle provides JWT authentication for request forwarded by Istio sidecar. 
 
-> To use this bundle, ensure your application container had injected Istio sidecar and Istio [RequestAuthentication](https://istio.io/latest/docs/reference/config/security/request_authentication/) CRD had configured, if not your application **IS NOT SECURE**.
+> To use this bundle, make sure your K8S application pod had injected Istio sidecar and [RequestAuthentication](https://istio.io/latest/docs/reference/config/security/request_authentication/) CRD had configured, if not your application **IS NOT SECURE**.
+
+The difference between this bundle and the awesome [Lexik JWT Authentication](https://github.com/lexik/LexikJWTAuthenticationBundle) bundle is it's **NOT** validate JWT token because Istio sidecar proxy had validated before forward request to your application,
+so that your application don't need to hold public key and double validate JWT token.
 
 ## Requirements
 
@@ -27,9 +30,80 @@ Symfony versions:
 composer require php-istio/jwt-authentication-bundle
 ```
 
-## Document
+## Configuration
+
+Enable [the authenticator manager](https://symfony.com/doc/current/security/authenticator_manager.html) setting:
+
+```yaml
+# config/packages/security.yaml
+security:
+  enable_authenticator_manager: true
+  # ...
+```
+
+Configure your `config/packages/security.yaml`:
+
+```yaml
+security:
+  enable_authenticator_manager: true
+  access_control: 
+    - path: ^/
+      roles: IS_AUTHENTICATED_FULLY
+  firewalls:
+    #...
+    main:
+      stateless: true
+      istio_jwt_authenticator:
+        - issuer: issuer_1 # Required
+          user_identifier_claim: sub #Default is `sub` claim
+          origin_token_headers: [authorization] #Required at least once of `origin_token_headers`, `origin_token_query_params` or `base64_headers`. Use this option when your Istio JWTRule CRD using `forwardOriginalToken`.
+          origin_token_query_params: [token] #Use this option when your Istio JWTRule CRD using `forwardOriginalToken` and your JWT token in query param.
+          base64_headers: [x-istio-jwt-payload] # Use this option when your Istio JWTRule CRD using `outputPayloadToHeader`.
+```
+
+In case your application have multi issuers:
+
+```yaml
+#....
+    main:
+      stateless: true
+      istio_jwt_authenticator:
+        - issuer: issuer_1
+          origin_token_headers: [authorization]
+        - issuer: issuer_2
+          user_identifier_claim: aud
+          base64_headers: [x-istio-jwt-payload]
+        #....
+```
+
+
+## Usages
+
+Generate mock JWT token forwarded by Istio sidecar:
+
+```shell
+payload='{"issuer":"issuer_1", "sub": "test"}'; \
+base64_payload=$(echo -n $payload | base64 -); \
+origin_token=$(echo "header.$base64_payload.signature")
+```
+
+You can test authenticate origin token with curl:
+
+```shell
+curl -H "Authorization: $origin_token" http://localhost/
+```
+
+Or authenticate base64 payload header:
+
+```shell
+curl -H "X-Istio-JWT-Payload: $base64_header" http://localhost/
+```
 
+## Further readings:
 
++ [Get JWT payload of authenticated user](src/Resources/doc/stateless-user-provider.md)
++ [Use stateless user provider](src/Resources/doc/stateless-user-provider.md)
++ [Create custom user provider](src/Resources/doc/create-custom-user-provider.md)
 
 ## Credits
 

src/Resources/doc/create-custom-user-provider.md

@@ -0,0 +1,36 @@
+Create custom user provider
+=============================
+
+In case [stateless user provider](stateless-user-provider.md) not fit to your requirements, you can create your own [custom user provider](https://symfony.com/doc/current/security/user_provider.html#creating-a-custom-user-provider) 
+implement [JWTPayloadAwareUserProviderInterface](/src/User/JWTPayloadAwareUserProviderInterface.php)
+when you want to create user instance depend on JWT payload. 
+This interface base on Symfony `UserProviderInterface` just add more optional arg `$payload` to `loadUserByIdentifier` method.
+
+Configuring the user provider
+-----------------------------
+Config custom user provider in `security.yaml`:
+
+```yaml
+# config/packages/security.yaml
+security:
+    providers:
+      jwt:
+        id: App\Security\UserProvider # your user provider service id, change it if you want.
+```
+
+#### Sample implementation
+
+```php
+namespace App\Security;
+
+use Istio\Symfony\JWTAuthentication\User\JWTPayloadAwareUserProviderInterface;
+
+final class UserProvider implements JWTPayloadAwareUserProviderInterface {
+    
+    //.... 
+    public function loadUserByIdentifier(string $identifier, array $payload = null) {
+       // use $identifier and $payload to create `UserInterface` instance.
+    }
+    
+}
+```

src/Resources/doc/get-jwt-payload-of-authenticated-user.md

@@ -0,0 +1,24 @@
+Get JWT payload of authenticated user
+=============================
+
+You can get JWT payload of authenticated user via `jwt_payload` attribute in security token.
+
+#### Sample:
+
+```php
+<?php
+
+namespace App\Services;
+
+use Symfony\Component\Security\Core\Security;
+
+class MyService {
+
+    public function __construct(Security $security) {
+        $security->getToken()->getAttribute('jwt_payload');
+    }
+    
+}
+```
+
+

src/Resources/doc/stateless-user-provider.md

@@ -0,0 +1,45 @@
+A stateless user provider
+=============================
+
+This feature inspired by the awesome [Lexik JWT Authentication](https://github.com/lexik/LexikJWTAuthenticationBundle) bundle.
+
+Stateless user provider help to create user instances from the JWT payload.
+
+Configuring the user provider
+-----------------------------
+
+First, you need to config `istio_jwt_stateless` provider in `security.yaml`:
+
+```yaml
+# config/packages/security.yaml
+security:
+    providers:
+      jwt:
+        istio_jwt_stateless:
+          class: App\Security\User # your user class, you can change it if you want.
+```
+
+Then, create a user class `istio_jwt_stateless.class` had set in config, in this case is `App\Security\User`, this class need to implement [StatelessUserInterface](/src/User/StatelessUserInterface.php).
+This interface contains only a `fromPayload(array $payload)` method returns an instance of the class.
+
+#### Sample implementation
+
+```php
+namespace App\Security;
+
+use Istio\Symfony\JWTAuthentication\User\StatelessUserInterface;
+
+final class User implements StatelessUserInterface
+{
+    //....
+    
+    public static function fromPayload(array $payload): static
+    {
+        $instance = new static();
+        
+        // use $payload to config your user instance.
+        
+        return $instance;
+    }
+}
+```