OAuth 2.0 Web Service Auth Accounts

TeamDynamix Version 9.5 introduces a new feature to workflow web services: OAuth 2.0 authentication accounts. This includes out-of-the-box support for Google and Microsoft OAuth 2.0, but can also be configured for generic OAuth 2.0 enabled services.

This article will walk you through configuring an auth account using OAuth 2.0. For a specific example of setting up OAuth 2.0, please see Creating a Workflow Web Service Method that Uses Google OAuth 2.0.
 

Important note: At this time, TeamDynamix only supports OAuth 2.0 for services with authorization servers that provide refresh tokens. This is because without a refresh token, there's no way for TeamDynamix to automatically refresh an expired access token after the auth account has been configured.

Registering an Application

In order to start using OAuth 2.0, you'll first need to create and register an application with the desired service. This process is different for every service, but will typically involve providing basic information like an application name, company logo, etc. You'll also need to authorize a redirect URI for TeamDynamix. When prompted, you must provide the TeamDynamix redirect URI, which is [TeamDynamix Base URL]/TDAdmin/OAuth/Callback.

For example, if your TeamDynamix base URL is https://abuniversity.teamdynamix.com, then the redirect URI you need to register will be:
https://abuniversity.teamdynamix.com/TDAdmin/OAuth/Callback

Additionally, some services may also require that you authorize Javascript origins. In that case, you'll need to provide your TeamDynamix base URL, which would be https://abuniversity.teamdynamix.com from the previous example.

For more detailed information about registering an application with Google, see Google's documentation.
For more detailed information about registering an application with Microsoft, see Microsoft's documentation.

Make sure to take note of your application's Client ID and Client Secret, as you'll need those pieces of information later on in the configuration process.
 

Creating the Auth Account

The first step is to log into Admin and create a new auth account. You can do so by navigating to the Web Service Auth Accounts page for a particular ticketing application and clicking the New button.
 

Admin  >  Applications  >  [Application Name]  >  Web Service Auth Accounts  >  New

Once you've arrived at the page, begin filling out the Name, Account Type, and Description fields. In the Account Type dropdown, you'll see three options pertaining to OAuth 2.0.

  1. Generic OAuth 2.0
  2. Google OAuth 2.0
  3. Microsoft OAuth 2.0

New OAuth Account

If you're building a web service call to Google or Microsoft, you should select the appropriate type. While you can build auth accounts for these services through a Generic OAuth 2.0 account, selecting one of those two options will require you to enter less information to get your account configured.

At this point you'll notice a handful of OAuth specific fields which you'll need to provide. Each of those fields is discussed in detail below.


Authorization Endpoint

This is the URI for the endpoint on the authorization server used to obtain authorization. If you are using a Google or Microsoft account type, you will not need to provide this field. For any other service, you'll need to enter the endpoint provided by that service.

For example, Google's OAuth 2.0 authorization endpoint is:
https://accounts.google.com/o/oauth2/v2/auth

TeamDynamix will automatically append the query string parameters required by the OAuth 2.0 specification when you go to generate an access token. Some of the values for these parameters will be taken from the information you provide while configuring the account, while others are simply provided by TeamDynamix. These parameters include the following.

  • access_type
  • client_id
  • origin
  • prompt
  • redirect_uri
  • response_type
  • scope
  • state

If your authorization server requires additional parameters, they can be added to the end of your authorization endpoint. For example, Google's authorization endpoint supports an optional login_hint parameter that you can provide.

To supply this parameter, you would simply enter the authorization endpoint as shown below:
https://accounts.google.com/o/oauth2/v2/auth?login_hint=myemail@gmail.com

You can also supply multiple parameters in this way by using an ampersand character (&) to delimit them. For example, Google supports an additional parameter called include_granted_scopes. You could supply both the login_hint and include_granted_scopes parameters as follows:

https://accounts.google.com/o/oauth2/v2/auth?login_hint=myemail@gmail.com&include_granted_scopes=true
 

Token Endpoint

This is the URI for the endpoint on the authorization server used to exchange an authorization grant for an access token. Just like with the Authorization Endpoint, you will not need to supply this field for Google or Microsoft accounts. This endpoint should also be provided to you by the service against which you are authenticating.

For example, Google's OAuth 2.0 Token Endpoint is:
https://www.googleapis.com/oauth2/v4/token


Client ID

This is the string representing the public registration information provided by your client application. You should receive a Client ID when you register your application.


Client Secret

This is the string representing the confidential secret provided by your client application. Depending on your application, you will typically receive a Client Secret alongside your Client ID when registering your application. If your application provided you with a client secret, you must provide it here.
 

Scope

This specifies the scope of the access request. The value is expressed as a list of space-delimited, case-sensitive strings identified by the authorization server. You will need to determine which permissions you will need to make your web service call and specify them here.

For example, let's say I'm trying to build a web service method that writes to a Google sheet. You can see from the Google's scope documentation that you'll need to provide the https://www.googleapis.com/auth/spreadsheets scope in order to authorize that access.

Note that for Microsoft accounts, offline_access will automatically be appended to the scope, as that is required by TeamDynamix.
 

Generating an Access Token

Once you've provided all of the above fields, you're ready to generate an access token. Simply click on the Generate button beside the Access Token field to visit the OAuth 2.0 authorization endpoint where you will be prompted for your credentials in the external system and authorize access for the provided scopes. Once you've successfully authorized the application, you should see a message indicating that the access token was generated successfully. A this point, your account has been configured successfully and you can now activate it by checking the Active checkbox and clicking the Save button.Generating Access and Refresh Tokens
 

NOTE: To ensure that your web service methods succeed, you will need to generate the tokens by logging in with a user who has permission to perform any of the desired web service method actions.

Calling a Web Service Method Using an OAuth 2.0 Auth Account

Now that you've configured your OAuth 2.0 web service auth account, it's time to put it to work! Start by navigating to the Web Service Methods page and clicking the New button.
 

Admin  > Applications  >  [Application Name]  >  Web Service Methods  >  New

Please see this article for building web service methods. Once you have the method built out, select your new OAuth 2.0 auth account as the account for Authorization, and test your method out using the Test Request button. You can now include calls to this method in your workflow as you see fit!
 

Refreshing Access Tokens

When you generate an access token, that token will only be valid for a set amount of time (usually an hour) before it expires. This is why the authorization server will also supply something called a refresh token along side the access token. TeamDynamix captures this refresh token and uses it to generate a new access token automatically when the old one expires. You don't need to configure anything for this to work, TeamDynamix will simply take care of refreshing your access tokens for you.

Revoking OAuth Access

It is possible for OAuth access to be revoked from outside of TeamDynamix. This happens when you explicitly choose to revoke access to the service you're using. Should that happen, all web service calls using the auth account will fail with a status code of 401 (unauthorized) from that point onward. Any such web service call (including those used in workflow web service steps) will be recorded as unsuccessful, and you can see that reflected in the Workflow Web Service Logs in Admin. In order to make those calls succeed again, you'll need to reconfigure the auth account and generate new access and refresh tokens for it.

Details

Article ID: 20961
Created
Tue 12/6/16 3:18 PM
Modified
Wed 7/29/20 4:33 PM