Skip to content

OAuth Configuration Guide

InfoConnect Hub, RPA Hub and the InfoConnect MCP server can authenticate callers with OAuth 2.0 instead of Basic authentication. This guide explains how to enable OAuth in each module, how the modules authenticate to each other, and how to set up each supported authorization server.

Overview

Each module has a property that selects its authentication type:

Module Property Values
Hub auth.type basic, oauth, both
RPA Hub auth.type basic, oauth
MCP mcp.auth.type none, basic, oauth, spring-oauth-server

On the Hub, each value of the role claim (spring.oauth.resource.server.authority.claim) must be the name of a Hub user group, by default admin or user. See User groups and permissions. The authority.admin and authority.user properties are used only by the MCP server.

Supported OAuth configurations:

  • Built-in authorization server (the authorization_server application shipped with the Hub)
  • AWS Cognito
  • Okta
  • Salesforce
  • Azure AD

Every provider section below uses requests from the OAuth InfoConnect Hub folder of the Postman collection. For RPA Hub-specific OAuth settings, see the RPA Hub user manual.

Setting the authorization type

Set the authentication type in each module you want to secure with OAuth:

  • In Hub or RPA Hub, set the property auth.type to oauth.

    Hub properties with auth.type set to oauth

  • In MCP, set the property mcp.auth.type to oauth.

    MCP properties with mcp.auth.type set to oauth

Configuring communication between modules

When you secure a module with OAuth, the modules that call it must be configured with matching security properties. For example, if you enable OAuth 2.0 on RPA Hub, set the RPA security properties on the Hub. Otherwise, the Hub cannot send requests to RPA Hub.

The modules call each other as follows:

  • Hub calls RPA Hub.
  • MCP calls the Hub. It reads RPA Calls through the Hub.
  • The Hub UI calls the Hub, RPA Hub and MCP.

For calls between modules, set the provider of the called module (for example rpa.oauth.provider) to Azure, AWS or built-in. Okta and Salesforce can secure incoming calls, but not calls between modules.

Each caller has a similar set of properties for each module it accesses. The following example shows the properties you define on the Hub to access RPA Hub:

Properties on the Hub for accessing the secured RPA Hub

The properties use these values:

Value Description
Client ID, client secret, domain Common to most OAuth 2.0 providers. Find them in the settings of your provider.
Refresh token Used by some providers. It usually stays valid for a long time; you can configure the period in the provider settings.
Azure scope, Azure organization Used only with the Azure provider. Find them in the Azure settings.

Getting a refresh token

The exact procedure depends on the provider and is described in the provider sections below. The main steps are always the same:

  1. Register on the chosen platform (AWS, Okta, Salesforce).
  2. Create users with the roles admin and user. Tokens differ for user and admin.
  3. Send the authorization requests described in the provider section. They differ for each provider.
  4. Receive the refresh token, which contains information about the authenticated user.

Built-in OAuth authorization

Use the built-in authorization server when you do not want to depend on an external identity provider.

  1. Run the authorization_server application. In its application.properties, set your own client secret and client ID.

    Warning

    Use the same client secret and client ID when you configure communication between modules (see Configuring communication between modules).

    application.properties of the authorization server with the client ID and client secret

  2. Change basic to oauth in application.properties at /opt/info-connect-hub/config/ and uncomment the OAuth properties below it.

    application.properties with the authentication type changed to oauth

    application.properties with the OAuth main configuration uncommented

    auth.type = oauth
    spring.oauth.resource.server.issuer-uri=http://localhost:8081
    spring.oauth.resource.server.authority.admin=ROLE_admin
    spring.oauth.resource.server.authority.user=ROLE_user
    spring.oauth.resource.server.authority.claim=role
    

    Warning

    The issuer URI is also used as the domain when you configure communication between modules.

    RPA domain property set to the issuer URI

  3. Start the authorization server.

    sudo service auth-server start
    
  4. To start the authorization server automatically, enable autostart.

    sudo chkconfig auth-server on
    
  5. Restart the Hub.

    sudo service info-connect-hub restart
    
  6. Open the Postman OAuth collection, folder Built-in oauth, and send the request BUILT_IN:Get code verifier and code challenge. It returns the code_verifier for the token request and the code_challenge for generating the authorization code.

    Postman request BUILT_IN:Get code verifier and code challenge

  7. In the same folder, open the request BUILT_IN: Get oauth code. Copy the code_challenge from the application console and paste it into the same parameter of the request.

    Postman request BUILT_IN: Get oauth code with the code_challenge parameter

  8. Copy the request URL, paste it into your browser and sign in with user or admin credentials.

    Sign-in page of the built-in authorization server

  9. After you sign in, the browser redirects you to a Spring page. Copy the code parameter from the page URL.

    Browser address bar with the code parameter in the redirect URL

  10. Open the request BUILT_IN: Get oauth token. Paste the copied code into the code parameter. Copy the code_verifier from the application console and paste it into the code_verifier parameter.

    Postman request BUILT_IN: Get oauth token with the code and code_verifier parameters

  11. Send the request to receive the access token.

    Note

    The response also contains the refresh token, which you use when you configure communication between modules.

    Postman response with the access token and the refresh token

  12. To validate the received token, send the request BUILT_IN: Validate OAuth token.

  13. Use the access token to call the endpoints of the Hub.

AWS OAuth authorization

To use AWS Cognito as the OAuth provider, create a user pool in the AWS Management Console.

  1. Open the AWS website.

  2. Select My Account > AWS Management Console in the upper-right corner. On the login page, sign in or create your AWS account.

    AWS website My Account menu with the AWS Management Console option

  3. After you sign in, search for Amazon Cognito in the search box and open it.

    AWS Console search results for Amazon Cognito

  4. Create a user pool: select User Pools > Create User Pool.

    Amazon Cognito User Pools page with the Create User Pool button

  5. Enter the user pool details: the name of your application and the redirect URI. The browser redirects to this URI in a later step and returns the access code.

    Create user pool form with the application name

    Create user pool form with the redirect URI

  6. After the user pool is created, it appears in the user pool list. Open it.

    User pool list with the new user pool

  7. Create a user: open the Users tab and select Create User.

    Users tab with the Create User button

  8. Enter the user's email and password. The new user appears on the Users tab of your user pool.

    Create user form with email and password

  9. Create the admin and user groups: open the Groups tab, select Create Group and fill in the details of each group.

    Groups tab with the Create Group button

    Create group form

  10. Return to the Users tab, open the new user and add the user to the admin or user group.

    User details with the Add user to group button

  11. To receive a token, you first need a code. Select App Clients > Login Pages > View Login Page and sign in with the credentials of the new user.

    App client Login pages tab with the View login page button

    Cognito hosted sign-in page

  12. After you sign in, the browser redirects you to the URI entered at the beginning. Copy the code value from the URL in the address bar.

    Browser address bar with the code parameter after the redirect

  13. Collect the values needed for the token request. You need the client ID and client secret from App Clients.

    App client details with the client ID and client secret

    You also need the domain. In the left panel, select Brand > Domain and copy the domain. You can also edit the domain there.

    Domain page of the user pool

  14. Before you get a refresh token, edit the refresh token lifetime in the user pool settings.

    Warning

    The default lifetime is 5 days. After that your application stops working until you receive a new refresh token, put it into the properties and restart the application.

    Select User pools > your user pool > App clients > your app client > Edit.

    App client page with the Edit button

    In the opened window, edit the refresh token lifetime. You can enter a longer value, for example one year.

    App client edit page with the refresh token lifetime

    Select Save changes in the bottom-right corner.

  15. Get the refresh token with one of the two methods below. Replace the placeholders with the values from the previous steps. The code is valid for a short time, so send the token request as soon as you receive the code.

    Option 1: Request in a terminal

    Send the following request.

    curl -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
    -d "grant_type=authorization_code" \
    -d "code=YOUR_OBTAINED_CODE" \
    -d "redirect_uri=YOUR_REDIRECT_URI" \
    "YOUR_DOMAIN/oauth2/token"
    

    The response looks like this:

    {
    "access_token": "eyJraWQiOiJ....",
    "refresh_token": "eyJjdHkiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....",
    "id_token": "eyJraWQiOiJ....",
    "token_type": "Bearer",
    "expires_in": 3600
    }
    

    Extract the refresh token from the response and put it into the application properties file.

    Option 2: Request in Postman

    Send the request AWS: Get oauth token from the Postman collection.

    Postman request AWS: Get oauth token

    The response is the same as in the terminal. Extract the refresh token and put it into the application properties file.

    Postman response with the refresh token

  16. Using the information from the token payload, configure application.properties of the info-connect-hub application:

    auth.type = oauth
    
    # ISSUER_URI
    # A website, application, or service that creates and signs JWTs.
    spring.oauth.resource.server.issuer-uri_OKTA=empty
    spring.oauth.resource.server.issuer-uri_BUILT_IN=empty
    spring.oauth.resource.server.issuer-uri_AWS=YOUR_ISSUER_URI
    spring.oauth.resource.server.issuer-uri_SALESFORCE=empty
    spring.oauth.resource.server.issuer-uri_AZURE=empty
    
    # MAIN_CONFIG
    # The configuration you use for your OAuth provider.
    spring.oauth.resource.server.issuer-uri=YOUR_ISSUER_URI
    spring.oauth.resource.server.authority.admin=ROLE_admin
    spring.oauth.resource.server.authority.user=ROLE_user
    # The parameter that contains information about the user's role when using OAuth.
    # Allows extracting user roles from JWT token.
    # For AWS use 'cognito:groups', for Azure - 'roles', for BUILT_IN server - 'role'.
    spring.oauth.resource.server.authority.claim=cognito:groups
    
  17. To validate the token, send the request AWS: Validate OAuth Token. Pass the token as a parameter and add issUrl from the token as a parameter.

Okta OAuth authorization

  1. In Okta, open Applications and select Applications from the menu.

    Okta Applications menu

  2. Select Create App Integration.

  3. Select OIDC - OpenID Connect and Web Application.

    Create a new app integration dialog with OIDC and Web Application selected

  4. Create the application.

    New Web App Integration form, part 1

    New Web App Integration form, part 2

    Application created in Okta

  5. Open the Sign On tab and find OpenID Connect ID token. Select Edit > Issuer > Okta URL > Save.

    Sign On tab with the OpenID Connect ID token section

    OpenID Connect ID token section in edit mode

    Issuer set to the Okta URL

  6. Open the Directory tab and select Groups.

    Directory menu with the Groups option

    Groups page

  7. Select Add group and create one group for admins and one for users.

    Add group button

    Add group form

  8. Add the user to a group and create the scope and claim that carry the group information:

    1. Open the group to which you want to assign a user.

      Group page in Okta

    2. Select Assign people, choose the user and select the plus button.

      Assign people dialog

    3. Add a scope, which is named role here. Later you place the claim with the user's group or role in it.

      Okta scope setup, screen 1 of 2

      Okta scope setup, screen 2 of 2

    4. Open the Scopes tab, select Add Scope and set up the scope.

      Scopes tab with the Add Scope button

    5. Select Add Scope and set up the scope.

      Add Scope form

    6. Open the Claims tab and select Add Claim.

      Claims tab with the Add Claim button

    7. Set up the claim with these values:

      • name: name
      • filter: Match regex (admin | user)
      • Include in: the scope from the previous steps

      Add Claim form with the name, filter and scope values

  9. Update the requests in the Okta folder of the Postman collection. In the request Okta: Get OAuth Code, copy the Sign-in redirect URIs from Okta and paste them into the redirect_uri parameter. Copy the client_id and paste it into the client_id parameter.

    Sign-in redirect URIs of the Okta application

    client_id on the General tab of the Okta application

    Postman request Okta: Get OAuth Code with redirect_uri and client_id

  10. Copy the request, paste it into your browser and sign in. After the redirect, copy the code parameter from the address bar.

    Browser address bar with the code parameter after the redirect

  11. Paste the copied code into the code parameter of the request OKTA: Get OAuth Token and set the other parameters:

    • redirect_uri: the Sign-in redirect URIs value copied in the previous step
    • client_id: find it on the General tab
    • client_secret: find it on the General tab

    Okta token request, screen 1 of 3

    Okta token request, screen 2 of 3

    Okta token request, screen 3 of 3

  12. Decode the token on jwt.io.

    Decoded token payload on jwt.io

  13. Using the information from the token payload, configure application.properties of the info-connect-hub application:

    auth.type=oauth
    spring.oauth.resource.server.issuer-uri=<iss>
    spring.oauth.resource.server.issuer-uri_OKTA=<iss>
    # Name of the claim that contains the user's group or role
    spring.oauth.resource.server.authority.claim=<claim-name>
    # Must correspond to the names of your groups in Okta, prefixed with ROLE_
    spring.oauth.resource.server.authority.admin=ROLE_admin
    spring.oauth.resource.server.authority.user=ROLE_user
    

    application.properties with the Okta values

  14. To validate the token, send the request OKTA: Validate oauth token with the token in the body parameter.

    Postman request OKTA: Validate oauth token

Salesforce OAuth authorization

  1. After you sign in to Salesforce, select the gear icon next to your profile (Setup).

    Salesforce gear icon with the Setup entry

  2. Go to the App tab under the Platform Tools category and select App Manager.

    App Manager under Platform Tools

  3. Select New Connected App.

    App Manager page with the New Connected App button

  4. Configure the connected app, for example as follows:

    • Enable OAuth Settings: true
    • Selected OAuth Scopes: Access unique user identifiers (openid)
    • Include custom attributes
    • Include custom permissions

    Connected app basic information

    Connected app OAuth settings

    Connected app OAuth scopes and options

  5. Scroll down the page of the new connected app and create a new custom attribute.

    Custom attributes section of the connected app

  6. Create an attribute based on the user's role. You create the role in the next step.

    Custom attribute based on the user's role

  7. Create a user role: in the Administration section, select Users > Roles > Add Role.

    Administration section with Users and Roles

    Roles page with the Add Role button

    New role form

    Role setup, screen 4 of 4

  8. Assign the role to a user:

    1. Open the role to which you want to assign the user.

      Role details page

    2. Select Assign Users to Role.

      Assign Users to Role button

    3. In the Available Users Search list, select All Users.

      Available Users Search list with All Users selected

    4. Select the user to whom you want to assign the role.

  9. Return to the connected app and select Manage Consumer Details to get the client_id and client_secret.

    Connected app page with the Manage Consumer Details button

    Consumer key and consumer secret of the connected app

  10. Copy the client_id and client_secret and paste them into the corresponding fields of the SALESFORCE: Get OAuth Token request in the OAuth collection. Also add the callback URL that you created when you configured the connected app.

    Postman request SALESFORCE: Get OAuth Token with the client credentials

  11. After you generate the token, you receive an access token and an ID token. Use the ID token, because the access token is not in JWT format. Decode it on jwt.io.

    Decoded ID token payload on jwt.io

  12. Using the information from the token payload, configure application.properties of the info-connect-hub application:

    auth.type=oauth
    spring.oauth.resource.server.issuer-uri=<iss>
    spring.oauth.resource.server.issuer-uri_SALESFORCE=<iss>
    # Name of the parameter from which the role or group is read
    spring.oauth.resource.server.authority.claim=<claim-name>
    # Must correspond to the names of your groups in Salesforce, prefixed with ROLE_
    spring.oauth.resource.server.authority.admin=ROLE_admin
    spring.oauth.resource.server.authority.user=ROLE_user
    

    application.properties with the Salesforce values

  13. To validate the token, send the request SALESFORCE: Validate OAuth Token. Pass your token, client_id and client_secret as parameters.

    Postman request SALESFORCE: Validate OAuth Token

Azure AD OAuth authorization

  1. Sign in to Azure Active Directory.

  2. In the Manage category, select App registrations > New registration.

    Azure Active Directory menu with App registrations

    App registrations page with the New registration button

  3. Use this configuration:

    • Supported account type: Account in any organizational directory (Any Azure AD directory - Multitenant)

    Register an application form with the supported account types

  4. Set the Application ID URI: select Add next to Application ID URI and, in the pop-up window, select Save.

    Application ID URI with the Add button

    Set the Application ID URI pop-up window

  5. Open the App roles tab in the Manage category.

    App roles tab in the Manage category

  6. Select Create app role.

    App roles page with the Create app role button

  7. Create the roles. You need one role for admin and one for user. Use these values:

    • Name: admin / user
    • Allowed member type: Applications
    • Value: admin / user
    • Do you want to enable this app role?: true

    Create app role form

  8. Create a client for this application: open the App registrations tab.

    App registrations tab

  9. Register a new application. For two roles, register two client applications: one for the admin role and one for the user role. Use these values:

    • Name: YOUR_NAME
    • Supported account type: Account in any organizational directory (Any Azure AD directory - Multitenant)

    Register an application form for the client application

  10. Add API permissions: open the API permissions tab and select Add a permission.

    API permissions tab with the Add a permission button

    Request API permissions pane

    Request API permissions pane with the application permissions

  11. Select My APIs and choose your application created in the previous step (8). Then grant admin consent for <your organization> or ask your organization's administrator to do it.

    My APIs list with the application selected

    Grant admin consent confirmation

  12. Configure the client_id and client_secret:

    1. Open the Certificates and secrets tab and select New client secret.

      Certificates and secrets tab with the New client secret button

      Add a client secret pane

      Client secret list with the generated value

    2. Copy the client_secret from the Value field and paste it into the client_secret parameter of the request AZUREAD: Get oauth token.

      Postman request AZUREAD: Get oauth token with the client_secret

    3. Copy the Application ID and paste it into the client_id parameter of the request.

      Application ID on the overview page of the client application

    4. Open All apps by selecting <your_organization>.

      All apps list reached from the organization name

    5. Choose the app you created first. In the original example it is AzureADOauthExample. Copy its Application ID URI. Before you paste it into the request parameter, add /.default to the URI, for example api://<application-id>/.default.

      Application ID URI of the first application

  13. Open All applications, choose your client application and select Endpoints.

    All applications list with the client application

    Endpoints pane of the client application

  14. Copy the OAuth 2.0 token endpoint (v2) and paste it into the URL field of the request AZUREAD: Get oauth token. Replace organizations with the value of the Directory ID.

    Azure token endpoint setup, screen 1 of 4

    Azure token endpoint setup, screen 2 of 4

    Azure token endpoint setup, screen 3 of 4

    Azure token endpoint setup, screen 4 of 4

  15. You now have an access token. Decode it on jwt.io.

    Decoded access token payload on jwt.io

  16. Using the information from the token payload, configure application.properties of the info-connect-hub application:

    auth.type=oauth
    spring.oauth.resource.server.issuer-uri=<iss>
    spring.oauth.resource.server.issuer-uri_AZURE=<iss>
    # Name of the claim from which the role or group is read
    spring.oauth.resource.server.authority.claim=roles
    # Must correspond to the names of your groups in Azure, prefixed with ROLE_
    spring.oauth.resource.server.authority.admin=ROLE_admin
    spring.oauth.resource.server.authority.user=ROLE_user
    

    application.properties with the Azure values

  17. Token validation: Azure does not currently provide a validation endpoint. According to Microsoft forum posts, Microsoft is working on it.