feat(refresh-token): Add refresh token option to the rest connector, add it to the MS email as well

[mathias-vandaele]

This pull request adds support for OAuth 2.0 Refresh Token authentication to the HTTP client library and updates the GraphQL connector templates to allow users to configure this new authentication method. The implementation includes a new authentication type, request/response handling logic, error handling for common OAuth failure modes, and comprehensive tests to ensure correct behavior.

OAuth 2.0 Refresh Token Authentication Support

• Introduced the new OAuthRefreshTokenAuthentication type, including its data model and logic for building the refresh token grant request body. (OAuthRefreshTokenAuthentication.java)
• Registered the new authentication type in the polymorphic HttpAuthentication hierarchy. (HttpAuthentication.java)

Request and Token Handling

• Implemented methods in OAuthService to create OAuth refresh token requests and extract tokens from responses, with detailed error handling for invalid_grant, interaction_required, and other OAuth errors. (OAuthService.java) [1] [2]
• Updated the request builder to support the new authentication type, including fetching and applying access tokens obtained via the refresh token flow. (ApacheRequestAuthenticationBuilder.java) [1] [2]
• Added new constants for OAuth error fields and refresh token parameters. (OAuthConstants.java)

Connector Template Updates

• Extended both the standard and hybrid GraphQL connector element templates to allow configuration of OAuth 2.0 Refresh Token authentication, including all required fields (token endpoint, client ID, client secret, refresh token, and scopes). (graphql-outbound-connector.json, graphql-outbound-connector-hybrid.json) [1] [2] [3] [4]

Testing

• Added a comprehensive test suite for the OAuth refresh token flow, covering request construction, successful token extraction, and error handling for common OAuth error responses. (OAuthRefreshTokenServiceTest.java)

[Copilot]

Pull request overview

This PR adds OAuth 2.0 Refresh Token authentication support to the shared HTTP client stack and exposes it through the REST/GraphQL/HTTP-polling element templates, plus wires the option into the Microsoft O365 Mail template.

Changes:

• Introduces a new OAuthRefreshTokenAuthentication type (client + http-base model) and registers it in the polymorphic authentication hierarchies/mappers.
• Implements refresh-token grant request/response handling (including common OAuth error cases) and uses it in the Apache request auth builder.
• Updates multiple element templates (REST, GraphQL, polling, O365 Mail) and bumps REST connector/template versions accordingly.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
connectors/microsoft/mail/element-templates/versioned/microsoft-office365-mail-connector-4.json	Adds a new versioned v4 O365 Mail element template snapshot.
connectors/microsoft/mail/element-templates/microsoft-office365-mail-connector.json	Bumps template to v5 and adds refresh-token auth configuration fields.
connectors/http/rest/src/main/java/io/camunda/connector/http/rest/HttpJsonFunction.java	Bumps REST connector element template version annotation to 14.
connectors/http/rest/README.md	Updates documented REST connector version to 14.
connectors/http/rest/element-templates/versioned/http-connector.json-13.json	Adds a versioned template snapshot for REST connector version 13.
connectors/http/rest/element-templates/hybrid/http-json-connector-hybrid.json	Bumps to v14 and adds refresh-token auth fields for hybrid template.
connectors/http/rest/element-templates/http-json-connector.json	Bumps to v14 and adds refresh-token auth fields.
connectors/http/polling/element-templates/http-polling-connector.json	Adds refresh-token auth fields to HTTP polling template.
connectors/http/polling/element-templates/http-polling-boundary-catch-event-connector.json	Adds refresh-token auth fields to HTTP polling boundary template.
connectors/http/http-base/src/main/java/io/camunda/connector/http/base/model/auth/OAuthRefreshTokenAuthentication.java	Adds http-base model subtype for refresh-token auth (template-generation model).
connectors/http/http-base/src/main/java/io/camunda/connector/http/base/model/auth/AuthenticationMapper.java	Maps http-base refresh-token auth model into http-client auth model.
connectors/http/http-base/src/main/java/io/camunda/connector/http/base/model/auth/Authentication.java	Registers refresh-token auth subtype in the sealed/auth polymorphic config.
connectors/http/graphql/element-templates/hybrid/graphql-outbound-connector-hybrid.json	Adds refresh-token auth fields to GraphQL hybrid template.
connectors/http/graphql/element-templates/graphql-outbound-connector.json	Adds refresh-token auth fields to GraphQL standard template.
connector-commons/http-client/src/test/java/io/camunda/connector/http/client/authentication/OAuthRefreshTokenServiceTest.java	Adds tests for refresh-token request creation and token/error extraction.
connector-commons/http-client/src/main/java/io/camunda/connector/http/client/model/auth/OAuthRefreshTokenAuthentication.java	Adds http-client refresh-token auth model and form body builder.
connector-commons/http-client/src/main/java/io/camunda/connector/http/client/model/auth/HttpAuthentication.java	Registers refresh-token auth subtype in the http-client polymorphic hierarchy.
connector-commons/http-client/src/main/java/io/camunda/connector/http/client/client/apache/builder/parts/ApacheRequestAuthenticationBuilder.java	Adds support for applying refresh-token based access tokens to requests.
connector-commons/http-client/src/main/java/io/camunda/connector/http/client/authentication/OAuthService.java	Adds refresh-token grant request creation and token/error extraction logic.
connector-commons/http-client/src/main/java/io/camunda/connector/http/client/authentication/OAuthConstants.java	Adds constants needed for refresh-token parameters and OAuth error fields.

Comments suppressed due to low confidence (1)

connectors/microsoft/mail/element-templates/microsoft-office365-mail-connector.json:970

• The template's top-level version was bumped to 5, but the elementTemplateVersion task header is set to 4. Other Microsoft templates keep these aligned (e.g., azure-open-ai-connector.json uses value "2" for version 2), so this likely should be updated to 5 to avoid confusion and inconsistent metadata at runtime.

      "id": "version",
      "label": "Version",
      "description": "Version of the element template",
      "value": "4",
      "group": "connector",
      "binding": {
        "key": "elementTemplateVersion",
        "type": "zeebe:taskHeader"
      },
      "type": "Hidden"

[johnBgood]

Code review

Found 2 issues:

1. OAuthRefreshTokenAuthentication bypasses the token cache on every invocation — unlike OAuthAuthentication which routes through tokenCache.getOrFetch(auth, ...), the new case calls fetchOAuthRefreshToken(auth) directly, issuing a live HTTP request to the token endpoint on every connector execution. The OAuthTokenCache was introduced specifically to avoid this per-invocation overhead.

connectors/connector-commons/http-client/src/main/java/io/camunda/connector/http/client/client/apache/builder/parts/ApacheRequestAuthenticationBuilder.java

Lines 53 to 61 in dfab214

	case OAuthAuthentication auth -> {
	var token = tokenCache.getOrFetch(auth, () -> fetchOAuthToken(auth));
	builder.addHeader(AUTHORIZATION, String.format(BEARER, token));
	}
	case OAuthRefreshTokenAuthentication auth -> {
	var token = fetchOAuthRefreshToken(auth);
	builder.addHeader(AUTHORIZATION, String.format(BEARER, token));
	}
	case BearerAuthentication auth ->

2. The new versioned element template snapshot is named http-connector.json-13.json, breaking the established naming convention — all 13 existing files in the same directory follow http-json-connector-{N}.json (e.g. http-json-connector-12.json). The file should be named http-json-connector-13.json.

https://github.com/camunda/connectors/blob/dfab214325399e2f3280415039246997578fabc5/connectors/http/rest/element-templates/versioned/http-connector.json-13.json

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}