OAuth 2.0 Web Service Auth Accounts

This introduction article will help Ticketing Admins to configure Web Service Auth Accounts in the Ticketing application. The user must have the permission to be global or ticketing application administrator.

Overview

This article will explore how to create a Web Service Auth Account for using Web Services throughout TeamDynamix workflows in Ticketing.

Where to Find This

This feature appears in the TDAdmin interfaces.

TDAdmin is where the Web Service Auth Account in the ticketing application. If you do not have an account dedicated to the Web Services, please see this KB Article on Creating A Service Account.

Navigate to creating a Web Service Auth Account following these paths:

• TDAdmin > Applications > Ticketing Application > Workflow Web Services

Using Web Service Auth Accounts

OAuth 2.0 Web Service Auth Accounts

TeamDynamix workflow web services 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

First, log into Admin and create a new auth account:

1. In TDAdmin, click Applications in the left navigation.
2. Click the desired Application Name.  
3. In the ticketing application, go to Workflow Web Services > Web Service Auth Accounts
4. Click the New button.

Now, on the Auth Account screen, 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
   

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.

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.

1. 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. At this point, your account has been configured successfully and you can now activate it by checking the Active checkbox and clicking the Save button.

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.

1. In TDAdmin, click Applications in the left navigation.
2. Click the desired Application Name.  
3. In the ticketing application, go to Workflow Web Services > Web Service Auth Accounts
4. Click the New button.

Please see this web service step 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 alongside 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.

Registering TeamDynamix with Windows Live

This article is intended to give you the information you will need to register TeamDynamix with Windows Live so that you can make OAuth 2.0 calls to Microsoft products through web service workflows. You must register TeamDynamix with Microsoft® as an application and receive a client ID for use with the service. Only a person who has a valid Windows Live ID can register an application and obtain a client ID. After you create the application, you can sign in and change it whenever you want.

Registering Your Application

The Windows Live application management site assists you with the registration process, issues your client ID to you, and provides a place where you can continue to manage all the applications you register.

Getting Your Client ID

To complete the integration of your application with Windows Live, you must specify additional settings and publish your application. Click the Essentials link under the box that displays your client ID and secret key.

Whenever you want to retrieve or change your application data, return to the Windows Live application management site. Sign in with the Windows Live ID account that you used during registration to see and manage your application projects.

To get your client ID:

1. Go to the Windows Live application management site.
2. Sign in by using your Windows Live ID.

Important note: If this is your first visit to this site, you will see several pages that configure your Windows Live ID for use with the site.

3. Click Add an application.
4. Provide the following information in the form on the Connect your application to Windows Live page. 
   • Application name. A unique and friendly name that you use to refer to your application. We recommend that you specify a human-readable name.
   • Application type. For Web Authentication, you will select the Web application radio button.
   • Domain. The domain name of your application. For most applications, this domain name must be a fully qualified Domain Name System (DNS) name that is unique to your application.
5. Click I accept. After your application has been created, the Summary page appears. This page contains the following information about your site:
   • Secret key. A security key that Windows Live ID uses to encrypt and sign all tokens that it sends to your site. You should record this key, but we recommend that you do not store it in the same location as its corresponding client ID.
   • Client ID. A 16-character string that represents your application. Record this string for later use.

To complete the integration of your application with Windows Live, you must specify additional settings and publish your application. Click the Essentials link under the box that displays your client ID and secret key.

Whenever you want to retrieve or change your application data, return to the Windows Live application management site. Sign in with the Windows Live ID account that you used during registration to see and manage your application projects.

About Web Service Auth Account Licensing

Any web service authentication user account you create will not count against your licensing usage if you make it a generic, non-personal account. Give it a username like apiuser@abccollege.edu , and a generic naming convention that indicates it is not a personal account. You can give it a personal Primary Email and Alert/Notification Email address, but the username and name of the account should be kept non-personal so the license it uses isn't included in your usage count total.