How to protect Hubway Connect APIs with OAuth 2.0 using Microsoft Entra

Hubway Connect supports custom authentication methods for protecting your APIs. If you choose OAuth 2.0, you don’t need to implement it from scratch as Hubway provides a ready-to-use authentication plugin called HWAuthentication_OAuth2.

This guide explains how to configure Microsoft Entra ID (formerly Azure Active Directory) as your identity provider using this plugin.

⚠️ Note that this module is optional and if you don’t have it available on your environment, reach out to our support team.

Prerequisites

Before starting, ensure you have:

• Hubway Connect installed in your OutSystems environment along with HWAuthentication_OAuth2 plugin
• Access to Microsoft Entra ID (Azure Portal) with permission to create App Registrations
• Postman or a similar tool for testing API requests

Step 1 – Register the API Application (Microsoft Entra ID)

This application represents the protected resource (your API).

1. Go to Microsoft Entra → App registrations → New registration
   2. Provide a Name and fill in the required fields
   3. Click Register
   – Data will be configured automatically as seen below
   4. Go to Expose an API → Add a scope
   – An Application ID URI will be created automatically
   – Define a scope (e.g., access_as_user)
   5. Add yourself as the Owner.

Step 2 – Register the API Client Application (Microsoft Entra ID)

This application requests tokens and calls the API.

1. Go to Microsoft Entra → App registrations → New registration
2. Configure name, redirect URI (if needed), then register
3. In Authentication: enable Access tokens and ID tokens. Set Allow public client flows = Yes
4. In API permissions: add your API and choose access_as_user.
5. In Certificates & secrets: generate a client secret.
   – Copy the Value immediately — this is the secret string used for authentication.
   – ⚠️ The Value is the secret. The Secret ID is just an identifier.

Step 3. Request an Access Token for the Client Credentials Flow (Postman)

Open Postman App, create a new request with the following details:

• Method: Post
• URL: https://login.microsoftonline.com/{Tenant ID}/oauth2/v2.0/token -> get the Tenant ID from the Application API client you’ve created.
• Body(x-www-form-urlencoded):
  • client_id -> Application(client ID) of the Application API client(in this example, Hubway API Client 2)

  • client_secret -> The Value from the Certificates & secret of the Application API client(Hubway API Client 2)

  • scope -> The scope from the Application API you’ve created(in this example, Hubway API 2) under the Expose an API tab. But change the name at the end of the URL to “.default”

  • grant_type -> “client_credentials“

Step 4. Request an Keys for the Client Credentials Flow (Postman)

In Postman App, create a new request with the following details:

• Method: Get
• URL: https://login.microsoftonline.com/{Tenant ID}/discovery/v2.0/keys – get the Tenant ID from the Application API client you’ve created.

Step 5. Configure site properties in HWAuthentication_OAuth2

1. Decode the access token (from step 3) in JWT.io. Note the Key ID (kid).
2.  Match the kid and set in Service Center:
   – ExpectedSignatureKeyId = kid
   – SignatureKey = matching key value (in keys from step 4)

Step 6. Test API with Access Token

1. Create a new project in Hubway Builder, and change the Security Tab, select the OAuth 2.0 as the Authentication.
2. Copy the test link in the Overview Tab and add the Country entity to the project
3. In Postman
   1. Method: Get
   2. URL: use the Test link from your Hubway Connect project and append /Country
   3. Authorization: Select Bearer Token and use the Access Token (from step 3) as the Bearer Token

If configured correctly, you’ll see the entity data.

Step 7. Obtain and Use an ID Token

1. Open browser URL:
   https://login.microsoftonline.com/{Tenant ID}/oauth2/v2.0/authorize?client_id={Client ID} & response_type=id_token & redirect_uri=redirect_uri={Redirect URI} & scope=openid profile email & response_mode=fragment & nonce=12345
2. Sign in with your Microsoft credentials and copy the id_token value from the redirected URI
3. In Postman
   • Method: Get
   • URL: use the Test link from your Hubway Connect project and append /Country
   • Authorization: Select Bearer Token and use the id_token value as the Bearer Token

The id_token allows Hubway to retrieve user details, which are recorded in audit logs.

Final considerations

• Never share client secrets
• Secrets expire; renew them before expiry
• The use of the id_token is preferred when possible, as it contains richer user-related information (claims) that can be used for identification