¶ Project
In order to use the Netless interactive whiteboard service, you can create a project in Management Console. After logging in to the management console, select Project Management on the left sidebar, and you can see all projects on the right. You can create new projects on this page or modify the configuration of existing projects.
You can create multiple projects, and the permissions of these projects are isolated from each other.
You can create a production mode project and a development mode project. Let the development only get the permission of the development mode project, and let the operation and maintenance get the permission of the production mode project. In this way, the development environment and the production environment are isolated from each other.
Click "Configuration" on the right side of the item, and it will jump to another page. This page can view the basic information (or modify) of the project. The key information is as follows.
- AppIdentifier: project identifier
- AK: access key is used for authentication
- SK: secret access key is used for authentication
At the bottom of the configuration page, you can "disable the project" (set the project status to disabled). This operation can disable all resources belonging to the project. This operation can be undone, and you can restart the disabled item.
"Disabled Project" will disable all whiteboard rooms, whiteboard recordings, and PPT conversion tasks under the project. If the project corresponds to the production environment, this operation may cause extremely serious consequences, that is, some of your online services may be interrupted. Please confirm that you have understood the consequences of "prohibited items" before performing this operation.
¶ AppIdentifier
Each item has its own AppIdentifier as an identifier. Select Project Management on the left sidebar of Management Console, In the project list, you can find the AppIdentifier of your project.
When using the SDK on the client side (Web, iOS, Android), the project AppIdentifier needs to be passed in as a startup parameter.
JavaScript
new WhiteWebSdk({
appIdentifier: "AppIdentifier copied from the management console",
...,
});
Objective-C-iOS
WhiteSdkConfiguration *config = [[WhiteSdkConfiguration alloc] initWithApp:@"AppIdentifier copied from the management console"];
Java-Android
WhiteSdkConfiguration sdkConfiguration = new WhiteSdkConfiguration("AppIdentifier copied from the management console", true);
¶ Access key
You can view or create an access key in the project configuration page. The access key is composed of a pair of AK and SK, by which you can check out the token.
Almost all activities of the Netless interactive whiteboard involve the use of Token authentication. Our cloud service uses the token you checked out to confirm that the person who initiated the operation has obtained your authorization.
Token has the authority to access the key pair. You can delete or disable the access key pair, which will invalidate all tokens checked out by the access key pair. You can also ban the project itself, and this operation can also invalidate all tokens under the project.
There are two dimensions to understand a specific Token. First, determine what type of Token is? Token can be sdkToken, roomToken, taskToken. Different APIs of Netless interactive whiteboard require different types of tokens, which should be generated as needed before calling. Second, determine what fields the Token contains. Filling in the fields with different values will affect the behavior of the token. Different Token types will contain their unique fields.
No matter which type of Token, it contains the following public fields.
| Field name | Value type | Description |
|---|---|---|
role |
Enumerate reader, writer, admin | Roles corresponding to permissions |
expireAt |
Positive integer time (milliseconds) | Expiration time point, unix timestamp (milliseconds) |
Among them, expireAt is an optional field. If the Token does not contain this field, it means that the Token will never expire. You can set the parameter lifespan to 0 when constructing the token to check out the token that never expires.
Tokens that never expire may bring security risks to your business. Imagine that if someone acquires a highly authorized token, he can use the token to harm your system, and the only way you can invalidate the token is to disable the access key pair of the token—this is a side effect Great operation.
Don't check out tokens that never expire unless you have to. On the business server, you can check out a short-lived temporary token only when needed, and release it immediately after use. For Tokens that must be issued to the client, you can estimate the maximum period for the client to use the Token according to the business scenario, and set this maximum period as the lifetime of the Token. Don't store the Token in the database or write it into a file. Whenever there is a need, use the access key pair to check out directly instead of reading from the database or file.
roomToken
roomToken is bound to a specific whiteboard room. You can check out the roomToken of role=admin to manage the room (such as kicking room members, banning the room, deleting the room, etc.). You can also check out the roomToken of role=writer or role=reader and place it to the client (or front end) so that they can join the room with a specific identity.
The roomTokens of different rooms do not communicate with each other. Please refer to other API documents for specific usage. roomToken contains its own unique fields.
| Field name | Value type | Description |
|---|---|---|
uuid |
String | UUID of the room |
taskToken
taskToken is bound to a specific conversion task. You can use it to view the progress of the conversion task, or to cancel the conversion task. The taskTokens of different transformation tasks do not communicate with each other. Please refer to other API documents for specific usage. taskToken contains its own unique fields.
| Field name | Value type | Description |
|---|---|---|
uuid |
String | UUID of the task |
sdkToken
The level of sdkToken is above the Token introduced earlier. It can directly replace other tokens. When calling Netless's API on the business server, you can directly use sdkToken to perform any operations without worrying about being blocked due to permissions.
Don't leak the sdkToken to the client (or front-end), and don't store the sdkToken in the database or write the configuration file. It should be checked out temporarily while in use, and the expiration time should be set as short as possible. The permission level of sdkToken is very high, and the leakage will endanger business security.
You can also click the "Generate sdkToken" button directly on the project configuration page of the management console. This will generate a permanently valid sdkToken with role=admin.
¶ Check out Token
You can check out any token you want with the access key pair (ie AK and SK).
For security reasons, only the server can get AK, SK, can only check out the token on the server. Never send AK, SK to the client or front end, and don't write them in the code. At least, you have to let the business server App read AK and SK from the configuration file.
The access key pair is an important asset of your team. If a malicious person gets the access key pair for your online business, he can seriously harm your online business. In order to stop the infringement of malicious people, you can only disable the access key pair, which will inevitably lead to the prohibition of other online businesses that are normally running.
Therefore, in order to avoid falling into this dilemma, you should avoid unreliable people from obtaining access key pairs for the production environment.
You can check out the token on the server in the following two ways.
- According to the language of your business server, select the code snippet of the corresponding language in the open source project netless-token, and copy the snippet to your project , And call the method in the code snippet when the token needs to be checked out.
- Directly call Netless server API to generate Token. For details, please refer to 《Generate Token》.