Guest Issuer

Guest Issuer applications give guest users temporary access to users within your organization.

Create a Guest Issuer

anchorOverview
anchor

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 REST API. These tokens are exchanged for an access 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.

anchorGuest Issuer App
anchor

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.

anchorGenerating Guest Tokens
anchor

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 REST 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:

ClaimValue
typThe type of token. Must be JWT.
algThe 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 REST API expects the following claims:

ClaimValue
subThe subject of the token. This is your unique and public identifier for the guest user. This claim may contain only letters, numbers, and hyphens. This claim is required.
nameThe display name of the guest user. This will be the name shown in Webex Teams clients.
issThe issuer of the token. Use the Guest Issuer ID provided in My Webex Teams Apps. This claim is required.
expThe expiration time of the token, as a UNIX timestamp in seconds. Use the lowest practical value for the use of the token. This is not the expiration time for the guest user's session. 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.

anchorUsing Guest Tokens
anchor

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 SDKs can be performed after authenticating with a guest token. If you need to use the Webex REST API directly, you'll need to exchange it for an access token. See below for a few examples of using a guest token with our SDKs and the 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

When using guest tokens with the SDKs and Widgets, session management is handled automatically. If the guest token is exchanged for an access token, your application will need to handle guest user sessions. See Using the Access Token below for more information.

Using with the Browser SDK

The Browser SDK accepts guest tokens when authorizing a user. To initialize and authenticate with a guest token instead of using a grant flow, use the requestAccessTokenFromJwt function. The function's input is an object with a property of "jwt" that's set to a valid guest token. For example, {jwt: "your.guest.token.here"}. This function exchanges the guest token for an access token and authenticates the session using that access token.

var CiscoSpark = require('ciscospark');
var spark = CiscoSpark.init();

var token = 'your.guest.token.here';
// wait until the SDK is loaded and ready
spark.once(`ready`, function() {
    spark.authorization.requestAccessTokenFromJwt({jwt: token})
      .then(() => {
        // the user is now authenticated with a guest token (JWT)
        // proceed with your app logic
      })
});
Using with the iOS SDK

To initialize and authenticate the iOS SDK with a guest token, provide it as a parameter when authorizing the user:

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

if !authenticator.authorized {
    authenticator.authorizedWith(jwt: myJwt)
}
Using with the Widgets

To use the Widgets with a guest token, simply instantiate the widgets with guest token. For example, here's how you would use a guest token with the Space Widget:

var widgetEl = document.getElementById('my-webexteams-widget');
// Init a new widget
ciscospark.widget(widgetEl).spaceWidget({
  guestToken: 'GUEST_TOKEN',
  destinationId: 'SPACE_ID',
  destinationType: 'spaceId'
});

To quickly test a guest token with the widgets, use the Widgets Demo.

Exchanging for an Access Token

The SDKs handle the guest token exchange and authentication for you, but if you aren't using an SDK, or need more control over the authentication process, you can use the REST API to exchange a guest token for an access token. You can then use the access token to make API requests like you would with a bot token or integration token.

To exchange the guest token for an access 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_TOKEN" \
  https://api.ciscospark.com/v1/jwt/login

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

Example Response
{
  "token": "ACCESS_TOKEN",
  "expiresIn": "21599"
}

The access token will be valid for six hours. The expiration (exp) claim in the guest token will not affect this expiration time.

Using the Access Token

Once you have an access token, you can use it with the Webex REST API 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.

When using access tokens, your application will need to manage guest user sessions. A refresh token is not provided after exchanging the guest token for an access token. If a session needs to continue past the expiration time of the access token, create a new guest token for the user and exchange it for a new access token.

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.

Last updated: December 4, 2018