Browse Source

fix(docs): correct the grammar in token docs

dev1
Gary Hunt 4 years ago
parent
commit
c8939c0dec
1 changed files with 26 additions and 26 deletions
  1. 26
    26
      doc/tokens.md

+ 26
- 26
doc/tokens.md View File

1
 JWT token authentication Prosody plugin
1
 JWT token authentication Prosody plugin
2
 ==================
2
 ==================
3
 
3
 
4
-This plugin implements Prosody authentication provider that verifies client connection based on JWT token described in [RFC7519].
5
-It allows to use any external form of authentication with lib-jitsi-meet. Once your user authenticates you need to
6
-generate the JWT token as described in the RFC and pass it to your client app. Once it connects with valid token is considered authenticated by jitsi-meet system.
4
+This plugin implements a Prosody authentication provider that verifies a client connection based on a JWT token described in [RFC7519].
5
+It allows use of an external form of authentication with lib-jitsi-meet. Once your user authenticates you need to
6
+generate the JWT token as described in the RFC and pass it to your client app. Once it connects with a valid token it is considered authenticated by the jitsi-meet system.
7
 
7
 
8
-During configuration you will need to provide the *application ID* that identifies the client and a *secret* shared by both server and JWT token generator. Like described in the RFC, secret is used to compute HMAC hash value which allows to authenticate generated token. There are many existing libraries which can be used to implement token generator. More info can be found here: [http://jwt.io/#libraries-io]
8
+During configuration you will need to provide the *application ID* that identifies the client and a *secret* shared by both server and JWT token generator. Like described in the RFC, the secret is used to compute a HMAC hash value which allows authentication of the generated token. There are many existing libraries which can be used to implement token generation. More info can be found here: [http://jwt.io/#libraries-io]
9
 
9
 
10
-JWT token authentication currently works only with BOSH connections.
10
+JWT token authentication only currently works with BOSH connections.
11
 
11
 
12
 [RFC7519]: https://tools.ietf.org/html/rfc7519
12
 [RFC7519]: https://tools.ietf.org/html/rfc7519
13
 [http://jwt.io/#libraries-io]: http://jwt.io/#libraries-io
13
 [http://jwt.io/#libraries-io]: http://jwt.io/#libraries-io
14
 
14
 
15
 ### Token structure
15
 ### Token structure
16
 
16
 
17
-The following JWT claims are used in authentication token:
18
-- 'iss' specifies *application ID* which identifies the client app connecting to the server. It should be negotiated with the service provider before generating the token.
19
-- 'room' contains the name of the room for which the token has been allocated. This is *NOT* full MUC room address. Example assuming that we have full MUC 'conference1@muc.server.net' then 'conference1' should be used here.  Alternately, a '*' may be provided, allowing access to all rooms within the domain.
17
+The following JWT claims are used in the authentication token:
18
+- 'iss' specifies the *application ID* which identifies the client app connecting to the server. It should be negotiated with the service provider before generating the token.
19
+- 'room' contains the name of the room for which the token has been allocated. This is *NOT* the full MUC room address. An example assuming that we have full MUC 'conference1@muc.server.net' would be that 'conference1' should be used here.  Alternately, a '*' may be provided, allowing access to all rooms within the domain.
20
 - 'exp' token expiration timestamp as defined in the RFC
20
 - 'exp' token expiration timestamp as defined in the RFC
21
 - 'sub' contains EITHER the lowercase name of the tenant (for a conference like TENANT1/ROOM with would be 'tenant1') OR the lowercase name of the domain used when authenticating with this token (for a conference like /ROOM). By default assuming that we have full MUC 'conference1@muc.server.net' then 'server.net' should be used here.  Alternately, a '*' may be provided, allowing access to rooms in all tenants within the domain or all domains within the server.
21
 - 'sub' contains EITHER the lowercase name of the tenant (for a conference like TENANT1/ROOM with would be 'tenant1') OR the lowercase name of the domain used when authenticating with this token (for a conference like /ROOM). By default assuming that we have full MUC 'conference1@muc.server.net' then 'server.net' should be used here.  Alternately, a '*' may be provided, allowing access to rooms in all tenants within the domain or all domains within the server.
22
 - 'aud' application identifier. This value indicates what service is consuming the token.  It should be negotiated with the service provider before generating the token.
22
 - 'aud' application identifier. This value indicates what service is consuming the token.  It should be negotiated with the service provider before generating the token.
23
 
23
 
24
-Secret is used to compute HMAC hash value and verify the token for HS256 tokens.  
24
+The secret is used to compute the HMAC hash value and verify the token for HS256 tokens.  
25
 
25
 
26
-Alternately the token may be signed by a private key and authorized via public keyserver using RS256 tokens.  In this mode, the 'kid' header of the JWT must be set to the name of the public key.  The backend server must be configured to fetch and confirm keys from a pre-configured public keyserver.
26
+Alternately the token may be signed by a private key and authorized via a public keyserver using RS256 tokens.  In this mode, the 'kid' header of the JWT must be set to the name of the public key.  The backend server must be configured to fetch and confirm keys from a pre-configured public keyserver.
27
 
27
 
28
 ### Token Identifiers
28
 ### Token Identifiers
29
 
29
 
35
   - 'email' is the email of the user
35
   - 'email' is the email of the user
36
   - 'avatar' is the URL of the avatar for the user
36
   - 'avatar' is the URL of the avatar for the user
37
 > Note: As the moment all fields in 'user' need to be a valid string, numeric types or `null` will generate an exception.
37
 > Note: As the moment all fields in 'user' need to be a valid string, numeric types or `null` will generate an exception.
38
-- 'callee' is an optional object containing display information when launching a 1-1 video call with a single other participant.  It used to display an overlay to the first user, before the second user joins.
38
+- 'callee' is an optional object containing display information when launching a 1-1 video call with a single other participant. It is used to display an overlay to the first user, before the second user joins.
39
   - 'id' is a user identifier string.  Intended for use in reporting/analytics
39
   - 'id' is a user identifier string.  Intended for use in reporting/analytics
40
   - 'name' is the display name of the 'callee' user
40
   - 'name' is the display name of the 'callee' user
41
   - 'avatar' is the URL of the avatar of the 'callee'
41
   - 'avatar' is the URL of the avatar of the 'callee'
48
     modules_enabled = { "presence_identity" }
48
     modules_enabled = { "presence_identity" }
49
 ```
49
 ```
50
 
50
 
51
-The data is now available as the identity in the JitsiParticipant class. You can access them by e.g. listening to the `USER_JOINED` event.
51
+The data is now available in the identity in the JitsiParticipant class. You can access them by e.g. listening to the `USER_JOINED` event.
52
 
52
 
53
 NOTE: The values in the token shall always be valid values. If you define e.g. the avatar as `null` it will throw an error.
53
 NOTE: The values in the token shall always be valid values. If you define e.g. the avatar as `null` it will throw an error.
54
 
54
 
83
 ### Token verification
83
 ### Token verification
84
 
84
 
85
 JWT token is currently checked in 2 places:
85
 JWT token is currently checked in 2 places:
86
-- when user connects to Prosody through BOSH. Token value is passed as 'token' query paramater of BOSH URL. User uses XMPP anonymous authentication method.
87
-- when MUC room is being created/joined Prosody compares 'room' claim with the actual name of the room. In addition, the 'sub' claim is compare to either the tenant (for TENANT/ROOM URLs) or the base domain (for /ROOM URLs).  This prevents stolen token being abused by unathorized users to allocate new conference rooms in the system. Admin users are not required to provide valid token which is used by Jicofo for example.
86
+- when a user connects to Prosody through BOSH. The token value is passed as the 'token' query paramater of the BOSH URL. User uses XMPP anonymous authentication method.
87
+- when a MUC room is being created/joined Prosody compares the 'room' claim with the actual name of the room. In addition, the 'sub' claim is compare to either the tenant (for TENANT/ROOM URLs) or the base domain (for /ROOM URLs).  This prevents a stolen token being abused by unathorized users to allocate new conference rooms in the system. Admin users are not required to provide a valid token which is used for example by Jicofo.
88
 
88
 
89
 ### Lib-jitsi-meet options
89
 ### Lib-jitsi-meet options
90
 
90
 
91
-When JWT authentication is used with *lib-jitsi-meet* the token is passed to *JitsiConference* constructor:
91
+When JWT authentication is used with *lib-jitsi-meet* the token is passed to the *JitsiConference* constructor:
92
 
92
 
93
 ```
93
 ```
94
 var token = {token is provided by your application possibly after some authentication}
94
 var token = {token is provided by your application possibly after some authentication}
103
 
103
 
104
 ### Jitsi-meet options
104
 ### Jitsi-meet options
105
 
105
 
106
-In order to start jitsi-meet conference with token you need to specify the token as URL param:
106
+In order to start a jitsi-meet conference with a token you need to specify the token as an URL param:
107
 ```
107
 ```
108
 https://example.com/angrywhalesgrowhigh?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
108
 https://example.com/angrywhalesgrowhigh?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
109
 ```
109
 ```
110
-At current level of integration every user that joins the conference has to provide the token and not just the one who
111
-creates the room. It should be possible to change that by using second anonymous domain, but that hasn't been tested
110
+At the current level of integration every user that joins the conference has to provide the token and not just the one who
111
+creates the room. It should be possible to change that by using a second anonymous domain, but that hasn't been tested
112
 yet.
112
 yet.
113
 
113
 
114
 
114
 
115
 
115
 
116
-### Installing token plugin
116
+### Installing the token plugin
117
 
117
 
118
-Token authentication can be integrated automatically using Debian package install. Once you have jitsi-meet installed
118
+Token authentication can be integrated automatically using a Debian package install. Once you have jitsi-meet installed
119
 just install 'jitsi-meet-tokens' on top of it. In order to have it configured automatically at least version 779 of
119
 just install 'jitsi-meet-tokens' on top of it. In order to have it configured automatically at least version 779 of
120
-jitsi-meet is required which comes with special Prosody config template.
120
+jitsi-meet is required which comes with a special Prosody config template.
121
 
121
 
122
 ```
122
 ```
123
 apt-get install jitsi-meet-tokens
123
 apt-get install jitsi-meet-tokens
135
 Include "conf.d/*.cfg.lua"
135
 Include "conf.d/*.cfg.lua"
136
 ```
136
 ```
137
 
137
 
138
-Also check if client to server encryption is not enforced. Otherwise token authentication won't work:
138
+Also check if client to server encryption is enforced. If not then token authentication won't work:
139
 ```
139
 ```
140
 c2s_require_encryption=false
140
 c2s_require_encryption=false
141
 ```
141
 ```
151
 
151
 
152
 Modify your Prosody config with these three steps:
152
 Modify your Prosody config with these three steps:
153
 
153
 
154
-\1. Adjust *plugin_paths* to contain the path pointing to jitsi meet Prosody plugins location. That's where plugins are copied on *jitsi-meet-token* package install. This should be included in global config section(possibly at the beginning of your host config file).
154
+\1. Adjust *plugin_paths* to contain the path pointing to the jitsi meet Prosody plugins location. That's where plugins are copied on *jitsi-meet-token* package installation. This should be included in the global config section (possibly at the beginning of your host config file).
155
 
155
 
156
 ```lua
156
 ```lua
157
 plugin_paths = { "/usr/share/jitsi-meet/prosody-plugins/" }
157
 plugin_paths = { "/usr/share/jitsi-meet/prosody-plugins/" }
158
 ```
158
 ```
159
 
159
 
160
-Also optionally set the global settings for key authorization.  Both these options default to the '*' parameter which means accept any issuer or audience string in incoming tokens
160
+Also, optionally set the global settings for key authorization.  Both these options default to the '*' parameter which means accept any issuer or audience string in incoming tokens
161
 ```lua
161
 ```lua
162
 asap_accepted_issuers = { "jitsi", "some-other-issuer" }
162
 asap_accepted_issuers = { "jitsi", "some-other-issuer" }
163
 asap_accepted_audiences = { "jitsi", "some-other-audience" }
163
 asap_accepted_audiences = { "jitsi", "some-other-audience" }
164
 ```
164
 ```
165
 
165
 
166
-\2. Under you domain config change authentication to "token" and provide application ID, secret and optionally token lifetime:
166
+\2. Under your domain config change authentication to "token" and provide the application ID, secret and optionally the token lifetime:
167
 
167
 
168
 ```lua
168
 ```lua
169
 VirtualHost "jitmeet.example.com"
169
 VirtualHost "jitmeet.example.com"
185
 ```
185
 ```
186
 
186
 
187
 
187
 
188
-\3. Enable room name token verification plugin in your MUC component config section:
188
+\3. Enable the room name token verification plugin in your MUC component config section:
189
 
189
 
190
 ```lua
190
 ```lua
191
 Component "conference.jitmeet.example.com" "muc"
191
 Component "conference.jitmeet.example.com" "muc"

Loading…
Cancel
Save