Skip to content

Commit

Permalink
[alibaba#138] Could you please provide complete and systematic Author…
Browse files Browse the repository at this point in the history
…ization document? (alibaba#139)
  • Loading branch information
realJackSun authored Dec 1, 2020
1 parent 1db5343 commit b2a1ea3
Show file tree
Hide file tree
Showing 5 changed files with 252 additions and 63 deletions.
119 changes: 119 additions & 0 deletions docs/en-us/auth.md
Original file line number Diff line number Diff line change
@@ -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'
```

31 changes: 0 additions & 31 deletions docs/en-us/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
```
125 changes: 125 additions & 0 deletions docs/zh-cn/auth.md
Original file line number Diff line number Diff line change
@@ -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'
```

32 changes: 0 additions & 32 deletions docs/zh-cn/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
```
8 changes: 8 additions & 0 deletions site_config/docs.js
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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',
Expand Down

0 comments on commit b2a1ea3

Please sign in to comment.