TaskRouter.js v1: Constructing JWTs: Managing access policies for client side requests

JWTs consist of three hashed sections:

• Header
• Payload
• Signature

Let's first go over the two smaller sections of the JWT.

The first part of our JWT token is the header which contains 2 parts:

1
{
2
  "typ": "JWT",
3
  "alg": "HS256"
4
}

This tells us that this is indeed a JWT and the hashing algorithm used is HS256.

The third and final part of our JSON Web Token is going to be the signature. This signature is made up of a hash of the following components:

• Header
• Payload
• Secret

In formula terms this is:

hash((hash(header) + hash(payload)), 'secret')

The secret is your AuthToken.

The payload of the JWT is what defines the access policies for resources.

Access Policy Objects are a set of rules that can be applied to an HTTP REST request, authorizing whether this request is allowed to access the API resources. The policy defines which resources and sub-resources are allowed to be accessed, what parameters are expected and allowed, and whether or not the resources and sub-resources are outright forbidden. Access policies will be represented as JSON objects.

The Access Policy Object is a JSON object with the following fields.

The "policies" array contains policy rule objects.

The url key defines a literal or pattern that will be matched against the request's URL. This field should contain the URL without query parameters and may either be a literal string or end in a wildcard string. Literal strings must exactly match the request URL for this rule to match. There are two types of wildcard strings:

• Immediate child wildcard (URLs ending in "/*").
• Recursive wildcard (URLs ending in "/**").

Immediate child wildcards cause a rule to match the next step in the path, but no further.

For example:

• https://taskrouter.twilio.com/v1/Workspaces/*

Matches:

• https://taskrouter.twilio.com/v1/Workspaces/WSxxx

But not these URLs:

• https://taskrouter.twilio.com/v1/Workspaces/
• https://taskrouter.twilio.com/v1/Workspaces/WSxxx/TaskQueues

Recursive wildcards cause a URL to match any child URL of this path.

For example:

• https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**

Matches:

• https://taskrouter.twilio.com/v1/Workspaces/WSxxx/TaskQueues
• https://taskrouter.twilio.com/v1/Workspaces/WSxxx/TaskQueues/WQxxx
• https://taskrouter.twilio.com/v1/Workspaces/WSxxx/Workers/WKxxx/Statistics
• https://taskrouter.twilio.com/v1/Workspaces/WSxxx/Statistics

But not:

• https://taskrouter.twilio.com/v1/Workspaces/WSxxxx
• https://taskrouter.twilio.com/v1/Workspaces

Multiple Rule Matching

• For requests that match multiple rules, the rule that is most specific takes priority.
• Longer, more specific paths take priority over less specific.
• If the paths are the same, rules with filters take priority over rules without filters.
• Directly conflicting rules are considered invalid and should be detected and rejected by the access policy parser.

The HTTP method this rule applies to: GET, POST, DELETE

Allow may have a value of true or false. If the matching rule has an allow value of "true", the request is authorized. If the allow value is false, the request is explicitly rejected. The default for all rules is "false".

The post_filter and query_filter fields are used to match parameters provided in either the query string or www-form-post-params. The value is an object whose keys are the parameter names, and values are either a string literal that must be matched, or a matcher object that describes how the key is matched in more detail. Both post and query filters use the same format.

String Literal Example

1
"post_filter": {
2
    "FriendlyName": "Alice"
3
}

This would match a request that contained a single www-form-encoded parameter FriendlyName with the value Alice. If the request contained any other form parameters, it would not match this rule.

Matcher Object Example

1
"post_filter": {
2
   "FriendlyName": {"required": true},
3
   "Status": {"required": false},
4
   "Foo": {"required": false, "value": "bar"}
5
}

Matcher objects allow for more complex matching rules. In the above example, the field FriendlyName is required, but will match any provided value. The field Status is optional, meaning this rule will match if its provided or not. If it is provided, any value will be allowed. The field "Foo" is optional as well, but if it is provided, it must have the value "bar".

Matcher Object

In addition to our list of policies, we need to define the following in the payload:

• iss: The issuer of the token (AccountSid)
• exp: When the token will expire (TimeStamp in seconds since epoch)
• account_sid: Account owner of the token
• workspace_sid: Workspace owner of the token
• channel: The channel to receive updates on and post API requests to.

If you are defining a Worker, you will also need to define the following:

• channel: WSxxx
• worker_sid: WKxxx

If you are defining a Workspace, you will also need to define the following:

• channel: WSxxx

Two required policies in your JWT include the ability to connect to a web-socket channel and post messages on that web-socket to hit the REST API. These are required since we want to authenicate and authorize the opening a websocket in the first place. Subsequent events to GET, POST or DELETE to other APIs will utilize this websocket.

For example:

1
{
2
    "url": "https://event-bridge.twilio.com/v1/wschannels/AccountSid/Channel",
3
    "method": "GET",
4
    "allow": true
5
},
6
{
7
    "url": "https://event-bridge.twilio.com/v1/wschannels/AccountSid/Channel",
8
    "method": "POST",
9
    "allow": true
10
}

Let's take an example using the helper library and see what this breaks down to as a policy object:

1
<?php
2
$workspaceCapability = new Services_Twilio_TaskRouter_Capability($accountSid, $authToken, $workspaceSid, $workspaceSid);
3
$workspaceCapability->allowFetchSubresources();
4
$workspaceCapability->allowDeleteSubresources();
5
$workspaceCapability->allowUpdatesSubresources();
6
$workspaceToken = $workspaceCapability->generateToken();

The policy object would look like the following:

1
{
2
    "url": "https://event-bridge.twilio.com/v1/wschannels/ACxxx/WSxxx",
3
    "method": "GET",
4
    "allow": true
5
},
6
{
7
    "url": "https://event-bridge.twilio.com/v1/wschannels/ACxxx/WSxxx",
8
    "method": "POST",
9
    "allow": true
10
},
11
{
12
    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx",
13
    "method": "GET",
14
    "allow": true
15
},
16
{
17
    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**",
18
    "method": "GET",
19
    "allow": true
20
},
21
{
22
    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**",
23
    "method": "POST",
24
    "allow": true
25
},
26
{
27
    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**",
28
    "method": "DELETE",
29
    "allow": true
30
}

In total, the JWT payload would decode to:

1
{
2
  "version": "v1",
3
  "friendly_name": "WSxxx",
4
  "policies": [
5
    {
6
      "url": "https://event-bridge.twilio.com/v1/wschannels/ACxxx/WSxxx",
7
      "method": "GET",
8
      "allow": true
9
    },
10
    {
11
      "url": "https://event-bridge.twilio.com/v1/wschannels/ACxxx/WSxxx",
12
      "method": "POST",
13
      "allow": true
14
    },
15
    {
16
      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx",
17
      "method": "GET",
18
      "allow": true
19
    },
20
    {
21
      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**",
22
      "method": "GET",
23
      "allow": true
24
    },
25
    {
26
      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**",
27
      "method": "DELETE",
28
      "allow": true
29
    },
30
    {
31
      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSxxx/**",
32
      "method": "POST",
33
      "allow": true
34
    }
35
  ],
36
  "iss": "ACxxx",
37
  "exp": 1432251317,
38
  "account_sid": "ACxxx",
39
  "channel": "WSxxx",
40
  "workspace_sid": "WSxxx"
41
}