Authentication
Overview
To avoid unauthorized service access or operations, ZEGOCLOUD uses digital Tokens to control and validate users' login privileges.
The validation process
Before you log in to a room, your app clients request Tokens from your app server and provide the Token for privilege validation when logging in to a room.
The following diagram shows the process of room login privilege validation:
Generate a Token
For business security, you must generate Tokens on your app server.
-
Go to ZEGOCLOUD Admin Console, and do the following:
- Create a project, get the AppID and AppSign.
- Subscribe to the In-app Chat service.
-
Use the token generator plug-in provided by ZEGOCLOUD to generate Tokens on your app server.
Take Go language as an example, you can do the following steps to generate a Token:
- go get github.com/ZEGOCLOUD/zego_server_assistant
- import "github.com/ZEGOCLOUD/zego_server_assistant/token/go/src/token04"
- Call the
GenerateToken04 method to generate a Token.
The following code shows how to generate a user identity Token:
| Language | Supported version | Core function | Code base | Sample code |
|---|
| User identity Token | User privilege Token |
|---|
| Go | Go 1.14.15 or later | GenerateToken04 | | | |
| C++ | C++ 11 or later | GenerateToken04 | | |
| Java | Java 1.8 or later | generateToken04 | | | |
| Python | Python 3.6.8 or later | generate_token04 | | | |
| PHP | PHP 7.0 or later | generateToken04 | | | |
| .NET | .NET Framework 3.5 or later | GenerateToken04 | | |
| Node.js | Node.js 8 or later | generateToken04 | | | |
var appId uint32 = <Your AppId> // type: uint32
userId := <Your userID> // type: string
secret := <ServerSecret> // type: 32 byte length string
var effectiveTimeInSeconds int64 = <Your token effectiveTime> //type: int64; unit: s
token, err := zsa.GenerateToken04(appId, userId, secret, effectiveTimeInSeconds)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(token)
1
Use the Token
When logging in to a room, you need to pass the Token for validation. Otherwise, the login will fail.
ZIMUserInfo userInfo = new ZIMUserInfo();
userInfo.userID = "YOUR_USER_ID";
userInfo.userName = "YOUR_USER_NAME";
String token = "xxxxxxxxxx"; // The token you get from your app server.
zim.login(userInfo, token, new ZIMLoggedInCallback() {
@Override
public void onLoggedIn(ZIMError error) {
// You can tell by the ZIMErrorCode whether the room login is successful.
......
}
});
1
try{
ZIMLoginConfig loginConfig = ZIMLoginConfig();
// The user's nickname, leave it blank if you don't want to modify the nickname
loginConfig.userName = 'userName';
// If using token as the authentication method, please fill in this parameter, otherwise no need to fill in
loginConfig.token = '';
// Whether this login is an offline login, please refer to the offline login documentation for details
loginConfig.isOfflineLogin = false;
await ZIM.getInstance()?.login('zego', loginConfig);
// Login successful, write the business logic for successful login
} on PlatformException catch(onError){
// Login failed
// Error code for login failure, please refer to the error code table in the integration documentation for handling
onError.code;
// Error message for login failure
onError.message;
}
1
ZIMUserInfo *userInfo = [[ZIMUserInfo alloc] init];
userInfo.userID = @"YOUR_USER_ID";
userInfo.userName = @"YOUR_USER_NAME";
NSString *token = @"xxxxxxxx"; // Obtain the token from the server.
[zim loginWithUserInfo:userInfo token:token callback:^(ZIMError * _Nonnull errorInfo) {
// Check whether the login is successful based on the `ZIMErrorCode`.
}];
1
ZIMUserInfo *userInfo = [[ZIMUserInfo alloc] init];
userInfo.userID = @"YOUR_USER_ID";
userInfo.userName = @"YOUR_USER_NAME";
NSString *token = @"xxxxxxxx"; // Obtain the token from the server.
[zim loginWithUserInfo:userInfo token:token callback:^(ZIMError * _Nonnull errorInfo) {
// Check whether the login is successful based on the `ZIMErrorCode`.
}];
1
ZIMUserInfo userInfo = new ZIMUserInfo();
userInfo.userID = "userID";
userInfo.userName = "userName";
string token = "xxxxxxx"; // The Token you get from your app server.
zim.Login(userInfo, token, (ZIMError errorInfo) =>
{
if(errorInfo.code == ZIMErrorCode.Success)
{
// Login successful.
}
else
{
// Login failed.
}
});
1
ZIMUserInfo userInfo;
userInfo.userID = 'YOUR_USER_ID';
userInfo.userName = 'YOUR_USER_NAME';
std::string token = 'xxxxxxxxxx'; // The Token you get from your app server.
zim->login(userInfo, token, [=](zim::ZIMError errorInfo) {
// You can tell by the ZIMError errorInfo whether the room login is successful.
......
});
1
Renew the Token
In the 30 seconds before a Token expires, the SDK sends out a notification through the tokenWillExpire callback.
(If the period of validity of the Token is less than 30 seconds after a successful room login, the callback triggers immediately. )
Upon receiving this callback, you need to get a new Token from your app server first, and then pass the new Token to the renewToken method.
When the token expires and is not updated, the user will be disconnected and receive the connectionStateChanged callback, where the event is ZIMConnectionEventTokenExpired and the state is ZIMConnectionStateDisconnected.
@Override
public void onTokenWillExpire(int second){
String token = getToken(); // Request a new Token from app server.
engine.renewToken(token, new ZIMTokenRenewedCallback {
@Override
public void onTokenRenewed(String token, ZIMError error) {
// You can tell by the ZIMErrorCode whether the Token is renewed successfully.
}
});
}
1
ZIMEventHandler.onTokenWillExpire = (zim, second) {
ZIM.getInstance().renewToken('new token');
};
1
- (void)zim:(ZIM *)zim tokenWillExpire:(unsigned int)second {
NSString *token = [MyToken getToken]; // Obtain a new token from the server.
[self.zim renewToken:token callback:^(ZIMError * _Nonnull errorInfo) {
// Check whether the token is updated successfully based on the `ZIMErrorCode`.
......
}];
}
1
- (void)zim:(ZIM *)zim tokenWillExpire:(unsigned int)second {
NSString *token = [MyToken getToken]; // Obtain a new token from the server.
[self.zim renewToken:token callback:^(ZIMError * _Nonnull errorInfo) {
// Check whether the token is updated successfully based on the `ZIMErrorCode`.
......
}];
}
1
// zim is the instance you created.
zim.onTokenWillExpire = (ZIM zim, uint second) =>
{
zim.RenewToken("new token", (string token, ZIMError errorInfo) =>
{
// You can tell by the ZIMErrorCode whether the Token is renewed successfully.
});
};
1
void onTokenWillExpire(ZIM * zim, unsigned int second) override {
std::string token = getToken(); // Request a new Token from app server.
zim->renewToken(token, [=](const std::string &token, zim::ZIMError errorInfo) {
// You can tell by the ZIMError errorInfo whether the room login is successful.
......
});
}
1
