[alibaba#138] Could you please provide complete and systematic Author…

…ization document? (alibaba#139)
realJackSun · Dec 1, 2020 · b2a1ea3 · b2a1ea3
1 parent 1db5343
commit b2a1ea3
Show file tree

Hide file tree

Showing 5 changed files with 252 additions and 63 deletions.
diff --git a/docs/en-us/auth.md b/docs/en-us/auth.md
@@ -0,0 +1,119 @@
+---
+title: Authentication
+keywords: Authentication
+description: Authentication
+---
+
+# Authentication
+
+### Use Authentication in Servers
+
+### Without Docker
+By default, no login is required to start following the official document configuration, which can expose the configuration center directly to the outside world. However, if the authentication is enabled, one can use nacos only after he configures the user name and password.
+
+Before enabling authentication, the configuration in application.properties is as follow:
+```java
+### If turn on auth system:
+nacos.core.auth.enabled=false
+```
+
+After enabling authentication, the configuration in application.properties is as follow:
+```java
+### If turn on auth system:
+nacos.core.auth.enabled=true
+```
+
+
+### With Docker
+
+#### Official images
+
+If you choose to use official images, please add the following environment parameter when you start a docker container.
+
+```powershell
+NACOS_AUTH_ENABLE=true
+```
+
+For example, you can run this command to run a docker container with Authentication:
+
+```powershell
+docker run --env PREFER_HOST_MODE=hostname --env MODE=standalone --env NACOS_AUTH_ENABLE=true -p 8848:8848 nacos/nacos-server
+```
+
+Besides, you can also add the other related enviroment parameters:
+
+| name                          | description                            | option                                 |
+| ----------------------------- | -------------------------------------- | -------------------------------------- |
+| NACOS_AUTH_ENABLE      |  If turn on auth system        | default :false                          |
+| NACOS_AUTH_TOKEN_EXPIRE_SECONDS      |  The token expiration in seconds        | default :18000                          |
+| NACOS_AUTH_TOKEN      |  The default token        | default :SecretKey012345678901234567890123456789012345678901234567890123456789                          |
+| NACOS_AUTH_CACHE_ENABLE      |  Turn on/off caching of auth information. By turning on this switch, the update of auth information would have a 15 seconds delay.        | default : false   |
+
+
+
+#### Custom images
+
+If you choose to use custom images, please modify the application.properties before you start nacos, change this line 
+
+```
+nacos.core.auth.enabled=false
+```
+into
+```
+nacos.core.auth.enabled=true
+```
+
+## Authentication in Clients
+
+### Authentication in Java SDK
+
+The user name and password should be set when creating a 'Properties' class.
+```java
+properties.put("username","${username}");
+properties.put("password","${password}");
+```
+#### Example Code
+```java
+try {
+    // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code.
+	String serverAddr = "{serverAddr}";
+	Properties properties = new Properties();
+	properties.put("serverAddr", serverAddr);
+
+    // if need username and password to login
+        properties.put("username","nacos");
+        properties.put("password","nacos");
+
+	ConfigService configService = NacosFactory.createConfigService(properties);
+} catch (NacosException e) {
+    // TODO Auto-generated catch block
+    e.printStackTrace();
+}
+```
+### Authentication in Other languages SDK
+
+Pending...
+
+### Authentication in Open-API
+Firstly, the user name and password should be provided to login.
+
+```plain
+curl -X POST '127.0.0.1:8848/nacos/v1/auth/login' -d 'username=nacos&password=nacos'
+```
+
+If the user name and password are correct, the response will be:
+
+```
+{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyOTE2Nn0.2TogGhhr11_vLEjqKko1HJHUJEmsPuCxkur-CfNojDo","tokenTtl":18000,"globalAdmin":true}
+```
+
+Secondly, when using configuration services or naming services, accessToken in the previous response should be provided. To use the accessToken, 'accessToken=${accessToken}' should be appended at the end of request url, e.g.,
+
+```plain
+curl -X GET '127.0.0.1:8848/nacos/v1/cs/configs?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&dataId=nacos.example.1&group=nacos_group'
+```
+
+```plain
+curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1'
+```
+
diff --git a/docs/en-us/sdk.md b/docs/en-us/sdk.md
@@ -637,34 +637,3 @@ void
 NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
 naming.unsubscribe("nacos.test.3", event -> {});
 ```
-
-### Use Authentication Configuration
-#### Description
-By default, no login is required to start following the official document configuration, which can expose the configuration center directly to the outside world.
-```java
-### If turn on auth system:
-nacos.core.auth.enabled=false
-```
-Therefore, to enable authentication, use nacos by configuring the user name and password.
-```java
-### If turn on auth system:
-nacos.core.auth.enabled=true
-```
-#### Example Code
-```java
-try {
-    // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code.
-	String serverAddr = "{serverAddr}";
-	Properties properties = new Properties();
-	properties.put("serverAddr", serverAddr);
-
-    // if need username and password to login
-        properties.put("username","nacos");
-        properties.put("password","nacos");
-
-	ConfigService configService = NacosFactory.createConfigService(properties);
-} catch (NacosException e) {
-    // TODO Auto-generated catch block
-    e.printStackTrace();
-}
-```
diff --git a/docs/zh-cn/auth.md b/docs/zh-cn/auth.md
@@ -0,0 +1,125 @@
+---
+title: Authorization
+keywords: Authorization
+description: Authorization
+---
+
+# 鉴权
+
+## 服务端如何开启鉴权
+
+### 非Docker环境
+
+按照官方文档配置启动,默认是不需要登录的，这样会导致配置中心对外直接暴露。而启用鉴权之后，需要在使用用户名和密码登录之后，才能正常使用nacos。
+
+开启鉴权之前，application.properties中的配置信息为：
+```java
+### If turn on auth system:
+nacos.core.auth.enabled=false
+```
+开启鉴权之后，application.properties中的配置信息为：
+```java
+### If turn on auth system:
+nacos.core.auth.enabled=true
+```
+
+
+### Docker环境
+
+#### 官方镜像
+
+如果使用官方镜像，请在启动docker容器时，添加如下环境变量
+
+```powershell
+NACOS_AUTH_ENABLE=true
+```
+
+例如，可以通过如下命令运行开启了鉴权的容器:
+
+```powershell
+docker run --env PREFER_HOST_MODE=hostname --env MODE=standalone --env NACOS_AUTH_ENABLE=true -p 8848:8848 nacos/nacos-server
+```
+
+除此之外，还可以添加其他鉴权相关的环境变量信息：
+
+| name                          | description                            | option                                 |
+| ----------------------------- | -------------------------------------- | -------------------------------------- |
+| NACOS_AUTH_ENABLE      |  是否开启权限系统        | 默认:false|
+| NACOS_AUTH_TOKEN_EXPIRE_SECONDS      |  token 失效时间 | 默认:18000                          |
+| NACOS_AUTH_TOKEN      |  token        | 默认:SecretKey012345678901234567890123456789012345678901234567890123456789      |
+| NACOS_AUTH_CACHE_ENABLE      |  权限缓存开关 ,开启后权限缓存的更新默认有15秒的延迟       | 默认 : false   |
+
+
+然后运行docker-compose构建命令,例如
+```powershell
+docker-compose -f example/standalone-derby.yaml up
+```
+
+#### 自定义镜像
+
+如果选择自定义镜像，请在构建镜像之前，修改nacos工程中的application.properties文件，
+
+将下面这一行配置信息
+```
+nacos.core.auth.enabled=false
+```
+修改为
+```
+nacos.core.auth.enabled=true
+```
+然后再配置nacos启动命令。
+
+## 客户端如何进行鉴权
+
+### Java SDK鉴权
+
+在构建“Properties”类时,需传入用户名和密码。
+```java
+properties.put("username","${username}");
+properties.put("password","${password}");
+```
+#### 示例代码
+```java
+try {
+    // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code.
+	String serverAddr = "{serverAddr}";
+	Properties properties = new Properties();
+	properties.put("serverAddr", serverAddr);
+
+    // if need username and password to login
+        properties.put("username","nacos");
+        properties.put("password","nacos");
+
+	ConfigService configService = NacosFactory.createConfigService(properties);
+} catch (NacosException e) {
+    // TODO Auto-generated catch block
+    e.printStackTrace();
+}
+```
+### 其他语言的SDK鉴权
+
+待补充
+
+### Open-API鉴权
+首先需要使用用户名和密码登陆nacos。
+
+```plain
+curl -X POST '127.0.0.1:8848/nacos/v1/auth/login' -d 'username=nacos&password=nacos'
+```
+
+若用户名和密码正确,返回信息如下:
+
+```
+{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyOTE2Nn0.2TogGhhr11_vLEjqKko1HJHUJEmsPuCxkur-CfNojDo","tokenTtl":18000,"globalAdmin":true}
+```
+
+接下来进行配置信息或服务信息时,应当使用该accessToken鉴权,在url后添加参数accessToken=${accessToken},其中${accessToken}为登录时返回的token信息，例如
+
+```plain
+curl -X GET '127.0.0.1:8848/nacos/v1/cs/configs?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&dataId=nacos.example.1&group=nacos_group'
+```
+
+```plain
+curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1'
+```
+
diff --git a/docs/zh-cn/sdk.md b/docs/zh-cn/sdk.md
@@ -532,35 +532,3 @@ NamingService naming = NamingFactory.createNamingService(System.getProperty("ser
 naming.unsubscribe("nacos.test.3", event -> {});
 
 ```
-
-### 使用验证配置
-
-#### 描述
-按照官方文档配置启动,默认是不需要登录的，这样会导致配置中心对外直接暴露。
-```java
-### If turn on auth system:
-nacos.core.auth.enabled=false
-```
-因此要启用鉴权，通过配置用户名和密码的方式来使用nacos
-```java
-### If turn on auth system:
-nacos.core.auth.enabled=true
-```
-#### 示例代码
-```java
-try {
-    // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code.
-	String serverAddr = "{serverAddr}";
-	Properties properties = new Properties();
-	properties.put("serverAddr", serverAddr);
-
-    // if need username and password to login
-        properties.put("username","nacos");
-        properties.put("password","nacos");
-
-	ConfigService configService = NacosFactory.createConfigService(properties);
-} catch (NacosException e) {
-    // TODO Auto-generated catch block
-    e.printStackTrace();
-}
-```
diff --git a/site_config/docs.js b/site_config/docs.js
@@ -88,6 +88,10 @@ export default {
                 title: 'Nacos System Configurations',
                 link: '/en-us/docs/system-configurations.html',
               },
+              {
+                title: 'Authentication',
+                link: '/en-us/docs/auth.html',
+              },
               {
                 title: 'FAQ',
                 link: '/en-us/docs/faq.html',
@@ -260,6 +264,10 @@ export default {
                 title: 'Nacos系统参数介绍',
                 link: '/zh-cn/docs/system-configurations.html',
               },
+              {
+                title: '权限认证',
+                link: '/zh-cn/docs/auth.html',
+              },
               {
                 title: 'FAQ',
                 link: '/zh-cn/docs/faq.html',