Generic OAuth

​

Overview

​

Use Cases

• Token brokering against OAuth-only authorization servers — Exchange Orchestrator-issued tokens for upstream tokens (RFC 8693 token exchange) against services like Databricks account-wide federation or GCP Workload Identity Federation, where the upstream exposes OAuth but no id_token and no userinfo endpoint.
• Machine-to-machine outbound calls — Authorize outbound calls from the Orchestrator where the upstream authenticates the request via a subject token rather than client credentials.
• OAuth-only authorization servers — Integrate with services like GitHub or Atlassian that provide OAuth 2.0 authorization but not full OIDC, when you need access tokens for API access rather than user identity.
• Federation without a pre-provisioned credential — Connect to an authorization server you cannot register a client with ahead of time. The Orchestrator either registers itself on startup (Dynamic Client Registration) or identifies itself by a URL it publishes (Client ID Metadata Document), so no client ID or secret has to be issued and rotated by hand.

​

Setup

connectors:
  - name: databricks
    type: oauth
    clientID: "{{ env.DATABRICKS_CLIENT_ID }}"
    clientSecret: <vault.databricks_client_secret>
    wellKnownURL: https://accounts.cloud.databricks.com/.well-known/oauth-authorization-server
    loginRedirect:
      urls:
        - https://app.example.com/databricks/oauth

connectors:
  - name: github
    type: oauth
    clientID: "{{ env.GITHUB_CLIENT_ID }}"
    clientSecret: <vault.github_client_secret>
    authorizeURL: https://github.com/login/oauth/authorize
    tokenURL: https://github.com/login/oauth/access_token
    loginRedirect:
      urls:
        - https://app.example.com/github/oauth
    scopes: repo

connectors:
  - name: partner-oauth
    type: oauth
    wellKnownURL: https://auth.example.com/.well-known/oauth-authorization-server
    loginRedirect:
      urls:
        - https://app.example.com/partner/oauth
    # No clientID or clientSecret -- the Orchestrator registers itself on startup.
    dcr:
      clientName: Maverics Orchestrator

connectors:
  - name: partner-oauth
    type: oauth
    wellKnownURL: https://auth.example.com/.well-known/oauth-authorization-server
    loginRedirect:
      urls:
        - https://app.example.com/partner/oauth
    cimd:
      # Served by the Orchestrator at this address, and presented as the client ID.
      url: https://app.example.com/.well-known/oauth-client

​

Client Authentication Modes

​

Dynamic Client Registration

connectors:
  - name: partner-oauth
    type: oauth
    wellKnownURL: https://auth.example.com/.well-known/oauth-authorization-server
    loginRedirect:
      urls:
        - https://app.example.com/partner/oauth
    dcr:
      # Display name the authorization server records for the registered client.
      clientName: Maverics Orchestrator

​

How registration works

• client_name — from dcr.clientName.
• token_endpoint_auth_method — from dcr.tokenEndpointAuthMethod, when set.
• grant_types — authorization_code.
• response_types — code.
• redirect_uris — the connector’s loginRedirect.urls.

​

Client ID Metadata Document

connectors:
  - name: partner-oauth
    type: oauth
    wellKnownURL: https://auth.example.com/.well-known/oauth-authorization-server
    loginRedirect:
      urls:
        - https://app.example.com/partner/oauth
    cimd:
      # Served by the Orchestrator at this address, and presented verbatim as the
      # client ID. Must be lowercase and reachable by the authorization server.
      url: https://app.example.com/.well-known/oauth-client
    # Listing offline_access adds refresh_token to the published grant types.
    scopes: offline_access

​

The published document

{
  "client_id": "https://app.example.com/.well-known/oauth-client",
  "client_name": "partner-oauth",
  "client_uri": "https://app.example.com",
  "redirect_uris": ["https://app.example.com/partner/oauth"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "offline_access",
  "token_endpoint_auth_method": "none"
}

​

URL requirements

• Use the https scheme.
• Include a host and a path other than /.
• Omit any query string, fragment, or userinfo component.
• Omit dot-segments (. and ..).
• Be entirely lowercase, in both host and path. The route is registered lowercased while the published client ID keeps the casing you configure, so a mixed-case URL would return 404 at the very address the document advertises.

​

Discovery

​

Disable Client Authentication

• clientSecret must be empty.
• clientID becomes optional, though some grants may still require it at runtime.
• The Orchestrator enforces grant-type-level rules. For instance, the client-credentials and Resource Owner Password Credentials (ROPC) grants are rejected at runtime when client authentication is disabled, because those grants depend on client credentials to authenticate the request.

connectors:
  - name: databricks-federation
    type: oauth
    clientID: "{{ env.DATABRICKS_CLIENT_ID }}"
    wellKnownURL: https://accounts.cloud.databricks.com/.well-known/oauth-authorization-server
    loginRedirect:
      urls:
        - https://app.example.com/databricks/oauth
    disableClientAuthentication: true

​

Troubleshooting

• Verify the authorizeURL and tokenURL are accessible from the Orchestrator host — confirm both endpoints respond correctly.
• If using wellKnownURL, ensure the discovery document URL is correct and returns valid JSON with authorization_endpoint and token_endpoint fields.
• Ensure the loginRedirect URLs match exactly what is registered with the upstream authorization server.
• Check that the client secret reference resolves correctly via your secret provider — unless disableClientAuthentication is true, in which case clientSecret must be empty.
• If disableClientAuthentication is true, confirm the grant type in use is supported — client-credentials and ROPC grants are rejected when client authentication is disabled.
• Verify the requested scopes are valid for the authorization server — invalid scopes may cause authorization failures.
• If registration fails with a missing registration_endpoint, the discovery document does not advertise one. That authorization server does not support Dynamic Client Registration; use static credentials or CIMD instead.
• If the authorization server rejects a CIMD client as unknown, fetch cimd.url from outside your network and confirm it returns the metadata document rather than a 404. The usual cause is the Orchestrator not being routable at that host and path.
• If the configuration fails to load with 'url' must be lowercase, lowercase the entire cimd.url, host and path alike.
• If either credential-less mode is ignored entirely, check the Orchestrator version — dcr and cimd require v2026.08.2 or later.

​

Related Pages