Generic OAuth - Maverics Documentation

The Generic OAuth connector provides a pure OAuth 2.0 integration for upstream authorization servers. It speaks OAuth only — it does not consume an id_token or call a userinfo endpoint. The OAuth connector provides flexibility to connect services like GitHub, Atlassian, and other platforms that support OAuth but not OpenID Connect..

Console terminology: In the Maverics Console, this section is called Identity Fabric. The YAML configuration uses the connectors key to define identity provider integrations.

Overview

The Generic OAuth connector targets authorization servers that expose OAuth 2.0 endpoints. It supports two configuration styles — discovery via a wellKnownURL, or manually specified authorizeURL and tokenURL endpoints — and a non-standard “no client authentication” mode for federation flows where the upstream authenticates the request via a subject token instead of client credentials. The wellKnownURL field accepts either an OAuth Authorization Server Metadata document or an OIDC discovery document (which is a superset of the OAuth metadata format). Either way, the connector reads only the OAuth endpoints from the discovery document — it does not perform OIDC end-user authentication. For interactive end-user login against a full OpenID Connect IdP, use the Generic OIDC connector instead.

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.

Setup

Console UI
Configuration

To create a Generic OAuth connector in the Maverics Console:

Navigate to Identity Fabric in the Console sidebar.
Click Create and select Generic OAuth.
Enter a Name for the connector — this is the friendly name that identifies your OAuth integration.
Provide endpoints either by:
- Entering the Well Known URL — either an OAuth Authorization Server Metadata URL (RFC 8414) or an OIDC discovery URL; or
- Entering the Authorization URL and Token URL manually.
These two approaches are mutually exclusive — provide one or the other, not both.
Enter the Client ID issued by the upstream authorization server.
Enter the Client Secret associated with the client ID. Use the show/hide toggle to verify the value.
Add one or more Redirect URLs — the URL(s) where the Orchestrator’s OAuth handler is served. At least one entry is required.
Optionally enable Disable Client Authentication if the upstream authorization server authenticates the request via the subject token alone (for example, Databricks account-wide federation). See Disable Client Authentication below.
Click Save.

If your upstream is a full OpenID Connect provider and you need identity claims and end-user session handling out of the box (i.e., id_token and userinfo), use the Generic OIDC connector instead.

The OAuth connector supports two configuration approaches. Use wellKnownURL when the authorization server publishes a discovery document (either OAuth Authorization Server Metadata or OIDC discovery), or manually specify the authorizeURL and tokenURL endpoints. These two options are mutually exclusive.Option 1: Using a well-known discovery URL

maverics.yaml

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

Option 2: Manually specifying authorize and token URLs

maverics.yaml

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

Configuration Reference

Key	Type	Required	Description
`name`	string	Yes	Friendly name of the connector, referenced in app policies.
`type`	string	Yes	Must be `oauth`.
`wellKnownURL`	string	Conditional	Discovery document URL — either OAuth Authorization Server Metadata (RFC 8414) or OIDC discovery. The connector reads only the OAuth endpoints. Provide this or `authorizeURL` + `tokenURL`, not both.
`authorizeURL`	string	Conditional	OAuth 2.0 authorization endpoint. Required only when `wellKnownURL` is omitted. Mutually exclusive with `wellKnownURL`.
`tokenURL`	string	Conditional	OAuth 2.0 token endpoint. Required only when `wellKnownURL` is omitted. Mutually exclusive with `wellKnownURL`.
`clientID`	string	Conditional	OAuth 2.0 client ID. Required unless `disableClientAuthentication` is `true`, in which case it is optional (some grants may still require it at runtime).
`clientSecret`	string	Conditional	OAuth 2.0 client secret (use secret reference syntax). Required unless `disableClientAuthentication` is `true`, in which case it must be empty.
`loginRedirect.urls`	list	Yes	Redirect URL(s) where the Orchestrator’s OAuth handler is served. At least one entry is required.
`disableClientAuthentication`	boolean	No	When `true`, the Orchestrator does not send `client_secret` in OAuth form bodies. See Disable Client Authentication. Defaults to `false`.
`scopes`	string	No	Space-separated OAuth scopes to request.

For the complete field reference including health checks, see Identity Fabric.

Disable Client Authentication

Setting disableClientAuthentication: true is intended for federation flows where the upstream authorization server authenticates the request via the subject token alone — for example, Databricks account-wide federation. When enabled:

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.

maverics.yaml

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.

Identity Fabric

Overview of all identity providers

Token Brokering

RFC 8693 token exchange for downstream APIs

Generic OIDC

Generic OpenID Connect connector

Generic SAML

Generic SAML 2.0 connector

​Overview

​Use Cases

​Setup

​Configuration Reference

​Disable Client Authentication

​Troubleshooting

​Related Pages

Identity Fabric

Token Brokering

Generic OIDC

Generic SAML

Overview

Use Cases

Setup

Configuration Reference

Disable Client Authentication

Troubleshooting

Related Pages