Skip to content

Commit 6ca21fa

Browse files
adamweeksadamweeks
authored
Merge pull request #61 from webex/playbook/wxcc-token-java-sample
Add wxcc-token-java-sample playbook (Java OAuth2, WxCC token)
2 parents 0561595 + fd6e044 commit 6ca21fa

23 files changed

Lines changed: 1084 additions & 0 deletions

‎playbooks/wxcc-token-java-sample/APPHUB.yaml‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# APPHUB.yaml — Playbook metadata for Webex App Hub
2+
# Copy this file into your Playbook folder under playbooks/<tool-slug>/
3+
# Fill in all required fields. See CONTRIBUTING.md for field rules.
4+
5+
# -----------------------------------------------------------------------------
6+
# friendly_id — Unique identifier. Must end with -playbook (e.g. epic-ehr-playbook)
7+
# -----------------------------------------------------------------------------
8+
friendly_id: "wxcc-token-java-sample-playbook"
9+
10+
# -----------------------------------------------------------------------------
11+
# title — Display name for the Playbook (matches ContentStack field)
12+
# -----------------------------------------------------------------------------
13+
title: "Webex Contact Center — Java OAuth token sample"
14+
15+
# -----------------------------------------------------------------------------
16+
# tag_line — Short tagline for App Hub detail page (required, max 128 chars)
17+
# -----------------------------------------------------------------------------
18+
tag_line: "Java OAuth2 for WxCC: self-contained token for Flow Builder, WxCC APIs—inspect at /userinfo"
19+
20+
# -----------------------------------------------------------------------------
21+
# description — App Hub listing / detail copy (Markdown supported for formatting)
22+
# -----------------------------------------------------------------------------
23+
description: |
24+
A **Java / Spring Boot** sample that completes the **OAuth 2.0 authorization code**
25+
flow against Webex, exchanges the code for tokens using the parameters WxCC expects,
26+
and exposes the result for quick API testing.
27+
28+
**Why use this playbook**
29+
30+
- **Avoid guesswork on token shape:** Webex Contact Center APIs often need a
31+
**self-contained** access token. The sample adds the right token-exchange
32+
parameters so you are not debugging opaque 401s before your first successful call.
33+
- **Working reference in your stack:** If your team ships on **Java 17** and
34+
**Spring Security OAuth2**, you can copy patterns (client config, redirect URI,
35+
session-backed login) instead of translating from another language or framework.
36+
- **Fast path to a testable token:** After login, call **`/userinfo`** to see
37+
claims and copy a **Bearer** token into Postman, curl, **Webex Contact Center
38+
Flow Builder** HTTP activities, or your own middleware—useful when you are
39+
validating scopes, org entitlements, or WxCC endpoints inside real contact-center
40+
flows.
41+
- **Secrets stay out of source:** Client ID and secret are loaded from **environment
42+
variables**, aligning with how you will configure staging and production apps.
43+
44+
**What it does**
45+
46+
- Redirects the browser to Webex for sign-in, handles the callback, and stores
47+
the session server-side.
48+
- Performs token exchange with **`self_contained_token=true`** where applicable.
49+
- Serves a small static UI after login and a **`GET /userinfo`** JSON endpoint for
50+
inspection and tooling.
51+
52+
**Contact center (not generic OAuth)**
53+
54+
- Tokens from this sample are intended for **Webex Contact Center** scenarios:
55+
calling **WxCC REST/GraphQL** APIs and supplying **`Authorization: Bearer`**
56+
from **Flow Builder** or other automation that runs in your CC deployment.
57+
- **`product_types: contact_center`** reflects that focus: same OAuth stack as
58+
broader Webex, but scope defaults and token exchange match WxCC integration
59+
patterns from the official WxCC samples.
60+
61+
# -----------------------------------------------------------------------------
62+
# product_types — Where this Playbook appears. Pick one or more.
63+
# Valid: teams | meetings | calling | rooms | contact_center
64+
# -----------------------------------------------------------------------------
65+
product_types:
66+
- "contact_center"
67+
68+
# -----------------------------------------------------------------------------
69+
# app_context — Where the integration runs. Pick one or more.
70+
# Valid: space | in_meeting | call | device | contact_center | sidebar | mcp | a2a
71+
# -----------------------------------------------------------------------------
72+
app_context:
73+
- "contact_center"
74+
75+
# -----------------------------------------------------------------------------
76+
# categories — App Hub category slugs. Pick one or more.
77+
# Verticals: healthcare | financial-services | retail-ecommerce
78+
# App categories (use kebab-case slugs):
79+
# ai-agent-testing-observability | agent-supervisor-tools | analytics |
80+
# calendar-scheduling | collaboration-management | customer-relations |
81+
# customer-support | developer-tools | doc-management | education |
82+
# finance | government | healthcare | human-resources | internet-of-things |
83+
# marketing-sales | orchestration | platform | productivity |
84+
# project-management | recording-transcriptions | security-compliance |
85+
# self-service-bots | social-and-fun | strategy-team-planning |
86+
# workflow-automation | workforce-optimization | other
87+
# -----------------------------------------------------------------------------
88+
categories:
89+
- "developer-tools"
90+
- "security-compliance"
91+
92+
# -----------------------------------------------------------------------------
93+
# company_name — Your company or team name
94+
# -----------------------------------------------------------------------------
95+
company_name: "Webex for Developers"
96+
97+
# -----------------------------------------------------------------------------
98+
# company_url — Your company or project URL
99+
# -----------------------------------------------------------------------------
100+
company_url: "https://developer.webex.com"
101+
102+
# -----------------------------------------------------------------------------
103+
# support_url — Issues or support link (e.g. GitHub issues)
104+
# -----------------------------------------------------------------------------
105+
support_url: "https://github.com/webex/WebexPlaybooks/issues"
106+
107+
# -----------------------------------------------------------------------------
108+
# product_url — Link to this Playbook in the repo (required)
109+
# -----------------------------------------------------------------------------
110+
product_url: "https://github.com/webex/WebexPlaybooks/tree/main/playbooks/wxcc-token-java-sample"
111+
112+
# -----------------------------------------------------------------------------
113+
# logo — (Optional) URL to your logo image. If not provided, defaults to the
114+
# standard Webex Playbook logo.
115+
# -----------------------------------------------------------------------------
116+
logo: "https://images.contentstack.io/v3/assets/bltd14fd2a03236233f/blta2de9daa773c6604/60f71f81e2de935fc7e35dbe/download"
117+
118+
# -----------------------------------------------------------------------------
119+
# estimated_implementation_time — e.g. "2-4 hours", "1 day"
120+
# -----------------------------------------------------------------------------
121+
estimated_implementation_time: "2-4 hours"
122+
123+
# -----------------------------------------------------------------------------
124+
# third_party_tool — (Optional) The tool being integrated (e.g. Salesforce, Epic)
125+
# Omit for generic playbooks (e.g. "any CMS")
126+
# -----------------------------------------------------------------------------
127+
128+
# -----------------------------------------------------------------------------
129+
# privacy_url — Privacy policy URL (required; use Cisco default for Webex-authored)
130+
# -----------------------------------------------------------------------------
131+
privacy_url: "https://www.cisco.com/c/en/us/about/legal/privacy-full.html"
132+
133+
# -----------------------------------------------------------------------------
134+
# submission_date — (Optional) ISO date (e.g. 2025-03-01)
135+
# -----------------------------------------------------------------------------
136+
submission_date: "2026-04-01"

‎playbooks/wxcc-token-java-sample/README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Webex Contact Center — Java OAuth token sample
2+
3+
This Playbook is adapted from the [token-java-sample](https://github.com/WebexSamples/webex-contact-center-api-samples/tree/main/token-management-samples/token-java-sample) in the WebexSamples `webex-contact-center-api-samples` repository on GitHub.
4+
5+
## Use Case Overview
6+
7+
Developers building Webex Contact Center integrations need a working OAuth2 authorization code flow before they can call WxCC REST or GraphQL APIs. This Playbook packages a small Spring Boot application that logs a user in through Webex, exchanges the code for an access token (including the `self_contained_token` parameter required for WxCC-style tokens), and exposes the token and user claims in JSON for inspection. **That access token is what you use as a WxCC-facing credential:** paste it into API clients, middleware, or **Flow Builder** activities that call outbound HTTP with a `Bearer` header, so you can exercise real contact-center flows and configuration APIs—not only generic Webex OAuth. The target persona is a **developer** or **integration engineer** familiar with Java. Expect roughly **2–4 hours** to register an integration, configure redirect URIs, run the app locally, and validate a successful login.
8+
9+
## Architecture
10+
11+
The browser talks only to the Spring Boot app on localhost. The app redirects the user to Webex for authorization, receives the authorization code on the registered redirect URI, exchanges it for tokens at Webex token endpoint, and stores the session server-side. A functional route returns user profile fields and a `Bearer` access token for copying into API tools. Authentication never embeds secrets in the browser; client credentials are supplied through environment variables at process start.
12+
13+
See the sequence diagram in [diagrams/architecture-diagram.md](diagrams/architecture-diagram.md) for the full flow.
14+
15+
## Using the token with Webex Contact Center
16+
17+
- **WxCC REST and GraphQL:** Use the Bearer token from `/userinfo` as `Authorization: Bearer <token>` when calling documented WxCC APIs, subject to the scopes granted on your integration and entitlements in your org.
18+
- **Flow Builder and automations:** In **Webex Contact Center Flow Builder**, any activity that lets you set HTTP headers (for example outbound **HTTP Request**-style steps or custom integration points) can use the same Bearer value while you prototype how a flow calls external services or WxCC endpoints. Replace hand-copied tokens in production with a proper token service and rotation.
19+
- **Why “contact center” on App Hub:** The sample is sourced from the WxCC API samples repo, requests **`cjp:*`** scopes used for contact-center configuration and user context, and exchanges tokens the way WxCC integrations expect—so it is catalogued under **contact center** rather than as a generic Teams-only OAuth demo.
20+
21+
## Prerequisites
22+
23+
- **Webex:** A Webex account with access to create integrations at [Webex for Developers — My Apps](https://developer.webex.com/my-apps). Scopes used by the sample align with WxCC admin-style access (`cjp:user`, `spark:people_read`, `cjp:config*`). Adjust scopes in configuration only if your integration’s allowed scopes differ.
24+
- **Redirect URI:** Register exactly the redirect URI you will use (default `http://localhost:8080/login/oauth2/code/webexcc`) on the integration. If you change host, port, or path, set `WXCC_OAUTH_REDIRECT_URI` and update the integration to match.
25+
- **Runtime:** **Java 17** and a network path to Maven Central (Gradle downloads dependencies on first run).
26+
- **Repository:** This playbook’s code lives under `src/` relative to this folder (Gradle project root).
27+
28+
Additional upstream notes (video link, support links, license) are in [docs/upstream-overview.md](docs/upstream-overview.md).
29+
30+
## Code Scaffold
31+
32+
The Gradle project under [src/](src/) (playbook code folder) follows the usual Gradle layout: Java and resources live under **`src/main/`** inside that directory (i.e. `playbooks/<slug>/src/src/main/java` and `.../src/main/resources` from the repo root).
33+
34+
- `src/main/java/.../WebexccApplication.java` — Spring Boot entrypoint.
35+
- `src/main/java/.../OAuth2SecurityConfig.java` — OAuth2 login, logout, and custom token request that adds `self_contained_token=true`.
36+
- `src/main/java/.../RequestRouter.java` — `GET /userinfo` returning `UserInfo` JSON including the access token.
37+
- `src/main/resources/application.yaml` — OAuth client and provider endpoints; **client ID and secret are read from environment variables** (see [src/env.template](src/env.template)).
38+
- Static UI under `src/main/resources/static/` for post-login pages.
39+
40+
The sample does **not** implement refresh tokens, encrypted token storage, multi-tenant routing, or production security headers. Treat it as instructional code only.
41+
42+
## Deployment Guide
43+
44+
1. **Create a Webex integration** at [Webex for Developers — My Apps](https://developer.webex.com/my-apps):
45+
46+
- Choose **Create a New App** → **Create an Integration** (OAuth 2.0 authorization code flow).
47+
- Give the app a name and description; the **Redirect URI** must include exactly the callback you will use locally. Default for this sample: `http://localhost:8080/login/oauth2/code/webexcc`. If you use another host, port, or path, register that URI instead and set **`WXCC_OAUTH_REDIRECT_URI`** to the same value when you run the app.
48+
- Under **Scopes**, select the OAuth scopes the sample will request. The defaults in [src/src/main/resources/application.yaml](src/src/main/resources/application.yaml) match the upstream WxCC token sample. Enable these on the integration (or a superset of them):
49+
50+
| Scope | Role in this sample |
51+
| ----- | ------------------- |
52+
| `cjp:user` | WxCC user / session context for Contact Center APIs. |
53+
| `spark:people_read` | Lets Webex return the signed-in user for `GET https://webexapis.com/v1/people/me` during the OAuth user-info step. |
54+
| `cjp:config` | Base WxCC configuration access (grouped scope in the developer portal). |
55+
| `cjp:config_read` | Read WxCC configuration. |
56+
| `cjp:config_write` | Write WxCC configuration (included for parity with typical admin-style samples). |
57+
58+
The app sends them as a single comma-separated list (no spaces), same as **`WXCC_OAUTH_SCOPE`** in [src/env.template](src/env.template). If your integration exposes fewer scopes, remove the extras from the integration **and** set `WXCC_OAUTH_SCOPE` to a comma-separated subset that is allowed for your app; otherwise authorization will fail with a scope mismatch.
59+
60+
- Save the integration and copy the **Client ID** and **Client Secret** (secret is shown once—store it securely).
61+
62+
2. Open a terminal and change to the Gradle project directory: `cd playbooks/wxcc-token-java-sample/src` (adjust the prefix if your clone path differs).
63+
64+
3. Copy [src/env.template](src/env.template) into your shell or IDE run configuration. Set **`WXCC_OAUTH_CLIENT_ID`** and **`WXCC_OAUTH_CLIENT_SECRET`** from the integration. Leave other variables unset to use documented defaults unless you changed redirect URI or scopes above.
65+
66+
4. Confirm the integration’s redirect URI matches `WXCC_OAUTH_REDIRECT_URI` (default `http://localhost:8080/login/oauth2/code/webexcc`).
67+
68+
5. Run `./gradlew bootRun` (Windows: `gradlew.bat bootRun`). Wait until the app reports that it is listening (default port **8080**, overridable with `SERVER_PORT`).
69+
70+
6. Open `http://localhost:8080` in a browser, complete the Webex login, and confirm you reach the static success page.
71+
72+
7. Open `http://localhost:8080/userinfo` to view JSON with user attributes and a `Bearer` access token suitable for testing WxCC APIs.
73+
74+
## Known Limitations
75+
76+
- **Sample only:** Upstream disclaimer applies — not a production security or token-lifecycle design. See [docs/upstream-overview.md](docs/upstream-overview.md) for the original support and video links.
77+
- **Session and tokens:** Access tokens are tied to the servlet session; restarting the app or clearing cookies requires re-authentication. No automatic refresh.
78+
- **Scopes and org:** You must use an integration and user that are entitled to the configured scopes in your org.
79+
- **License:** This Playbook is covered by the Webex Playbooks repository [LICENSE](../../LICENSE). Upstream Java sources are under the Cisco sample license described in [docs/upstream-overview.md](docs/upstream-overview.md).
80+
81+
This Playbook is provided as a starting point. Webex does not guarantee the functional accuracy of the source code. Test thoroughly before use in a production environment.

‎playbooks/wxcc-token-java-sample/diagrams/architecture-diagram.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Architecture — WxCC Java OAuth token sample
2+
3+
OAuth2 authorization code flow for a browser user against Webex APIs, with the access token exposed for API experimentation.
4+
5+
```mermaid
6+
sequenceDiagram
7+
participant User as Browser
8+
participant App as SpringBootApp
9+
participant Webex as WebexOAuth
10+
11+
User->>App: GET /
12+
App->>User: Redirect to login
13+
User->>Webex: Authorize (Webex identity)
14+
Webex->>User: Redirect with auth code
15+
User->>App: GET login/oauth2/code/webexcc
16+
App->>Webex: POST access_token (code plus self_contained_token)
17+
Webex->>App: Access token
18+
App->>User: Session established, redirect to index
19+
User->>App: GET /userinfo
20+
App->>User: JSON user claims and Bearer token
21+
```
22+
23+
For narrative context, see the **Architecture** section in [README.md](../README.md).

‎playbooks/wxcc-token-java-sample/docs/upstream-overview.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Upstream sample notes
2+
3+
Material from the [token-java-sample](https://github.com/WebexSamples/webex-contact-center-api-samples/tree/main/token-management-samples/token-java-sample) README in the WebexSamples `webex-contact-center-api-samples` repository, kept here so we do not add a second `README.md` under `src/`.
4+
5+
## Purpose
6+
7+
The upstream sample is a minimal Spring Boot application that uses Spring Security OAuth2 client to perform an authorization code login against Webex APIs and obtain an access token suitable for Webex Contact Center API calls.
8+
9+
## Video
10+
11+
The upstream README links to a [Vidcast walkthrough](https://app.vidcast.io/share/5c1c16ab-1d3a-4623-b1ea-68bc2fbb19a3) of the basic authorization flow.
12+
13+
## Screenshot reference
14+
15+
The upstream README references `./images/basic-authorization-sample.png`; that asset lives in the upstream tree only. Clone the monorepo if you need the image file locally.
16+
17+
## Support and community
18+
19+
- [Webex Contact Center Developer Support](https://developer.webex.com/explore/support)
20+
- [Webex Contact Center APIs Developer Community](https://community.cisco.com/t5/contact-center/bd-p/j-disc-dev-contact-center)
21+
22+
## License
23+
24+
Upstream sample code is distributed under the **CISCO SAMPLE CODE LICENSE** in the [monorepo](https://github.com/WebexSamples/webex-contact-center-api-samples). This Playbook’s documentation and layout are covered by the Webex Playbooks repository [LICENSE](../../../LICENSE).

‎playbooks/wxcc-token-java-sample/src/.gitignore‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
HELP.md
2+
.gradle
3+
build/
4+
!gradle/wrapper/gradle-wrapper.jar
5+
!**/src/main/**/build/
6+
!**/src/test/**/build/
7+
8+
### STS ###
9+
.apt_generated
10+
.classpath
11+
.factorypath
12+
.project
13+
.settings
14+
.springBeans
15+
.sts4-cache
16+
bin/
17+
!**/src/main/**/bin/
18+
!**/src/test/**/bin/
19+
20+
### IntelliJ IDEA ###
21+
.idea
22+
*.iws
23+
*.iml
24+
*.ipr
25+
out/
26+
!**/src/main/**/out/
27+
!**/src/test/**/out/
28+
29+
### NetBeans ###
30+
/nbproject/private/
31+
/nbbuild/
32+
/dist/
33+
/nbdist/
34+
/.nb-gradle/
35+
36+
### VS Code ###
37+
.vscode/

0 commit comments

Comments
 (0)