customProvider

customProvider builds a complete OAuthConfig 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 fits, for any IdP that publishes discovery metadata and signs JWT access tokens.

Example

server.ts

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

customProvider(opts: CustomProviderOptions): Promise<OAuthConfig>;

Parameters

`opts`

type CustomProviderOptions = {
  issuer: string;
  audience?: 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. 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` 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`; a token missing one gets a 403.
`metadataOverrides`	Adjusts advertised metadata only.

Returns

An OAuthProvider: a deferred OAuthConfig you pass to the 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 by hand.

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

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 for opaque tokens. Either way the oauth field mounts the same endpoints.

Connect an Identity Provider

Set up sign-in with a hosted provider

Authenticate Users

Add sign-in to your app end to end

Skybridge

Pass the config to the oauth field

Server

Auth

Identity Providers

Hooks

Utilities

Types

Low-level

Example

Signature

Parameters

`opts`

Returns

Connect an Identity Provider

Authenticate Users

Skybridge

​Example

​Signature

​Parameters

​opts

​Returns

Connect an Identity Provider

Authenticate Users

Skybridge

Example

Signature

Parameters

`opts`

Returns