Authorization (Token)
Kumoi service use JWT token with algorithm ES256 to validate permission and authorization.
JWT Token is combined by three parts: Header, Payload, Signature
JWT Token
Token format will be Header.Payload.Signature
The following table describe the Required and Optional field for Kumoi service.
Kumoi service use ES256 algorithm to sign and validate token.
Header
| Fields | Value | Description |
|---|---|---|
| Required | ||
| alg | string | Signature Algorithm, Default: ES256 |
| typ | string | Token Type, Default: JWT |
| kid | string(32) | Signed Key Id |
Payload
| Fields | Value | Description |
|---|---|---|
| Required | ||
| iss | string(32) | Issuer, Signed App Id |
| aud | string | Audience, Default: GUNDAM |
| exp | integer | Expiration Time, token will be expired after this timestamp |
| Optional | ||
| nbf | integer | Not Before, token will not be accepted before this timestamp |
| iat | integer | Issued At, the timestamp of token issued |
| jti | string(36) | JWT Token Id, usually be UUID |
| sub | string(64) | Token User Id |
| nam | string(64) | Token Username |
| gne | string(32) | Gene sequence of token, empty or not exist means ROOT token |
| mta | object(4K) | Session Metadata |
| pri[] | Permission | List of Permission, means Token can be used for |
| ext | Extension | Extension Field, such like query check q_check and so on |
| cmu | object(4K) | Customize Field, size limit to 4KB |
Signature
Use ES256 to sign Concat("Header",".","Payload") and append to the tail of Payload with . prefix
Example
Header
Raw
{
"alg": "ES256",
"typ": "JWT",
"kid": "C37635C6EEE541A9AE55AECACF80E4EB"
}
Formatted (Encoded by Base64URL)
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkMzNzYzNUM2RUVFNTQxQTlBRTU1QUVDQUNGODBFNEVCIn0
Payload
Raw
{
"iss": "C37635C6EEE541A9AE55AECACF80E4CC",
"aud": "GUNDAM",
"jti": "C37632C6EEE541A9AE55AECACF10E4AB",
"sub": "wdksoejs13",
"nam": "John",
"gne": "KKSeq",
"pri": [
"playback"
],
"ext": {
"q_check": {
"dict_max": "5"
},
"api_vars":{
"/api/d/dictionaries": {
"total_count": 5
}
}
},
"iat": 1516239022,
"exp": 1516293022
}
Formatted (Encoded by Base64URL)
eyJpc3MiOiJDMzc2MzVDNkVFRTU0MUE5QUU1NUFFQ0FDRjgwRTRDQyIsImF1ZCI6IkdVTkRBTSIsImp0aSI6IkMzNzYzMkM2RUVFNTQxQTlBRTU1QUVDQUNGMTBFNEFCIiwic3ViIjoid2Rrc29lanMxMyIsIm5hbSI6IkpvaG4iLCJnbmUiOiJLS1NlcSIsInByaSI6WyJwbGF5YmFjayJdLCJleHQiOnsicV9jaGVjayI6eyJkaWN0X21heCI6IjUifSwiYXBpX3ZhcnMiOnsiL2FwaS9kL2RpY3Rpb25hcmllcyI6eyJ0b3RhbF9jb3VudCI6NX19fSwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyOTMwMjJ9
Signature
Signature = Base64URL.Encode(
ES256.Sign(eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkMzNzYzNUM2RUVFNTQxQTlBRTU1QUVDQUNGODBFNEVCIn0.eyJpc3MiOiJDMzc2MzVDNkVFRTU0MUE5QUU1NUFFQ0FDRjgwRTRDQyIsImF1ZCI6IkdVTkRBTSIsImp0aSI6IkMzNzYzMkM2RUVFNTQxQTlBRTU1QUVDQUNGMTBFNEFCIiwic3ViIjoid2Rrc29lanMxMyIsIm5hbSI6IkpvaG4iLCJnbmUiOiJLS1NlcSIsInByaSI6WyJwbGF5YmFjayJdLCJleHQiOnsicV9jaGVjayI6eyJkaWN0X21heCI6IjUifSwiYXBpX3ZhcnMiOnsiL2FwaS9kL2RpY3Rpb25hcmllcyI6eyJ0b3RhbF9jb3VudCI6NX19fSwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyOTMwMjJ9))
= nsLDZfUpEdgnlLM4BnzpCXbrVxrGWRms3Td2oPieRMPsdgngJ7Q4lmubiV50A2s7Jw4mTI2Q_-nXEIoUABfCKQ
It concat those parts with ., and the Token will be
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkMzNzYzNUM2RUVFNTQxQTlBRTU1QUVDQUNGODBFNEVCIn0.eyJpc3MiOiJDMzc2MzVDNkVFRTU0MUE5QUU1NUFFQ0FDRjgwRTRDQyIsImF1ZCI6IkdVTkRBTSIsImp0aSI6IkMzNzYzMkM2RUVFNTQxQTlBRTU1QUVDQUNGMTBFNEFCIiwic3ViIjoid2Rrc29lanMxMyIsIm5hbSI6IkpvaG4iLCJnbmUiOiJLS1NlcSIsInByaSI6WyJwbGF5YmFjayJdLCJleHQiOnsicV9jaGVjayI6eyJkaWN0X21heCI6IjUifSwiYXBpX3ZhcnMiOnsiL2FwaS9kL2RpY3Rpb25hcmllcyI6eyJ0b3RhbF9jb3VudCI6NX19fSwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyOTMwMjJ9.nsLDZfUpEdgnlLM4BnzpCXbrVxrGWRms3Td2oPieRMPsdgngJ7Q4lmubiV50A2s7Jw4mTI2Q_-nXEIoUABfCKQ
It uses Signature part to check the Token is correct or not.
Permission
| Name | Description |
|---|---|
| broadcast | broadcast message |
| create_channel | create channel |
| create_vote | create vote |
| playback | playback channel history message after channel closed |
| replay | replay channel history message for target channel |
| manage | granted for all permissions |
Extension
| Fields | Value | Description |
|---|---|---|
| q_check | object | Service will check the Request API Query Parameter, all q_check value should equal to the value of key |
| h_check | object | Service will check the Request API Header, all h_check value should equal to the value of key |
| f_check | object | Service will check the Request API Form, all f_check value should equal to the value of key |
| p_check | object | Service will check the Request API Path, all p_check value should equal to the value of key |
| api_vars | ExtAPIVars | variable of endpoints |
| scopes | ExtScopes | resource scope constraint |
Example
q_check
For token ext with {"q_check":{"dict_max":"5"}} and API Request Path
is /v1/app/C37635C6EEE541A9AE55AECACF80E4CC/ch/CI6IjUifX0sImlhdCI6MTUxNjIz?dict_max=100
, it will check the Query Parameter value with key dict_max,
if the value is existed and not equal to 5, it will return with error response.
p_check
For token ext with {"q_check":{"dict_max":"5"}, "p_check":{"ch":"CI6IjUifX0sImlhdCI6MTUxNjIz"}} and API Request Path
is /v1/app/C37635C6EEE541A9AE55AECACF80E4CC/ch/CI6IjUifX0sImlhdCI6MTUxNjIz
, the ch id from API Request Path is CI6IjUifX0sImlhdCI6MTUxNjIz and equal to p_check.ch value, it will pass the check.
ExtAPIVars
ExtAPIVars is JSON object with api endpoint path(start from /api) as key
Example
| Fields | Value | Description |
|---|---|---|
| /api/d/dictionaries | object | total_count means the total count limit of dictionaries of token gne sequence and it's extended gne sequence, not exist means NO LIMIT, -1 means NO PERMISSION |
"api_vars":{
"/api/d/dictionaries": {
"total_count": 5
}
}
ExtScopes
ExtScopes is JSON object, which use to limit the accessibility of channel or vote.
keep scopes empty or not present means NO LIMIT
| Fields | Value | Description |
|---|---|---|
| channels[] | string | channels is a string array to contain the channel_id of accessible channels, empty means NO LIMIT |
| votes[] | string | votes is a string array to contain the vote_id of accessible votes, empty means NO LIMIT |
Example
the token only can access the channel with id chid_1 and all vote
"scopes":{
"channels": ["chid_1"]
}
the token only can access the channel with id chid_1 and the vote with id voteid_1
"scopes":{
"channels": ["chid_1"],
"votes": ["voteid_1"]
}
the token can NOT access any channel, and it can access all vote.
"scopes":{
"channels": [""]
}
the token can access all channel and vote
"scopes":{
}