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

# customProvider

> Wire OAuth from any IdP's discovery document

`customProvider` builds a complete [`OAuthConfig`](#returns) from an identity provider's OAuth discovery document: it reads the provider's metadata at boot and verifies access tokens against its JWKS. Reach for it when no [branded provider](https://docs.skybridge.tech/api-reference/workos-provider.md) fits, for any IdP that publishes [discovery metadata](https://datatracker.ietf.org/doc/html/rfc8414) and signs JWT access tokens.

## Example

```ts server.ts highlight={1,6-11} theme={null}
import { Skybridge, customProvider } from "skybridge/server";

export const app = new Skybridge({
  name: "personal-shopper",
  version: "0.0.1",
  oauth: customProvider({
    issuer: "https://auth.myshop.com",
    audience: process.env.SERVER_URL,
    scopes: ["openid", "profile", "checkout"],
    requiredScopes: ["openid"],
  }),
  handler,
});
```

`customProvider` fetches `https://auth.myshop.com`'s discovery document when the app starts, then the [`oauth`](https://docs.skybridge.tech/api-reference/skybridge#oauth) field mounts the well-known metadata and JWKS bearer verification on `/mcp`. `audience` is the value the IdP binds into the token's `aud` claim, here this server's public URL.

## Signature

```ts theme={null}
customProvider(opts: CustomProviderOptions): Promise<OAuthConfig>;
```

## Parameters

### `opts`

```ts theme={null}
type CustomProviderOptions = {
  issuer: string;
  audience?: string | string[];
  baseUrl?: string;
  serverUrl?: string;
  scopes?: string[];
  requiredScopes?: string[];
  metadataOverrides?: Omit<Partial<OAuthMetadata>, "issuer">;
};
```

| Field | Description |
| - | - |
| `issuer` | The only required option: the IdP base URL whose discovery document is fetched at boot. It must serve a `jwks_uri`, or the call throws. |
| `audience` | Checked against each token's `aud` claim. Pass several, say a local port and a dev tunnel URL, when the server is reached at more than one URL: a token passes when its `aud` matches any of them. Omit it only for an IdP that binds no audience (Clerk): the `aud` check is then skipped. |
| `baseUrl` | This server's public URL. Set it and the resource URLs are baked once at boot; omit it and they resolve per request from the `x-forwarded-host` / `x-forwarded-proto` / `host` headers. |
| `serverUrl` | Advertises this server as the authorization server: the served AS metadata `issuer` and the PRM `authorization_servers` use this URL instead of the IdP's, while verification still trusts the IdP's real `iss`. Needed when this server must sit in the auth path, as [`auth0Provider`](https://docs.skybridge.tech/api-reference/auth0-provider) does, or behind the Alpic DCR proxy. |
| `scopes` | Scopes advertised in the served metadata; defaults to the IdP's. |
| `requiredScopes` | Server-wide scope floor enforced before any handler, layered under each tool's [`securitySchemes`](https://docs.skybridge.tech/api-reference/register-tool#securityschemes); a token missing one gets a 403. |
| `metadataOverrides` | Adjusts advertised metadata only. |

## Returns

An `OAuthProvider`: a deferred `OAuthConfig` you pass to the [`oauth`](https://docs.skybridge.tech/api-reference/skybridge#oauth) field. Discovery is a network call, so it runs in `resolve()` at `run()`, not when your module is imported. Call `resolve()` yourself when wiring [`requireBearerAuth`](https://docs.skybridge.tech/api-reference/require-bearer-auth) by hand.

```ts theme={null}
type OAuthProvider<TExtra = Record<string, unknown>> = {
  resolve: () => Promise<OAuthConfig<TExtra>>;
};
```

```ts theme={null}
type OAuthConfig<TExtra = Record<string, unknown>> = {
  baseUrl?: string;
  oauthMetadata: OAuthMetadata;
  scopesSupported?: string[];
  requiredScopes?: string[];
  verifier: TokenVerifier<TExtra>;
};
```

| Field | Description |
| - | - |
| `baseUrl` | Echoes the `baseUrl` option. |
| `oauthMetadata` | AS metadata served at `/.well-known/oauth-authorization-server`. |
| `verifier` | Checks each bearer token, and carries the claim type handlers receive. |
| `scopesSupported` | Scopes advertised in protected-resource metadata. |
| `requiredScopes` | Server-wide required-scope floor. |

`TExtra` is the claim shape the verifier resolves with, and the server reads it from here, so handlers get `extra.http?.authInfo?.extra` typed without declaring anything. Pass it as a type argument to name claims your IdP sends: `customProvider<{ subject?: string; email?: string }>({ ... })`.

Build this object by hand only to wire an IdP whose metadata `customProvider` can't discover. Supply a `verifier`, from `createJwksVerifier({ issuer, jwksUri })` for JWTs or your own [`TokenVerifier`](https://docs.skybridge.tech/api-reference/verifier) for opaque tokens. Either way the [`oauth`](https://docs.skybridge.tech/api-reference/skybridge#oauth) field mounts the same endpoints.

> [card] [Connect an Identity Provider](https://docs.skybridge.tech/guides/auth-providers.md)
>
> Set up sign-in with a hosted provider

> [card] [Authenticate Users](https://docs.skybridge.tech/build/auth.md)
>
> Add sign-in to your app end to end

> [card] [Skybridge](https://docs.skybridge.tech/api-reference/skybridge.md)
>
> Pass the config to the oauth field


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.