> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generic OAuth

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..

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

## 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](https://datatracker.ietf.org/doc/html/rfc8414) document or an [OIDC discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) 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](/reference/orchestrator/identity-fabric/custom-oidc) connector instead.

## Use Cases

* **[Token brokering](/reference/orchestrator/experimental/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

<Tabs>
  <Tab title="Console UI">
    To create a Generic OAuth connector in the Maverics Console:

    1. Navigate to **Identity Fabric** in the Console sidebar.
    2. Click **Create** and select **Generic OAuth**.
    3. Enter a **Name** for the connector -- this is the friendly name that identifies your OAuth integration.
    4. 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.
    5. Enter the **Client ID** issued by the upstream authorization server.
    6. Enter the **Client Secret** associated with the client ID. Use the show/hide toggle to verify the value.
    7. Add one or more **Redirect URLs** -- the URL(s) where the Orchestrator's OAuth handler is served. At least one entry is required.
    8. 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](#disable-client-authentication) below.
    9. Click **Save**.

    <Tip>
      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](/reference/orchestrator/identity-fabric/custom-oidc) connector instead.
    </Tip>
  </Tab>

  <Tab title="Configuration">
    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**

    ```yaml maverics.yaml theme={null}
    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**

    ```yaml maverics.yaml theme={null}
    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](#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](/reference/orchestrator/identity-fabric#configuration-reference).
  </Tab>
</Tabs>

## 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.

```yaml maverics.yaml theme={null}
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.

## Related Pages

<CardGroup cols={2}>
  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Token Brokering" icon="key-skeleton" href="/reference/orchestrator/experimental/token-brokering">
    RFC 8693 token exchange for downstream APIs
  </Card>

  <Card title="Generic OIDC" icon="openid" href="/reference/orchestrator/identity-fabric/custom-oidc">
    Generic OpenID Connect connector
  </Card>

  <Card title="Generic SAML" icon="file-shield" href="/reference/orchestrator/identity-fabric/custom-saml">
    Generic SAML 2.0 connector
  </Card>
</CardGroup>