Asymmetric JWT Authorization for Mobile and Web App Assets

Asymmetric JWT Authentication in Webex Connect

Webex Connect supports the use of JWT within the Android, iOS, JavaScript SDK, and Thread APIs. JWT provides additional security by restricting resource access to authorized users.

Webex Connect supports Asymmetric JWT authentication, which allows customers to authenticate Webex Connect Mobile/Web SDK users without sharing a signing secret with Webex Connect.

The customer uploads a public key in the Mobile/Web app asset configuration and keeps the matching private key in their own secure backend.

The customer backend signs a JWT with the customer private key and passes the signed JWT to the SDK. Webex Connect validates the JWT with the public key uploaded on the app asset. After validation succeeds, Webex Connect generates an access token with Webex Connect-owned asset-level keys and returns that token to the SDK. The SDK uses the Webex Connect access token for subsequent communication with the Webex Connect platform until the token expires.

For more information on configuring the public key and JWT settings, see Configuring Asymmetric JWT Authentication in Mobile/Web App Asset. For a general introduction to JWT, visit jwt.io.

Enabling Asymmetric JWT Authentication for Thread APIs

As a security best practice, we recommend that you enable JWT authentication.

For Webex Connect Standalone Tenants

JWT authentication is optional and is not enabled by default.

To use JWT authentication for Thread APIs, send an email to the support team to enable it for your tenant. After the Support team enables it, you must enable the JWT authentication option on the Mobile/Web app asset configuration page.

For existing assets, if JWT authentication is enabled, only the Symmetric option is shown. For all new assets created after the v6.19.0 release, only the Asymmetric option is shown.

Migration from Symmetric JWT authorization to Asymmetric JWT authorization is not supported in this release. To use Asymmetric JWT authorization, create a new Mobile/Web App asset and configure it with the Asymmetric option.

To enable JWT Asymmetric authentication, Webex Org ID is mandatory. For Webex Connect tenants that do not have a Webex Org ID assigned yet, log a request with your account manager to get it generated.

For Cisco Webex Contact Center or Cisco Contact Center Enterprise (CCE) Tenants

JWT is enabled by default, and only the Asymmetric option is available.

Asymmetric JWT is mandatory for Mobile Apps, including Android and iOS.

Asymmetric JWT is currently not supported in the Live Chat Widget.

Authentication Flow

1. The customer generates an RSA key pair.
2. The customer stores the private key in their backend.
3. The customer uploads the public key in the Webex Connect Mobile/Web app asset page after enabling Asymmetric JWT.
4. The Mobile/Web app authenticates the end user with the customer's backend.
5. The customer backend creates a customer JWT with the required claims.
6. The customer backend signs the customer JWT with the customer private key.
7. The SDK sends the signed customer JWT to Webex Connect.
8. Webex Connect validates the JWT signature with the uploaded customer public key.
9. Webex Connect validates the JWT claims.
10. If validation succeeds, Webex Connect generates an access token using the Webex Connect asset-level private key.
11. Webex Connect returns the access token to the SDK.
12. The SDK uses the access token for further communication with Webex Connect until the token expires.

The customer private key is never uploaded to Webex Connect and must never be embedded in the mobile app, web app, or SDK client.

Tokens Used in This Flow

Do not confuse the customer JWT expiry with the Webex Connect access token expiry. The customer controls the customer JWT lifetime through the customer JWT exp claim. Webex Connect controls the access token lifetime through the access token exp claim.

Customer JWT Format

The customer backend creates and signs this JWT with the customer private key. The SDK passes this signed JWT to Webex Connect for validation.

Token Header

Example token header:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "3d10c888f998970e70712bcca8e447fa"
}

Token Payload

Example payload:

{
  "iss": "https://auth-server.acme.com",
  "iat": 1700000000,
  "exp": 1700003600,
  "sub": "a9e9c474-4d9e-4089-ae23-27b9f64f7dc6",
  "appId": "IM912838237",
  "orgId": "003e1749-fe42-4830-891c-fa953065153d",
  "hash": "Q48ZbpJsvKcuBZEF9Yxny3iusCxbK419tK6nk3QFwII="
}

The hash claim binds the user identity to the device identity. Generate it from the user ID and device ID using SHA-256:

SHA256(userId & deviceId)

Use the exact user ID and device ID values expected by the SDK/platform flow. A mismatch causes token validation or subsequent SDK communication to fail.

Webex Connect Access Token

After Webex Connect validates the customer JWT, Webex Connect generates an access token and returns it to the SDK. This token is signed by Webex Connect using the asset-level private key. The SDK uses this access token for subsequent communication with Webex Connect.

Token Header

Example token header:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "f5a847efa6696e05726c06c55ec13228"
}

Token Payload

Example payload:

{
  "jti": "724e17f1-754e-4d62-a20d-ee3a0d89ce32",
  "iss": "https://rtm.imiconnect.co",
  "iat": 1782395506,
  "exp": 1782399106,
  "orgId": "003e1749-fe42-4830-891c-fa953065153d",
  "appId": "IM912838237",
  "userId": "user123",
  "hash": "Q48ZbpJsvKcuBZEF9Yxny3iusCxbK419tK6nk3QFwII="
}

Access Token Expiry

The Webex Connect access token lifetime is configured by the customer in the Mobile/Web app asset page.

By default, the access token lifetime is set to 60 minutes. Customers can configure the lifetime from 5 minutes to 360 minutes. Webex Connect includes the configured expiry in the exp claim of the access token payload.

In the example above:

exp - iat = 1782399106 - 1782395506 = 3600 seconds

This means the example access token is valid for 3600 seconds, or 60 minutes.

When the access token expires, the SDK must obtain a new valid access token before continuing protected communication with Webex Connect. Depending on the SDK flow and session state, the app may need to request a fresh customer JWT from the customer backend and repeat the authentication flow.

Key Rotation

Rotate customer signing keys carefully to avoid breaking active users:

1. Generate a new customer key pair.
2. Upload the new public key in the Mobile/Web app asset configuration.
3. Start signing new customer JWTs with the new private key.
4. Keep the old public key available until all JWTs signed with the old private key have expired.
5. Remove the old public key only after the old JWTs can no longer be accepted.

If only one public key can be active on the asset page, schedule rotation during a maintenance window and keep customer JWT lifetimes short before the rotation.

JWT Validation Errors

If an SDK method call fails because of a JWT validation error, an exception is generated with one of the following error codes:

Security Recommendations

• Generate customer JWTs only on the customer's backend.
• Never store the customer private key in a mobile app, web app, or client-side SDK code.
• Store the private key in a KMS, HSM, vault, or backend secret manager.
• Include exp in every production customer JWT.
• Use short-lived customer JWTs.
• Upload only the public key to Webex Connect.
• Rotate keys periodically and immediately if a private key may be compromised.