doc: update doc for auth service (#135)

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.5.7 (March 15, 2022)
+
+- doc: update doc for auth service
+
 ## 0.5.6 (February 18, 2022)
 
 - add download resource chapter

blocklet.yml

@@ -1,5 +1,5 @@
 name: '@arcblock/abtnode-docs'
-version: 0.5.6
+version: 0.5.7
 description: >-
   Blocklet Server Documentation, a help documentation for quickly get started
   with Blocklet Server.
@@ -25,7 +25,7 @@ title: Blocklet Server Docs
 community: 'https://gitter.im/ArcBlock/community'
 documentation: 'https://docs.arcblock.io'
 support: [email protected]
-specVersion: 1.2.1
+specVersion: 1.2.3
 did: z8ia5NLSuFwhPimBJHRdPmp6yx9fG8rcFex4b
 timeout:
   start: 10
@@ -54,3 +54,4 @@ payment:
 children: []
 capabilities:
   clusterMode: false
+  component: true

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcblock/abtnode-docs",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Blocklet Server Documentation, a help documentation for quickly get started with Blocklet Server.",
   "main": "index.js",
   "publishConfig": {

src/developer/auth-service/index.md

@@ -1,5 +1,5 @@
 ---
-title: 'Configure Auth Service'
+title: 'Auth Service'
 description: 'Auth Service Instructions'
 keywords: 'blocklet server, blocklet, service, auth'
 author: 'linchen'
@@ -12,23 +12,23 @@ tags:
   - 'auth'
 ---
 
-Auth Service is a general Auth service provided by Blocklet Server for Blocklet.
+Blocklet Server provides generic auth service for Blocklets.
 
-Blocklet can be declaratively enabled and configured Auth Service in `blocklet.yml`.
-
-Auth Service includes the following main capabilities:
-- Set accessible after login
-- Set accessible after authorization
-- Set invitation login or open login
+Auth service provides the following capabilities
+- Get user identity
+- Get user permissions
+- Intercept unlogged requests (do not intercept by default)
+- Intercept unauthorised requests (do not intercept by default)
+- Set invite login and open login (default is open login)
 
 ## Getting Started
-[static-demo-blocklet](https://github.com/blocklet/html-2048-sample) is an html5 game that can be run on Blocklet Server. The following will introduce how to make a static-demo-blocklet with Auth capability (login protection)
+[static-demo-blocklet](https://github.com/blocklet/html-2048-sample) is an html5 game that can be run on Blocklet Server. The following will introduce how to make a static-demo-blocklet that is only accessible after login.
 
-0. Prerequisites: Install and run Blocklet Server v1.2.0 or higher locally
+0. Prerequisites: Install and run Blocklet Server v1.7.0 or higher locally
 
 1. Download the project source code [html-2048-sample](https://github.com/blocklet/html-2048-sample)
 
-2. Open `blocklet.yml` in the project root directory, find the interface whose name is publicUrl, and add the Auth Service configuration
+2. Open `blocklet.yml` in the project root directory, find the interface whose name is publicUrl, and add the Auth configuration
 
 ``` yml
 interfaces:
@@ -39,7 +39,9 @@ interfaces:
     port: BLOCKLET_PORT
     protocol: tcp
 +   services:
-+     - name: '@abtnode/auth-service'
++     - name: 'auth'
++       config:
++         blockUnauthenticated: true
 ```
 
 3. Execute `blocklet bundle` in the project root directory. After successful execution, you will see the successfully created blocklet bundle in `.blocklet/bundle`.
@@ -50,7 +52,7 @@ linchen@LinkdeMacBook-Pro html-2048-sample % blocklet bundle
 ℹ Bundling in zip mode for blocklet static-demo-blocklet...
 
 ✔ Creating blocklet bundle in .blocklet/bundle... Done in 0.018s
-✔ Blocklet [email protected].7 is successfully bundled!
+✔ Blocklet [email protected].21 is successfully bundled!
 ```
 
 4. Execute `blocklet deploy .blocklet/bundle` in the project root directory to publish the blocklet bundle to the locally running Blocklet Server.
@@ -60,7 +62,7 @@ linchen@LinkdeMacBook-Pro html-2048-sample % blocklet deploy .blocklet/bundle
 ℹ Try to deploy blocklet from /Users/linchen/code/blocklet/html-2048-sample/.blocklet/bundle to Local Blocklet Server
 ℹ Node did from config zNKqGAvUzcCowxtNA5r5gKQYUm2hR4X2SE2o
 ℹ Load config from /Users/linchen/code/arcblock/andata/.abtnode/abtnode.yml
-✔ Blocklet [email protected].7 was successfully deployed!
+✔ Blocklet [email protected].21 was successfully deployed!
 ```
 
 5. Start Static Demo in Blocklet Server dashboard
@@ -81,21 +83,9 @@ Congratulations!
 
 [https://github.com/blocklet/auth-demo](https://github.com/blocklet/auth-demo): Implement login, logout, display user information, authentication and authorization functions based on Auth Service
 
-## Enable Auth Service
-Enable Auth Service by configuring in `blocklet.yml`, under the interface that needs to start Auth Service
-
-```yml
-interfaces:
-  - type: web
-    name: xxxx
-    # ... other interface config
-    services:
-      - name: '@abtnode/auth-service'
-      - config:
-        # ...
-```
+## Configure the Auth service
+All blocklets are installed with Auth capabilities. You can also configure the Auth service in `blocklet.yml`
 
-## Configuration
 e.g.
 
 ```yml
@@ -104,7 +94,7 @@ interfaces:
     name: publicUrl
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
           invitedUserOnly: no
           profileFields:
@@ -114,7 +104,7 @@ interfaces:
           webWalletUrl: https://web.abtwallet.io
           ignoreUrls:
             - /public/**
-          blockUnauthenticated: true
+          blockUnauthenticated: false
           blockUnauthorized: false
 ```
 
@@ -132,19 +122,17 @@ interfaces:
   - default: https://web.abtwallet.io
 
 ## Set accessible after login
-After Auth Service is enabled, Auth Service will automatically intercept requests that are not logged in and jump to the Auth Service login page.
-
-If Blocklet wants to handle unlogged requests by itself, it can be configured as follows:
+After setting the login access, the Auth service will automatically intercept requests that are not logged in, and jump to the login page
 
 ```yml
 interfaces:
   - type: web
     name: xxxx
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
-          blockUnauthenticated: false
+          blockUnauthenticated: true
 ```
 
 ## Set accessible after authorization
@@ -159,7 +147,7 @@ interfaces:
     name: xxxx
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
           blockUnauthorized: true
 ```
@@ -178,12 +166,11 @@ interfaces:
     name: xxxx
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
           invitedUserOnly: yes
 ```
 
 - invitedUserOnly
   - no: Open login (default)
-  - yes: Only log in via invitation link
-  - not-first: Only the first login user does not need to go through the invitation link
+  - yes: Only log in via invitation link

src/developer/auth-service/index.zh.md

@@ -1,6 +1,6 @@
 ---
-title: '配置 Auth Service'
-description: 'Auth Service 使用说明'
+title: 'Auth 服务'
+description: 'Auth 服务使用说明'
 keywords: 'blocklet server, blocklet, service, auth'
 author: 'linchen'
 category: ''
@@ -12,23 +12,23 @@ tags:
   - 'auth'
 ---
 
-Auth Service 是 Blocklet Server 为 Blocklet 提供的通用 Auth 服务。
+Blocklet Server 为 Blocklet 提供了通用 Auth 服务。
 
-Blocklet 可以通过在 `blocklet.yml` 中以声明的方式启用和配置 Auth Service.
-
-Auth Service 包含以下主要能力：
-- 设置登录可访问
-- 设置授权可访问
-- 设置邀请登录和开放登录
+Auth 服务提供以下能力
+- 获取用户身份
+- 获取用户权限
+- 拦截未登录的请求（默认不拦截）
+- 拦截无权限的请求（默认不拦截）
+- 设置邀请登录和开放登录（默认为开放登录）
 
 ## 入门
-[static-demo-blocklet](https://github.com/blocklet/html-2048-sample) 是一个可以运行在 Blocklet Server 上的 html5 游戏。下面将介绍如何制作一个拥有 Auth 能力（登录后可访问）的 static-demo-blocklet.
+[static-demo-blocklet](https://github.com/blocklet/html-2048-sample) 是一个可以运行在 Blocklet Server 上的 html5 游戏。下面将介绍如何制作一个只允许登录后可访问的 static-demo-blocklet.
 
-0. 前置条件: 本地安装并且运行 v1.2.0 以上版本的 Blocklet Server
+0. 前置条件: 本地安装并且运行 v1.7.0 以上版本的 Blocklet Server
 
 1. 下载项目源代码 [html-2048-sample](https://github.com/blocklet/html-2048-sample)
 
-2. 打开项目根目录下 `blocklet.yml`, 找到 name 为 publicUrl 的 interface, 并添加 Auth Service 配置
+2. 打开项目根目录下 `blocklet.yml`, 找到 name 为 publicUrl 的 interface, 并添加 Auth 配置
 
 ``` yml
 interfaces:
@@ -39,7 +39,9 @@ interfaces:
     port: BLOCKLET_PORT
     protocol: tcp
 +   services:
-+     - name: '@abtnode/auth-service'
++     - name: 'auth'
++       config:
++         blockUnauthenticated: true
 ```
 
 3. 在项目根目录下执行 `blocklet bundle`. 执行成功后, 在 `.blocklet/bundle` 中会看到被成功创建的 blocklet bundle.
@@ -50,7 +52,7 @@ linchen@LinkdeMacBook-Pro html-2048-sample % blocklet bundle
 ℹ Bundling in zip mode for blocklet static-demo-blocklet...
 
 ✔ Creating blocklet bundle in .blocklet/bundle... Done in 0.018s
-✔ Blocklet [email protected].7 is successfully bundled!
+✔ Blocklet [email protected].21 is successfully bundled!
 ```
 
 4. 在项目根目录下执行 `blocklet deploy .blocklet/bundle`, 将 blocklet bundle 发布到本地运行的 Blocklet Server.
@@ -60,7 +62,7 @@ linchen@LinkdeMacBook-Pro html-2048-sample % blocklet deploy .blocklet/bundle
 ℹ Try to deploy blocklet from /Users/linchen/code/blocklet/html-2048-sample/.blocklet/bundle to Local Blocklet Server
 ℹ Node did from config zNKqGAvUzcCowxtNA5r5gKQYUm2hR4X2SE2o
 ℹ Load config from /Users/linchen/code/arcblock/andata/.abtnode/abtnode.yml
-✔ Blocklet [email protected].7 was successfully deployed!
+✔ Blocklet [email protected].21 was successfully deployed!
 ```
 
 5. 在 Blocklet Server dashboard 启动 Static Demo
@@ -79,23 +81,11 @@ linchen@LinkdeMacBook-Pro html-2048-sample % blocklet deploy .blocklet/bundle
 
 ## Demo
 
-[https://github.com/blocklet/auth-demo](https://github.com/blocklet/auth-demo): 基于 Auth Service 实现了登录，登出，显示用户信息，认证，授权功能
+[https://github.com/blocklet/auth-demo](https://github.com/blocklet/auth-demo): 使用 Auth 服务实现了登录，登出，显示用户信息，认证，授权功能
 
-## 启用 Auth Service
-在 `blocklet.yml` 中，在需要启动 Auth Service 的 interface 下，配置并启用 Auth Service
+## 配置 Auth 服务
+所有 blocklet 安装后即具备了 Auth 能力. 你也可以在 `blocklet.yml` 中配置 Auth 服务
 
-```yml
-interfaces:
-  - type: web
-    name: xxxx
-    # ... other interface config
-    services:
-      - name: '@abtnode/auth-service'
-        config:
-        # ...
-```
-
-## 配置
 e.g.
 
 ```yml
@@ -104,7 +94,7 @@ interfaces:
     name: publicUrl
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
           invitedUserOnly: no
           profileFields:
@@ -114,52 +104,48 @@ interfaces:
           webWalletUrl: https://web.abtwallet.io
           ignoreUrls:
             - /path/to/**
-          blockUnauthenticated: true
+          blockUnauthenticated: false
           blockUnauthorized: false
 ```
 
 - invitedUserOnly: 是否只能通过邀请链接登录
   - default: no
 - profileFields: 登录时需要提供的身份信息
   - default: [fullName, email, avatar]
-- blockUnauthenticated: Auth Service 是否自动拦截未登录的请求, 并跳转到登录页
-  - default: true
-- blockUnauthorized: Auth Service 是否自动拦截未授权的请求
+- blockUnauthenticated: Auth 服务是否自动拦截未登录的请求, 并跳转到登录页
+  - default: false
+- blockUnauthorized: Auth 服务是否自动拦截未授权的请求
   - default: false
-- ignoreUrls: Auth Service 不会拦截哪些 url
+- ignoreUrls: Auth 服务不会拦截哪些 url
   - default: none
-- webWalletUrl: 通过 Auth Service 登录时的 Web Wallet 地址
+- webWalletUrl: 通过 Auth 服务登录时的 Web Wallet 地址
   - default: https://web.abtwallet.io
 
 ## 设置登录可访问
-启用 Auth Service 后，Auth Service 会自动拦截未登录的请求, 并跳转到 Auth Service 登录页.
-
-如果 Blocklet 希望自己处理未登录的请求, 可以做如下配置:
+设置登录可访问后，Auth 服务会自动拦截未登录的请求, 并跳转到登录页
 
 ```yml
 interfaces:
   - type: web
     name: xxxx
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
-          blockUnauthenticated: false
+          blockUnauthenticated: true
 ```
 
 ## 设置授权可访问
 
-启用 Auth Service 后，Auth Service **不会** 自动拦截未授权的请求. Blocklet 需要自己处理.
-
-如果 Blocklet 希望 Auth Service 自动拦截未授权的请求, 可以做如下配置:
+After setting authorized access, Auth Service automatically intercepts unauthorized requests
 
 ```yml
 interfaces:
   - type: web
     name: xxxx
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
           blockUnauthorized: true
 ```
@@ -178,12 +164,11 @@ interfaces:
     name: xxxx
     # ... other interface config
     services:
-      - name: '@abtnode/auth-service'
+      - name: 'auth'
         config:
           invitedUserOnly: yes
 ```
 
 - invitedUserOnly
   - no: 开放登录 (默认)
-  - yes: 只能通过邀请链接登录
-  - not-first: 只有第一个登录用户不需要通过邀请链接
+  - yes: 只能通过邀请链接登录

src/developer/index.md

@@ -19,7 +19,7 @@ If you are a developer and want to do something with Blocklet Server ,this chapt
 - [Create DApp Blocklets](./dapp-blocklets)
 - [Blocklet Specification](./blocklet-spec)
 - [Blocklet SDK](./blocklet-sdk)
-- [Configure Auth Service](./auth-service)
+- [Auth Service](./auth-service)
 - [Send notification to DID Wallet](./send-notification)
 - [Use DID Connect](./did-connect)
 - [Composable blocklet](./composable-blocklet)