OAuth 2.0 Clients

Configuring OAuth2 Clients

OAuth2 Clients are used by OAuth2 Email Profiles. Additionally, multiple OAuth2 Email Profiles can use the same OAuth2 Client. When configuring an OAuth2 SMTP Email Profile, you can reference the name of your OAuth2 Client to use those properties. To set up or modify OAuth2 Clients, navigate to the OAuth2 Clients section. You can find this section by going to your Gateway webpage > Config > Security > OAuth2 Clients.

Creating a new OAuth2 Client

1. Click on the OAuth2 Clients option. This will bring up a window where you can select an existing OAuth2 Client to modify, or create a new OAuth2 Client. Select "Create new OAuth2 Client..."
   
   
   
   
2. From here, you will be able to configure your OAuth2 Clients by specifying various properties. Fill out the fields on this page and click "Create New OAuth2 Client".
   
   
   
   
3. Your OAuth 2.0 Client is now set up and you can now test your token, test authorization, or begin using it.

OAuth2 Client Properties

The reference table below lists the available properties to configure and edit for OAuth2 Clients.

OAuth2 Client Options

After you set up your OAuth2 Client, you should have the option to edit your properties, delete the client, test authorization, or test your token.

Test Authorization

The "test authorization" tool allows you to test the integration between the OAuth2 Client configured in Ignition with the OAuth2 Authorization Server. More specifically, it allows you to walk through a test run of the Authorization Code Grant flow. During this process, the authorization server will validate the end user and may prompt the end user to give the Client permissions to perform actions on their behalf, such as sending emails. Once these permissions have been granted, the authorization server will generate an authorization code, which the Client can use to obtain an access token. To see an example of this process work alongside testing tokens, go to the Test Authorization and Token Example.

If you want to test the authorization, choose the test authorization option. 

You will need to add any scopes you want to test with, along with any additional Request Parameters you want to try. You can find Request Parameters in your authorization server's documentation. Once those fields are filled out, click on "Test Authorization".

Test Token

The test token option is useful in cases where you want to test the authorization code to make sure it successfully gives the Client an access token. It is also useful if you want to test an access token request using a client credentials grant, or refreshing an access token using a refresh token.  During this process, the Gateway will make an access token request against the authorization server using one of three methods and get a response back. To see an example of this process work alongside testing authorization, see the Test Authorization and Token Example.

You can find the test token option on the OAuth2 Clients page.

The section below details the Authorization Code, Client Credentials, or a Refresh Token grant types, with the main difference between the three being the type of information you will need to enter.

• Authorization Code
  • If you use an Authorization Code, you will need to enter an Authorization Code, Redirect URL, and any additional Request Parameters. Once you input that information, click on "Test Token".
    
    
    
    
• Client Credentials
  • If you use Client Credentials, you will need to enter a scope and any additional Request Parameters. Once you input that information, click on "Test Token".
    
    
    
    
• Refresh Token
  • If you use a Refresh Token, you will need to enter the Refresh Token, scope, and any additional Request Parameters. Once you input that information, click on "Test Token".
    
    

Test Authorization and Token Example (Google Identity OAuth2)

This example walks you through a "test authorization" and "test token" workflow for an OAuth2 Client configured against Google's OAuth2 Authorization Server.

1. Go to your OAuth2 Clients page. This is located at your Gateway webpage > Config > Security > OAuth2 Clients.
2. Set up your OAuth2 Client if you haven't already. For this example, we are using the OAuth2 Client we set up earlier called "OAuth2":
   
   
   
   
3. Click on the "test authorization" option. This will bring up the Test Authorization window. Add any Scopes and additional Request Parameters for your OAuth2 Client, and then press "Test Authorization".
   
   
   The additional Request Parameters in the example are specific to Google's Authorization Server. They do two things:
   
   1. access_type: Setting this parameter to "offline" will allow your Client to refresh access tokens while the user is not present at the browser.
   2. prompt: Setting this parameter to "consent" will force the Client to prompt the user for consent.
      
      
4. Since we are using Google Identity, we will be redirected, and a Google permission prompt will appear. Click "Allow".
   
   
   
   

5. Once permissions are granted to the OAuth2 Client, you will be redirected to the Gateway. Information about the authentication, including the authorization code, timestamps, results, and more will be displayed.
   
   
   
   

   Note: Besides the main OAuth2 Client page, you can use the Test Token button on the authentication results page to test access tokens. The benefit of testing your token from the authentication results page however, is that some information, such as the Authentication Code and Redirect URL will already be filled out based off the information from the authorization test.

6. Click on the "Test Token" button on the authentication results page. This will bring you to the Test Token page, where some fields will already be filled in.
   
   
   
   Click on "Test Token" to see what the token test results will be.
   
   
7. A "Token Response" dialog box will appear, showing the results of the token test, as well as timestamps, the response, and more. Click "Done" to close out the dialog box.