guestissuer

CLI to generate JWT and access tokens for Webex Teams 'Permanent Guest'

'Guest Issuer' applications allow guests (aka, non Webex Teams users) to persistently use the Webex cloud platform through the Teams SDKs and Widgets. Check the online documentation for details.

The guestissuer command line interface (CLI) helps generate Guest tokens for 'Guest Issuer' applications.

To use the tool, you'll first need to create a 'Guest Issuer' application from Webex for Developers portal, and fetch your 'Guest Issuer' application's identifier and secret. Note that you need a Webex Teams PAYING account to create 'Guest Issuer' applications.

Quick Start

To generate a Guest token, type the commands below in a terminal:

Note for Mac/Linux users: add sudo before each of the npm install commands below.

# Install the CLI 
npm install guestissuer -g
 
# Create a JWT Guest token with the specified user info (expires in 90 minutes by default) 
guestissuer create <userId> <userName> -i <issuerAppId> -s <issuerAppSecret> [-d <expirationDelay>]
 
# Fetch an access token for the Guest user (valid for 6 hours) 
guestissuer login <guestToken>

You can even get there quicker with the quick command:

# Install the CLI 
npm install guestissuer -g
 
# Create a Guest token, and fetch an access token right away (valid for 6 hours) 
# Here, the JWT guest token is volatile (neither stored, not returned) 
guestissuer quick <userId> <userName> -i <issuerAppId> -s <issuerAppSecret>

Detailled instructions

To install the guestissuer CLI, type:

```shell
npm install guestissuer -g
```

To create a JWT 'Guest token' for a 'Guest' user (non Webex Teams users), type:

```shell
guestissuer [create] <userId> <userName> -i <issuerAppId> -s <issuerAppSecret> [-d <expirationDelay>]
```

Where:
    - `userId` is a user identifier unique to your 'Guest Issuer'. This identifier is used by the Webex cloud platform to persist user data among sessions. Understand: if another token gets generated with the same 'userId', the Guest user interacting with that token will see Spaces, Messages, and inherit Memberships from previous Webex interactions for this 'userId',
    - `userName` is used to identify the user in Webex Teams spaces,
    - `expirationDelay` should be specified in seconds, defaults to 5400s (90min) from now.
    - the `issuerAppId` and `issuerAppSecret` tie to the 'Guest Issuer Application' created from the [Webex for Developers portal](https://developer.webex.com/add-guest.html).

Example (with verbose debugging info):

```shell
DEBUG=guest*  guestissuer create "123" "Stève" -i Y2lz...VzLMDY -s AMx/FPI...NABzD6o=
    guest arguments successfully checked +0ms
    guest successfully built Guest token: BDmh0rgbcVMfpklnyWfurxX5Y... +59ms
    guest Guest token is valid till XXXXX +1ms        
eyJhbGciOiJSUzI1NiJ9.eyJtYWN...uNDU1WiJ9.berce_d8vrRw6vDI....nMAlnYNj-f921mcqU
```

Note that:
    - instead of passing them through command line parameters, you can alternatively specify the 'Guest Issuer Application'  identifier and secret via environment variables `ISSUER` and `SECRET` 
    - the `create` command is the default's for guestissuer. You can omit it as in `guestissuer "123" "Stève" -i Y2lz...VzLMDY -s AMx/FPI...NABzD6o=`

Once you've got a JWT 'Guest token', you'll need to fetch an access token (valid for 6 hours).

```shell
guestissuer login <guestToken>
```

Note that:
   - the command uses the Webex Teams API 's /jwt/login endpoint behind the scene.
   - the fetched accessed token is valid for 6 hours

To quickly check the data contained in a JWT token (guest or access token):

```shell
guestissuer verify --jwt <token>
```

To quickly the Person behind an access token (equivalent tp a GET /people/me request):

```shell
guestissuer verify --access <access_token>
```

Guest tokens

Guest tokens have a JWT format, and are signed with your 'Guest Issuer Application' secret so that Webex can be assured of its origin. It contains an expiration date so that Webex will refuse to generate access tokens - via the /jwt/login endpoint - after the expiration date.

Example of Guest token

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJuYW1lIjoiU3TDqHZlIiwiaXNzIjoiWTJselkyOXpjR0Z5YXpvdkwzVnpMMDlTUjBGT1NWcEJWRWxQVGk4ek9URTRPR00zTWkwd01ESTVMVF EzWVRRdFlqQXlOUzAxT0dFd1kyRTNORFZrTURZIiwiZXhwIjoxNTE3MDczMDE5fQ.imX0LgZ6LT-xlT3A6mzF5gyGN0S2ty2aUyjTM35E8y4    

Note that the Guest token also has a JWT format. If you decode it, you'll discover its contents. Go to https://jwt.io to decode it, or simply type: guestissuer verify --jwt <guest_token>

Decoded Header Section

{
  "alg": "HS256",
  "typ": "JWT"
}

Decoded Data section

{
  "sub": "123",
  "name": "Stève",
  "iss": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8zOTE4OGM3Mi0wMDI5LTQ3YTQtYjAyNS01OGEwY2E3NDVkMDY",
  "exp": 1517073019
}

Retreiving API access tokens for 'Guest' users

These tokens are generated from 'Guest tokens' by invoking Webex Teams API 's /jwt/login endpoint They give access to the Webex Teams API, SDKs and Widgets under the identity of the 'Guest' user.

To test an access token for a user, reach to the GET /people/me resource, paste the access token and run the request. Alternatively, you can type: guestissuer verify --access <access_token>

Example of Person details for an access token attached to a Guest user:

_Note that the person type is `bot` and the email is formed from `<user_id>@<decoded-org>`_

```json
{
    "id": "Y2lzY29zcGFyazovL3VzL1B....Q5YzgtODAzMS02OTY1NWM4MGI3Njc",
    "emails": [
        "123@39188c72-0029-47a4-b025-58a0ca745d06"
    ],
    "displayName": "Stève",
    "avatar": "https://00792fd90955bc2.....da928cc2123a400b.ssl.cf1.rackcdn.com/default_machine~80",
    "orgId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVp...DI5LTQ3YTQtYjAyNS01OGEwY2E3NDVkMDY",
    "created": "2018-01-27T16:13:25.558Z",
    "type": "appuser"
}
```

Note that the issued token also has a JWT format. If you decode it, you'll discover its structure. Go to https://jwt.io, or simply type: guestissuer verify --jwt <token>

Decoded Header Section

{
  "alg": "RS256"
}

Decoded Data section

{
  "machine_type": "appuser",
  "expiry_time": 1517095624105,
  "user_type": "machine",
  "realm": "2a9e1....ad3c991b1b5",
  "cis_uuid": "8dcc341a...55c80b767",
  "reference_id": "b4f77f9.....204f3daac88",
  "iss": "https://idbroker.webex.com/idb",
  "token_type": "Bearer",
  "client_id": "C311772...1c2c82784a1f2975c",
  "token_id": "AaZ3r0t...0YzIxYzliZGE0NDNiOGRiYzctMmI1",
  "private": "eyJhbGciOiJkaXIiL...Tx45V0-PA",
  "user_modify_timestamp": "20180127172701.477Z"
}

Tip : Adding a 'Permanent Guest' to a space

The general use case for "Permanent Guest" is to call an existing Webex Teams user, and create a space and add Bots or Webex Teams users to the space.

Sometimes, you may be interested to add a 'Permanent Guest' to an existing space (or newly created space). You'll hit a difficulty here since 'Permanent Guest' cannot be reached via their Webex email. Simply use the personId in the POST /membership - Create a membership resource. Note that you can get the Webex Teams personId of a "Permanent Guest" through a GET /people/me request issued with the "Permanent Guest" access token.