[servicecomb-fence] 08/12: [SCB-1319]update docs and add design diagram

[li...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-fence.git

commit b078c954c2a4689092005abaaaf041ebae7951cc
Author: liubao <bi...@qq.com>
AuthorDate: Mon Jun 17 17:02:21 2019 +0800

    [SCB-1319]update docs and add design diagram
---
 README.md                     |   9 ++++++
 README_ZH.md                  |   9 ++++++
 docs/authentication.png       | Bin 0 -> 85676 bytes
 docs/authorization.png        | Bin 0 -> 79697 bytes
 docs/zh_CN/developersGuide.md |  72 ++++++++++++++++++++----------------------
 5 files changed, 52 insertions(+), 38 deletions(-)

diff --git a/README.md b/README.md
index cc9dbcb..9cfeab5 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,15 @@
 
 This project is servicecomb-java-chassis security support. The main architecture is based on [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) and [OpenID Connect](https://openid.net/connect/). And provides APIs for developers based on [Spring Security](https://spring.io/projects/spring-security). Please see [developers guide](docs/zh_CN/developersGuide.md) for details.
 
+## Authentication diagram
+
+![](docs/authentication.png)
+
+
+## Authorization diagram
+
+![](docs/authorization.png)
+
 ## Project description
 
 This project contains two folders api and samples. Api folder contains components used in Authentication Server, Edge Service and Resource Server. And samples folder gives a working example showing how to use these apis. 
diff --git a/README_ZH.md b/README_ZH.md
index cf893d4..55dda1a 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -2,6 +2,15 @@
 
 本项目为servicecomb-java-chassis提供认证鉴权支持。鉴权实现的主要框架参考了[The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) 和 [OpenID Connect](https://openid.net/connect/)。项目参考[Spring Security](https://spring.io/projects/spring-security)给开发者提供了接口。请参考[开发指南](docs/zh_CN/developersGuide.md)获取详细信息。
 
+## 认证流程图
+
+![](docs/authentication.png)
+
+
+## 鉴权流程图
+
+![](docs/authorization.png)
+
 ## 项目说明
 
 项目包含了api和samples两个目录。其中api目录主要提供给Authentication Server, Edge Service and Resource Server使用的api。 samples目录是基于上诉api提供的一个开发示例。
diff --git a/docs/authentication.png b/docs/authentication.png
new file mode 100644
index 0000000..be94dfc
Binary files /dev/null and b/docs/authentication.png differ
diff --git a/docs/authorization.png b/docs/authorization.png
new file mode 100644
index 0000000..91246c0
Binary files /dev/null and b/docs/authorization.png differ
diff --git a/docs/zh_CN/developersGuide.md b/docs/zh_CN/developersGuide.md
index a681c5a..8d881ee 100644
--- a/docs/zh_CN/developersGuide.md
+++ b/docs/zh_CN/developersGuide.md
@@ -25,24 +25,23 @@ grant_type=password&username=admin&password=changeMyPassword
     "id_token": "eyJ...hbGciOiJSU...zI1NiIsImtpZCI6Ij",
     "expires_in": 600,
     "scope": null,
-    "jti": null,
     "additionalInformation": null
 }
 ```
 
   * Authentication Server 发送 Token 给 Client 。
 
-  * Client 携带  Access Token 请求 Edge Service 。
+  * Client 携带  ID Token 请求 Edge Service 。
 
 ```
 ** HTTP Request **
 
 POST http://localhost:9090/api/resource-server/v1/auth/handler/adminSayHello?name=Hi HTTP/1.1
 Content-Type: application/x-www-form-urlencoded
-Authorization: Bearer SlAV32hkKG
+Authorization: Bearer eyJ...hbGciOiJSU...zI1NiIsImtpZCI6Ij
 ```
 
-  * Edge Service 将 Access Token 转换为对应的 ID Token ， 然后将请求转发给Resource Server。
+  * Edge Service 将 ID Token 转发给Resource Server。
   * Resource Server 返回对应的资源给 Client 。 
 
 ## 开发 Authentication Server
@@ -64,36 +63,28 @@ Authentication Server 主要提供认证和授权等接口。
 
 Authentication Server 需要配置 PasswordEncoder、Signer、SignerVerifier、TokenStore、UserDetailsService 等。
 ```
-@Configuration
-public class AuthenticationConfiguration {
-  @Bean(name = "authPasswordEncoder")
+  @Bean(name = Constants.BEAN_AUTH_PASSWORD_ENCODER)
   public PasswordEncoder authPasswordEncoder() {
     return new Pbkdf2PasswordEncoder();
   }
 
-  @Bean(name = {"authSigner", "authSignatureVerifier"})
+  @Bean(name = {Constants.BEAN_AUTH_SIGNER, Constants.BEAN_AUTH_SIGNATURE_VERIFIER})
   public SignerVerifier authSignerVerifier() {
     // If using RSA, need to configure authSigner and authSignatureVerifier separately. 
     // If using MacSigner, need to protect the shared key by properly encryption.
     return new MacSigner("Please change this key.");
   }
 
-  @Bean(name = {"authAccessTokenStore", "authRefreshTokenStore"})
-  public TokenStore sessionIDTokenStore() {
-    // Use in memory store for testing. Need to implement JDBC or Redis SessionIDTokenStore in product. 
-    return new InMemorySessionIDTokenStore();
-  }
-
-  @Bean(name = "authIDTokenStore")
-  public TokenStore authIDTokenStore(@Autowired @Qualifier("authSigner") Signer signer,
-      @Autowired @Qualifier("authSignatureVerifier") SignatureVerifier signerVerifier) {
-    return new JWTTokenStore(signer, signerVerifier);
+  @Bean(name = Constants.BEAN_AUTH_OPEN_ID_TOKEN_STORE)
+  public AbstractOpenIDTokenStore openIDTokenStore() {
+    // TODO: Use in memory store for testing. Need to implement JDBC or Redis SessionIDTokenStore in product. 
+    return new InMemoryOpenIDTokenStore();
   }
 
-  @Bean(name = "authUserDetailsService")
+  @Bean(name = Constants.BEAN_AUTH_USER_DETAILS_SERVICE)
   public UserDetailsService authUserDetailsService(
-      @Autowired @Qualifier("authPasswordEncoder") PasswordEncoder passwordEncoder) {
-    // Use in memory UserDetails, need to implement JDBC or others in product
+      @Autowired @Qualifier(Constants.BEAN_AUTH_PASSWORD_ENCODER) PasswordEncoder passwordEncoder) {
+    // TODO: Use in memory UserDetails, need to implement JDBC or others in product
     InMemoryUserDetailsManager manager = new InMemoryUserDetailsManager();
     UserDetails uAdmin = new User("admin", passwordEncoder.encode("changeMyPassword"),
         Arrays.asList(new SimpleGrantedAuthority("ADMIN")));
@@ -103,7 +94,6 @@ public class AuthenticationConfiguration {
     manager.createUser(uGuest);
     return manager;
   }
-}
 ```
 
 * UserDetailsService
@@ -114,8 +104,8 @@ public class AuthenticationConfiguration {
 
 生成 Token 和对 Token 进行校验。Singer 和  SignatureVerifier 是配套使用的， 在 Authentication Server ， 生成 Token 的时候，需要使用 Singer 。 验证 Token 的有效性 （比如查询 userDetails 等场景）， 需要使用  SignatureVerifier 。 通常有两种方式进行签名和校验， 一种是基于对称秘钥的机制，比如MacSigner，即是 Singer， 也是 SignatureVerifier （SignerVerifier）; 一种是基于非对称秘钥的机制， 比如 RsaSigner 和  RsaVerifier , 生成 Token 和校验 Token 的秘钥是不同的。
 
-* TokenStore
-在Authentication Server，TokenStore主要用来生成Access Token, Refresh Token和ID Token， 默认情况下， Access Token和Refresh Token都使用AbstractSessionIDTokenStore（本例子使用了InMemorySessionIDTokenStore，业务代码通常需要换为JDBC、Redis等实现）， ID Token使用JWTTokenStore。 JWTTokenStore是一个无状态的会话机制，Authentication Server的任何一个实例都可以独立生成。
+* AbstractOpenIDTokenStore
+在Authentication Server，TokenStore主要用来生成Access Token, Refresh Token和ID Token， 默认情况下， Access Token和Refresh Token都使用AbstractSessionIDTokenStore（本例子使用了InMemoryOpenIDTokenStore，业务代码通常需要换为JDBC、Redis等实现）， ID Token使用JWTTokenStore。 JWTTokenStore是一个无状态的会话机制，Authentication Server的任何一个实例都可以独立生成。支持Refresh Token认证的场景下，还需要实现通过Refresh Token读取其他信息的方法。
 
 * PasswordEncoder 
 
@@ -141,25 +131,25 @@ Resource Server 对 Client 的访问进行认证， 并进行权限控制。
 Resource Server 需要配置 Signer、SignatureVerifier、TokenStore 等， 对用户会话进行认证。 
 
 ```
-  @Bean(name = {"authSigner", "authSignatureVerifier"})
+  @Bean(name = {Constants.BEAN_AUTH_SIGNER, Constants.BEAN_AUTH_SIGNATURE_VERIFIER})
   public SignerVerifier authSignerVerifier() {
     // If using RSA, need to configure authSigner and authSignatureVerifier separately. 
     // If using MacSigner, need to protect the shared key by properly encryption.
     return new MacSigner("Please change this key.");
   }
 
-  @Bean(name = "authIDTokenStore")
-  public TokenStore authIDTokenStore(@Autowired @Qualifier("authSigner") Signer signer,
-      @Autowired @Qualifier("authSignatureVerifier") SignatureVerifier signerVerifier) {
-    return new JWTTokenStore(signer, signerVerifier);
+  @Bean(name = Constants.BEAN_AUTH_ID_TOKEN_STORE)
+  public JWTTokenStore authIDTokenStore(@Autowired @Qualifier(Constants.BEAN_AUTH_SIGNER) Signer signer, 
+      @Autowired @Qualifier(Constants.BEAN_AUTH_SIGNATURE_VERIFIER) SignerVerifier signerVerifier) {
+    return new JWTTokenStoreImpl(signer, signerVerifier);
   }
 ```
 
 * Signer、SignatureVerifier
 对Token进行校验需要，实际上Resource Server只需要使用SignatureVerifier。
 
-* TokenStore
-默认情况下， Edge Service将ID Token传递给Resource Server，所以只需要配置authIDTokenStore。
+* JWTTokenStore
+Edge Service将ID Token传递给Resource Server，所以只需要配置JWTTokenStore。基于会话认证的场景，需要提供AbstractOpenIDTokenStore。
 
 
 * 权限配置
@@ -242,14 +232,20 @@ Edge Service 是微服务接入层。 在[单体应用微服务改造](https://b
 
 * 配置
 
-Edge Service 需要配置 EdgeTokenStore 等， 对用户会话进行认证。Edge Service 从HTTP头里面读取Access Token， 然后通过 EdgeTokenStore比对是否Access Token有效，如果有效，将对应的 ID Token传递到 Resource Server。 这里使用了 InMemoryEdgeTokenStore， 产品代码会多实例部署 Edge Service， 需要将其替换为 JDBC 或者 Redis 等实现。 
+Edge Service 需要配置 JWTTokenStore 等， 对用户会话进行认证。Edge Service 从HTTP头里面读取Id Token， 然后通过 JWTTokenStore检查ID Token是否有效，如果有效，将对应的 ID Token传递到 Resource Server。 在基于会话认证的场景下，需要使用 AbstractOpenIDTokenStore。
 
 ```
-@Configuration
-public class AuthenticationConfiguration {
-  @Bean(name = "authEdgeTokenStore")
-  public EdgeTokenStore authEdgeTokenStore() {
-    return new InMemoryEdgeTokenStore();
+  @Bean(name = {Constants.BEAN_AUTH_SIGNER, Constants.BEAN_AUTH_SIGNATURE_VERIFIER})
+  public SignerVerifier authSignerVerifier() {
+    // If using RSA, need to configure authSigner and authSignatureVerifier separately. 
+    // If using MacSigner, need to protect the shared key by properly encryption.
+    return new MacSigner("Please change this key.");
   }
-}
+
+  @Bean(name = Constants.BEAN_AUTH_ID_TOKEN_STORE)
+  public JWTTokenStore authIDTokenStore(@Autowired @Qualifier(Constants.BEAN_AUTH_SIGNER) Signer signer, 
+      @Autowired @Qualifier(Constants.BEAN_AUTH_SIGNATURE_VERIFIER) SignerVerifier signerVerifier) {
+    return new JWTTokenStoreImpl(signer, signerVerifier);
+  }
+
 ```