Scoped Tokens for Webex Administrators

A Web application that generates scoped tokens for administrators of Webex Organizations.

The application comes in two flavors:

1. dynamic: let's the admin choose from a list of 'spark-admin' scopes (default mode and illustrated below)
2. static: uses an hard-coded list of admin scopes.

Test the application

Click to live test the dynamic OAuth tokens issuer for Webex admins.

0. Wait for up to 30 seconds for the application to launch, since the app is powered by Heroku free dynos

1. Select a few scopes, and click Start to initiate the OAuth flow.

      

2. If permissions are granted, the application will display newly issued access & refresh tokens to invoke Webex APIs on the user's behalf.

      

Note that:

• this example is configured with a pre-defined Webex OAuth Integration that includes all Webex scopes (except spark:all), and redirects to http://localhost:8080/oauth so that Webex Administrators can quickly generate 'scoped' OAuth access tokens on their local machine.
• for production purpose, you would typically create your own OAuth integration from the Webex for Developers portal. You would also deploy your integration over HTTPS.

To learn more about the implementation details of this Webex OAuth integration, check the DevNet learning lab: Run a Webex Teams Integration locally.

Run the application locally

git clone https://github.com/ObjectIsAdvantag/webex-integration-admin
cd webex-integration-admin
npm install
DEBUG=oauth* node server.js

You're all set, the integration is ready to use.

Open http://localhost:8080 in a Web browser.

Select scopes in the proposed list, and Click the 'Start' button

Customize the scoped tokens

Use the static.js service to launch an application with a pre-defined list of scopes.

To define the list of scopes requested:

• open the .env file and update the SCOPES varialbe,
• or specify custom scopes on the command line

Example to request custom compliance scopes

Run the command below in a bash terminal:

DEBUG=oauth* SCOPES="spark-compliance:rooms_read spark-compliance:teams_read spark-compliance:events_read"  node static.js

Registering your own OAuth Integration

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 see how to create your own Webex integration that we will be running on port 9090 for example.

Go to the Webex for developers portal, click 'Apps', 'add Apps', and then create an integration.

Fill the form fields:

• Name: your app name, such as 'My Awesome App' in the snapshot below,
• Description: these details are not displayed to your app end-users,
• Support email: a valid email address for Webex Spark operations team to reach to you if necessary,
• App Icon: simply pick one of the default icons or upload a 512x512 file. Feel free to use this provided sample for now: https://bit.ly/SparkIntegration-512x512
• Redirect URI: enter 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 lab
• Scopes: select all scopes but spark:all.

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 over HTTPS, and register its public URL rather than your local machine's.

Check the DevNet learning lab: 'Deploy a Webex OAuth Integration' for detailled instructions.

Common error codes

The following errors may be raised as the OAuth flow completes.

invalid_scope: 'No user entitled service in request scopes'

The Webex user can NOT access the requested scopes.

Generally happens when a standard Webex user is requesting 'admin' level scopes.

access_denied

The Webex organisation has configured policies that does not allow this OAuth integration to be executed for the Webex user.

Contact the administrator of the Webex organisation for the user, or use a different Webex account (example: gmail accounts).

More about Webex Integrations

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".