Guest Issuer Applications

Overview

As a Webex Teams developer, you can create Integrations to interact with Webex Teams on behalf of a user. You can also create Bots that act as an independent user representing your service or product. But, what if you want to interact with users who do not have a Webex Teams account? These users may be visitors to a website who you'd like to message with over Webex Teams. Or they may be customers in a store you’d like to have a video call with. These guest users can interact with regular Webex Teams users via tokens generated by a Guest Issuer application.

Guest users of Webex Teams authenticate with Guest Tokens. Guest Tokens use the JSON Web Token (JWT) standard to create and share authentication credentials between our SDKs & Widgets and the Webex Teams API. These tokens are exchanged for an OAuth authentication token which can be used for a limited time, and limited purpose, to interact with regular Webex Teams users.

Each Guest Token should be associated with an individual user of your application. Their activity within Webex Teams, such as message activity or call history, will persist, just like a regular Webex Teams user. While guest users can interact with regular Webex Teams users, they are not allowed to interact with other guests.

Guest Issuer App

Before you can create Guest Tokens, you will need to create a new Guest Issuer application in My Webex Teams Apps for use with your app. This application type will provide you with a Guest Issuer ID and a Secret. These two parameters will be used to generate Guest Tokens. Only paid Webex Teams subscribers may create Guest Issuer applications.

After creating a Guest Issuer application, the secret will only be shown once. Keep this shared secret safe, as you would with any other sensitive piece of information such as a password. If you need to regenerate the secret for any reason, the prior secret will be immediately invalidated.

Generating Guest Tokens

Once you create a Guest Issuer app in My Webex Teams Apps, you can create Guest Tokens to authenticate guest users and perform actions against the Webex Teams API.

Guest Tokens use the JSON Web Token (JWT) standard. JSON Web Tokens are composed of three parts, separated by a dot (.):

  • Header
  • Payload
  • Signature

Header

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

The header describes the token:

typ The type of token. Must be JWT.
alg The hashing algorithm. Must be HS256.

The header is base64url encoded to create the first part of the token.

Payload

{
  "sub": "guest-user-7349",
  "name": "Guest User's Display Name"
  "iss": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE",
  "exp": "1511286849"
}

The payload contains the claims for the token. The Webex Teams API expects the following claims:

sub The subject of the token—a unique, public identifier for the end-user of the token. This claim may contain only letters, numbers, and hyphens. This claim is required.
name The display name of the guest user. This will be the name shown in Webex Teams clients.
iss The issuer of the token. Use the Guest Issuer ID provided in My Webex Teams Apps. This claim is required.
exp The expiration time of the token, as a UNIX timestamp in seconds. Use the lowest practical value for the use of the token. This claim is required.

The payload is then base64url encoded to create the second part of the token.

Signature

To create the signature, the encoded header and payload, along with the secret (provided when the app is created) are combined and signed using the algorithm specified in the header. For example:

var encodedData = base64urlEncode(header) + '.' + base64urlEncode(payload);
HMACSHA256(encodedData, 'secret');

After creating the signature, all three parts are combined to create the Guest Token:

ABC123.DEF456.xd84f342d2

The secret provided when the app is created is base64-encoded. Certain JWT libraries require a decoded secret to generate the token. For example, to sign a token when using the jsonwebtoken NPM package, create a new Buffer to decode the secret when creating the signature:

var jwt = require('jsonwebtoken');

var payload = {
  "sub": "guest-user-7349",
  "name": "Guest User's Display Name",
  "iss": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE"
};

var token = jwt.sign(
  payload,
  Buffer.from('a71939434514ab0823ed06a63fc24715cef62b8d7428866d91037f90d9cce1f3', 'base64'),
  { expiresIn: '1h' }
);

More Resources

JWT.io provides an interactive JWT debugger and a great list of libraries which can be used to generate JSON Web Tokens in different languages. More tools are also available to help generate Guest Tokens.

Using Guest Tokens

Once you've created a Guest Token, you can use it to authenticate as a guest user and interact with Webex Teams users. Several functions in the Webex Teams SDKs can be performed after authenticating with a Guest Token. If you need to use the Webex Teams REST API directly, you'll need to exchange it for an OAuth token. See below for a few examples of using a Guest Token with our SDKs and the Webex Teams REST API.

After a guest user is authenticated, a Webex Teams guest account is created, and they can then perform actions just like regular users. There are a few important differences from regular users to keep in mind:

  • Webex Teams accounts for guest users are created only after authenticating with a Guest Token; accounts cannot be created manually
  • Guest users may only interact with regular users; they cannot interact with other guest users
  • Guest users will not have a valid email address associated with their account—use their individual personId with any activities that require the identification of a specific user

Using with the Browser SDK

Initialize and authenticate with a Guest Token instead of using a grant flow:

// require and initialize the Webex Teams SDK
var CiscoSpark = require('ciscospark');
var spark = CiscoSpark.init();

// wait until the SDK is loaded and ready
spark.once(`ready`, function() {
  if (spark.canAuthorize) {
    // the user is already authenticated
    // proceed with your app logic
  }
  else {
    spark.authorization.requestAccessTokenFromJwt({jwt})
      .then(() => {
        // the user is now authenticated with a JWT
        // proceed with your app logic
      })
  }
});

Using with the iOS SDK

Initialize and authenticate with a Guest Token:

let authenticator = JWTAuthenticator()
let spark = Spark(authenticator: authenticator)

if !authenticator.authorized {
    authenticator.authorizedWith(jwt: myJwt)
}

Exchanging for an OAuth Token

After generating a Guest Token, it needs to be exchanged for an OAuth token for use by your application. To exchange the token, make an HTTP POST to a special endpoint with the Guest Token in the Authentication header:

Example Request

curl --request POST \
  --header "Authorization: Bearer GUEST_ISSUER_TOKEN" \
  https://api.ciscospark.com/v1/jwt/login

You will then receive the OAuth token and an expiration time in seconds:

Example Response

{
  "token": "AUTH_TOKEN",
  "expiresIn": "600"
}

Using the OAuth Token with APIs

Once you have an OAuth token, you can use it with the Webex Teams APIs to perform actions as the guest user. For example, if your guest user is sending messages to Webex Teams users, use the Messages API to send messages to them. The token will include the appropriate scopes for messaging, calling, and people.

Changing the Display Name

To change the display name of a guest user who has already authenticated, simply re-authenticate with a new guest token. Create a new Guest Token and change the name payload claim to the new display name. To ensure that this new Guest Token is associated with the same guest user, use the same unique user identification value for the sub payload claim. After authenticating via the API or with the SDKs with the new Guest Token, the guest user's display name will be updated.