Skip to content

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.

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":{
}