This Webex Integration example illustrates an OAuth Grant flow at the end of which the Webex Teams user who granted permission will see his fullname displayed.
This code sample comes as a companion to the DevNet learning lab: Run a Webex Teams Integration locally.
This example leverages a pre-registered Webex OAuth Integration with a Redirect URL on localhost so that it can be run with minimal setup.
The flow initiates at http://localhost:8080/, and the provided Webex Application's Oauth Flow redirects to http://localhost:8080/oauth
For production purpose, you will register and deploy the integration on a public URL. Please check the guide to register your own integration.
Then open the .env
file and place your OAuth integration settings: CLIENT_ID, CLIENT_SECRET.
Also, place the set of scopes you want your integration to request.
Your integration is all set.
Note that thanks to Glitch 'PROJECT_DOMAIN' env variable, you do not need to customize the REDIRECT_URI env variable to point to your app domain.
git clone https://github.com/CiscoDevNet/webex-integration-sample cd webex-integration-sample npm install DEBUG=oauth* node server.js
You're all set, the integration sample is live!
Let's go through the OAuth flow.
Reach to the integration home page from a Web browser: open http://localhost:8080:
Click Start, enter your Webex Teams email and click accept (or decline):
If you accepted, the integration you're running locally just got issued a "Webex Teams API access token" so that the code sample can now act on your behalf, and with the set of permissions you provided.
The integration custom code logic uses the provided token to request your Webex Teams account details (GET /people/me) and displays your full name.
To learn more about Webex Integrations, read the reference documentation.
In the example above, we were running a pre-registered OAuth integration running on port 8080.
Let's now register a new Webex integration that we will be running on port 9090.
Go to the Webex for developers portal, click 'Apps', 'add Apps', and then create an integration.
Fill the form fields:
http://localhost:9090/oauth
since this is the URL at which the provided code sample will be listening on your local machine. More to come in the next steps if this labspark:people_read
and spark:rooms_read
scopes.Note the list of scopes you selected corresponds to the maximum set of scopes that your integration will be entitled to ask for. However, from code, your integration can dynamically refine the set of scopes asked for in order to comply with the real needs of your application. A good practice is to start small and extend the set of scopes asked for as the end-users gain trust in your app and is ready to ask more advanced features.
Click save, and look for your integration client id
and client secret
.
Let's now configure the integration: you can either paste your integration client id and secret into the code, or set these as env variables on the command line.
Instructions for Mac, Linux and Windows bash users
open a terminal
on a single command line, type:
DEBUG=oauth* PORT=9090 REDIRECT_URI="http://localhost:9090/oauth" CLIENT_ID="YOUR_INTEGRATION_ID" CLIENT_SECRET="YOUR_INTEGRATION_SECRET" node server.js
Instructions for Windows command shell users
open a command shell
enter the commands below:
set DEBUG="oauth*" set PORT=9090 set REDIRECT_URI="http://localhost:9090/oauth" set CLIENT_ID="YOUR_INTEGRATION_ID" set CLIENT_SECRET="YOUR_INTEGRATION_SECRET" node server.js
You're all set. Restart your integration, and give it a try: http://localhost:9090
This step by step guide explained how to register a Webex Integration running on a local developer environment.
In the real-world, you will want to deploy your integration, and register its public URL rather than your local machine's.
Check the DevNet learning lab: 'Deploy a Webex OAuth Integration' for detailled instructions.
Now that you know the basics about Webex Integrations, you can leverage not only REST API Resources but also the full set of Webex Teams SDKs and Widgets.
To experiment with the Webex Teams Widget, simply launch the widget.js
sample with 2 environment variables:
Once granted authorization to open the widget, the sample will add the user to a demo space, and display the 'Space' Widget.
Note that the OAuth list of scopes has been changed to spark:all
as required by the 'Space' Widget. To successfully run this sample, open the Webex for Developers portal, and change the list of scopes that can be requested by your OAuth Integration to spark:all
BOT_TOKEN=<your-token> SPACE_ID=<demo-space> node widget.js
Webex Integrations are a way for your apps to request permission to invoke the Webex APIs on behalf of Webex Teams users.
The process used to request permission is called an OAuth Grant Flow, and is documented in the Integrations guide.
You can experiment the flow in DevNet Learning lab "Understand the OAuth Grant flow of Webex Teams Integrations".
Owner
Contributors
Categories
Products
WebexProgramming Languages
JavaScriptLicense
Code Exchange Community
Get help, share code, and collaborate with other developers in the Code Exchange community.View Community