From fb7b3671771b0e5c134ce5847eb4decd8bd1a36e Mon Sep 17 00:00:00 2001 From: Jay V Date: Mon, 6 Jan 2025 21:11:56 -0500 Subject: [PATCH] tsdoc providers --- packages/openauth/src/provider/apple.ts | 59 +++-- packages/openauth/src/provider/cognito.ts | 55 ++++ packages/openauth/src/provider/discord.ts | 35 ++- packages/openauth/src/provider/facebook.ts | 67 ++++- packages/openauth/src/provider/github.ts | 35 ++- packages/openauth/src/provider/google.ts | 67 ++++- packages/openauth/src/provider/jumpcloud.ts | 35 ++- packages/openauth/src/provider/keycloak.ts | 56 +++- packages/openauth/src/provider/microsoft.ts | 77 +++++- packages/openauth/src/provider/oauth2.ts | 56 ++++ packages/openauth/src/provider/oidc.ts | 36 +++ packages/openauth/src/provider/slack.ts | 72 ++++-- packages/openauth/src/provider/spotify.ts | 35 ++- packages/openauth/src/provider/twitch.ts | 35 ++- packages/openauth/src/provider/x.ts | 35 ++- packages/openauth/src/provider/yahoo.ts | 35 ++- www/astro.config.mjs | 16 +- www/generate.ts | 127 ++++++++-- www/src/content/docs/docs/provider/apple.mdx | 58 +++-- .../content/docs/docs/provider/cognito.mdx | 160 ++++++++++++ .../content/docs/docs/provider/discord.mdx | 126 +++++++++ .../content/docs/docs/provider/facebook.mdx | 220 ++++++++++++++++ www/src/content/docs/docs/provider/github.mdx | 126 +++++++++ www/src/content/docs/docs/provider/google.mdx | 183 +++++++++++++- .../content/docs/docs/provider/jumpcloud.mdx | 126 +++++++++ .../content/docs/docs/provider/keycloak.mdx | 163 ++++++++++++ .../content/docs/docs/provider/microsoft.mdx | 239 ++++++++++++++++++ www/src/content/docs/docs/provider/oauth2.mdx | 160 ++++++++++++ www/src/content/docs/docs/provider/oidc.mdx | 115 +++++++++ www/src/content/docs/docs/provider/slack.mdx | 144 +++++++++++ .../content/docs/docs/provider/spotify.mdx | 126 +++++++++ www/src/content/docs/docs/provider/twitch.mdx | 126 +++++++++ www/src/content/docs/docs/provider/x.mdx | 126 +++++++++ www/src/content/docs/docs/provider/yahoo.mdx | 126 +++++++++ 34 files changed, 3135 insertions(+), 122 deletions(-) create mode 100644 www/src/content/docs/docs/provider/cognito.mdx create mode 100644 www/src/content/docs/docs/provider/discord.mdx create mode 100644 www/src/content/docs/docs/provider/facebook.mdx create mode 100644 www/src/content/docs/docs/provider/github.mdx create mode 100644 www/src/content/docs/docs/provider/jumpcloud.mdx create mode 100644 www/src/content/docs/docs/provider/keycloak.mdx create mode 100644 www/src/content/docs/docs/provider/microsoft.mdx create mode 100644 www/src/content/docs/docs/provider/oauth2.mdx create mode 100644 www/src/content/docs/docs/provider/oidc.mdx create mode 100644 www/src/content/docs/docs/provider/slack.mdx create mode 100644 www/src/content/docs/docs/provider/spotify.mdx create mode 100644 www/src/content/docs/docs/provider/twitch.mdx create mode 100644 www/src/content/docs/docs/provider/x.mdx create mode 100644 www/src/content/docs/docs/provider/yahoo.mdx diff --git a/packages/openauth/src/provider/apple.ts b/packages/openauth/src/provider/apple.ts index bd191542..a12bd6fc 100644 --- a/packages/openauth/src/provider/apple.ts +++ b/packages/openauth/src/provider/apple.ts @@ -1,28 +1,33 @@ /** - * This is the Apple provider. - * - * Use this provider to authenticate with Apple. + * Use this provider to authenticate with Apple. Supports both OAuth2 and OIDC. * * #### Using OAuth * - * ```ts - * import { AppleProvider } from "@openauthjs/openauth/provider/apple"; + * ```ts {5-8} + * import { AppleProvider } from "@openauthjs/openauth/provider/apple" * - * AppleProvider({ - * clientId: "1234567890", - * clientSecret: "0987654321", - * }); + * export default issuer({ + * providers: { + * apple: AppleProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) * ``` * * #### Using OIDC * - * ```ts - * import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple"; + * ```ts {5-7} + * import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple" * - * AppleOidcProvider({ - * clientId: "1234567890", - * clientSecret: "0987654321", - * }); + * export default issuer({ + * providers: { + * apple: AppleOidcProvider({ + * clientId: "1234567890" + * }) + * } + * }) * ``` * * @packageDocumentation @@ -31,18 +36,19 @@ import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" import { OidcProvider, OidcWrappedConfig } from "./oidc.js" -export interface AppleConfig extends Oauth2WrappedConfig {} -export interface AppleOidcConfig extends OidcWrappedConfig {} +export interface AppleConfig extends Oauth2WrappedConfig { } +export interface AppleOidcConfig extends OidcWrappedConfig { } /** - * This function creates an Apple OAuth2 provider. - * @param config - The configuration for the provider. + * Create an Apple OAuth2 provider. + * + * @param config - The config for the provider. * @example * ```ts * AppleProvider({ * clientId: "1234567890", - * clientSecret: "0987654321", - * }); + * clientSecret: "0987654321" + * }) * ``` */ export function AppleProvider(config: AppleConfig) { @@ -57,13 +63,16 @@ export function AppleProvider(config: AppleConfig) { } /** - * This function creates an Apple OIDC provider. + * Create an Apple OIDC provider. + * + * This is useful if you just want to verify the user's email address. + * + * @param config - The config for the provider. * @example * ```ts * AppleOidcProvider({ - * clientId: "1234567890", - * clientSecret: "0987654321", - * }); + * clientId: "1234567890" + * }) * ``` */ export function AppleOidcProvider(config: AppleOidcConfig) { diff --git a/packages/openauth/src/provider/cognito.ts b/packages/openauth/src/provider/cognito.ts index a350305a..446d75b1 100644 --- a/packages/openauth/src/provider/cognito.ts +++ b/packages/openauth/src/provider/cognito.ts @@ -1,10 +1,65 @@ +/** + * Use this provider to authenticate with a Cognito OAuth endpoint. + * + * ```ts {5-10} + * import { CognitoProvider } from "@openauthjs/openauth/provider/cognito" + * + * export default issuer({ + * providers: { + * cognito: CognitoProvider({ + * domain: "your-domain.auth.us-east-1.amazoncognito.com", + * region: "us-east-1", + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" export interface CognitoConfig extends Oauth2WrappedConfig { + /** + * The domain of the Cognito User Pool. + * + * @example + * ```ts + * { + * domain: "your-domain.auth.us-east-1.amazoncognito.com" + * } + * ``` + */ domain: string + /** + * The region the Cognito User Pool is in. + * + * @example + * ```ts + * { + * region: "us-east-1" + * } + * ``` + */ region: string } +/** + * Create a Cognito OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * CognitoProvider({ + * domain: "your-domain.auth.us-east-1.amazoncognito.com", + * region: "us-east-1", + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ export function CognitoProvider(config: CognitoConfig) { const domain = `${config.domain}.auth.${config.region}.amazoncognito.com` diff --git a/packages/openauth/src/provider/discord.ts b/packages/openauth/src/provider/discord.ts index bc596e70..933fa22e 100644 --- a/packages/openauth/src/provider/discord.ts +++ b/packages/openauth/src/provider/discord.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with Discord. + * + * ```ts {5-8} + * import { DiscordProvider } from "@openauthjs/openauth/provider/discord" + * + * export default issuer({ + * providers: { + * discord: DiscordProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" -export function DiscordProvider(config: Oauth2WrappedConfig) { +export interface DiscordConfig extends Oauth2WrappedConfig { } + +/** + * Create a Discord OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * DiscordProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function DiscordProvider(config: DiscordConfig) { return Oauth2Provider({ type: "discord", ...config, diff --git a/packages/openauth/src/provider/facebook.ts b/packages/openauth/src/provider/facebook.ts index b1df6c79..839aa2f0 100644 --- a/packages/openauth/src/provider/facebook.ts +++ b/packages/openauth/src/provider/facebook.ts @@ -1,7 +1,57 @@ +/** + * Use this provider to authenticate with Facebook. Supports both OAuth2 and OIDC. + * + * #### Using OAuth + * + * ```ts {5-8} + * import { FacebookProvider } from "@openauthjs/openauth/provider/facebook" + * + * export default issuer({ + * providers: { + * facebook: FacebookProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * #### Using OIDC + * + * ```ts {5-7} + * import { FacebookOidcProvider } from "@openauthjs/openauth/provider/facebook" + * + * export default issuer({ + * providers: { + * facebook: FacebookOidcProvider({ + * clientId: "1234567890" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" import { OidcProvider, OidcWrappedConfig } from "./oidc.js" -export function FacebookProvider(config: Oauth2WrappedConfig) { +export interface FacebookConfig extends Oauth2WrappedConfig { } +export interface FacebookOidcConfig extends OidcWrappedConfig { } + +/** + * Create a Facebook OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * FacebookProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function FacebookProvider(config: FacebookConfig) { return Oauth2Provider({ ...config, type: "facebook", @@ -12,7 +62,20 @@ export function FacebookProvider(config: Oauth2WrappedConfig) { }) } -export function FacebookOidcProvider(config: OidcWrappedConfig) { +/** + * Create a Facebook OIDC provider. + * + * This is useful if you just want to verify the user's email address. + * + * @param config - The config for the provider. + * @example + * ```ts + * FacebookOidcProvider({ + * clientId: "1234567890" + * }) + * ``` + */ +export function FacebookOidcProvider(config: FacebookOidcConfig) { return OidcProvider({ ...config, type: "facebook", diff --git a/packages/openauth/src/provider/github.ts b/packages/openauth/src/provider/github.ts index 99ef9d57..c0532318 100644 --- a/packages/openauth/src/provider/github.ts +++ b/packages/openauth/src/provider/github.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with Github. + * + * ```ts {5-8} + * import { GithubProvider } from "@openauthjs/openauth/provider/github" + * + * export default issuer({ + * providers: { + * github: GithubProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" -export function GithubProvider(config: Oauth2WrappedConfig) { +export interface GithubConfig extends Oauth2WrappedConfig { } + +/** + * Create a Github OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * GithubProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function GithubProvider(config: GithubConfig) { return Oauth2Provider({ ...config, type: "github", diff --git a/packages/openauth/src/provider/google.ts b/packages/openauth/src/provider/google.ts index d3fd226b..a9b4ece2 100644 --- a/packages/openauth/src/provider/google.ts +++ b/packages/openauth/src/provider/google.ts @@ -1,7 +1,57 @@ +/** + * Use this provider to authenticate with Google. Supports both OAuth2 and OIDC. + * + * #### Using OAuth + * + * ```ts {5-8} + * import { GoogleProvider } from "@openauthjs/openauth/provider/google" + * + * export default issuer({ + * providers: { + * google: GoogleProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * #### Using OIDC + * + * ```ts {5-7} + * import { GoogleOidcProvider } from "@openauthjs/openauth/provider/google" + * + * export default issuer({ + * providers: { + * google: GoogleOidcProvider({ + * clientId: "1234567890" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" import { OidcProvider, OidcWrappedConfig } from "./oidc.js" -export function GoogleProvider(config: Oauth2WrappedConfig) { +export interface GoogleConfig extends Oauth2WrappedConfig { } +export interface GoogleOidcConfig extends OidcWrappedConfig { } + +/** + * Create a Google OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * GoogleProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function GoogleProvider(config: GoogleConfig) { return Oauth2Provider({ ...config, type: "google", @@ -12,7 +62,20 @@ export function GoogleProvider(config: Oauth2WrappedConfig) { }) } -export function GoogleOidcProvider(config: OidcWrappedConfig) { +/** + * Create a Google OIDC provider. + * + * This is useful if you just want to verify the user's email address. + * + * @param config - The config for the provider. + * @example + * ```ts + * GoogleOidcProvider({ + * clientId: "1234567890" + * }) + * ``` + */ +export function GoogleOidcProvider(config: GoogleOidcConfig) { return OidcProvider({ ...config, type: "google", diff --git a/packages/openauth/src/provider/jumpcloud.ts b/packages/openauth/src/provider/jumpcloud.ts index 76cea4dc..f5df4c4a 100644 --- a/packages/openauth/src/provider/jumpcloud.ts +++ b/packages/openauth/src/provider/jumpcloud.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with JumpCloud. + * + * ```ts {5-8} + * import { JumpCloudProvider } from "@openauthjs/openauth/provider/jumpcloud" + * + * export default issuer({ + * providers: { + * jumpcloud: JumpCloudProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" -export function JumpCloudProvider(config: Oauth2WrappedConfig) { +export interface JumpCloudConfig extends Oauth2WrappedConfig { } + +/** + * Create a JumpCloud OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * JumpCloudProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function JumpCloudProvider(config: JumpCloudConfig) { return Oauth2Provider({ type: "jumpcloud", ...config, diff --git a/packages/openauth/src/provider/keycloak.ts b/packages/openauth/src/provider/keycloak.ts index ddae365a..062228ec 100644 --- a/packages/openauth/src/provider/keycloak.ts +++ b/packages/openauth/src/provider/keycloak.ts @@ -1,30 +1,68 @@ -import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" - /** - * Configuration options for Keycloak integration. + * Use this provider to authenticate with a Keycloak server. + * + * ```ts {5-10} + * import { KeycloakProvider } from "@openauthjs/openauth/provider/keycloak" * - * This interface extends the `Oauth2WrappedConfig` and includes additional - * properties specific to Keycloak, such as the base URL and realm. It is used - * to configure the `KeycloakProvider`. + * export default issuer({ + * providers: { + * keycloak: KeycloakProvider({ + * baseUrl: "https://your-keycloak-domain", + * realm: "your-realm", + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation */ + +import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" + export interface KeycloakConfig extends Oauth2WrappedConfig { /** * The base URL of the Keycloak server. * - * Example: `https://your-keycloak-domain` + * @example + * ```ts + * { + * baseUrl: "https://your-keycloak-domain" + * } + * ``` */ baseUrl: string /** * The realm in the Keycloak server to authenticate against. * * A realm in Keycloak is like a tenant or namespace that manages a set of - * users, credentials, roles, and groups. Each realm is independent of others. + * users, credentials, roles, and groups. * - * Example: `your-realm` + * @example + * ```ts + * { + * realm: "your-realm" + * } + * ``` */ realm: string } +/** + * Create a Keycloak OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * KeycloakProvider({ + * baseUrl: "https://your-keycloak-domain", + * realm: "your-realm", + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ export function KeycloakProvider(config: KeycloakConfig) { const baseConfig = { ...config, diff --git a/packages/openauth/src/provider/microsoft.ts b/packages/openauth/src/provider/microsoft.ts index 8ae28804..ee60e333 100644 --- a/packages/openauth/src/provider/microsoft.ts +++ b/packages/openauth/src/provider/microsoft.ts @@ -1,10 +1,72 @@ +/** + * Use this provider to authenticate with Microsoft. Supports both OAuth2 and OIDC. + * + * #### Using OAuth + * + * ```ts {5-9} + * import { MicrosoftProvider } from "@openauthjs/openauth/provider/microsoft" + * + * export default issuer({ + * providers: { + * microsoft: MicrosoftProvider({ + * tenant: "1234567890", + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * #### Using OIDC + * + * ```ts {5-7} + * import { MicrosoftOidcProvider } from "@openauthjs/openauth/provider/microsoft" + * + * export default issuer({ + * providers: { + * microsoft: MicrosoftOidcProvider({ + * clientId: "1234567890" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" import { OidcProvider, OidcWrappedConfig } from "./oidc.js" export interface MicrosoftConfig extends Oauth2WrappedConfig { + /** + * The tenant ID of the Microsoft account. + * + * This is usually the same as the client ID. + * + * @example + * ```ts + * { + * tenant: "1234567890" + * } + * ``` + */ tenant: string } +export interface MicrosoftOidcConfig extends OidcWrappedConfig { } +/** + * Create a Microsoft OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * MicrosoftProvider({ + * tenant: "1234567890", + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ export function MicrosoftProvider(config: MicrosoftConfig) { return Oauth2Provider({ ...config, @@ -16,7 +78,20 @@ export function MicrosoftProvider(config: MicrosoftConfig) { }) } -export function MicrosoftOidcProvider(config: OidcWrappedConfig) { +/** + * Create a Microsoft OIDC provider. + * + * This is useful if you just want to verify the user's email address. + * + * @param config - The config for the provider. + * @example + * ```ts + * MicrosoftOidcProvider({ + * clientId: "1234567890" + * }) + * ``` + */ +export function MicrosoftOidcProvider(config: MicrosoftOidcConfig) { return OidcProvider({ ...config, type: "microsoft", diff --git a/packages/openauth/src/provider/oauth2.ts b/packages/openauth/src/provider/oauth2.ts index 837efb27..79e58b3a 100644 --- a/packages/openauth/src/provider/oauth2.ts +++ b/packages/openauth/src/provider/oauth2.ts @@ -1,3 +1,27 @@ +/** + * Use this to connect authentication providers that support OAuth 2.0. + * + * ```ts {5-12} + * import { Oauth2Provider } from "@openauthjs/openauth/provider/oauth2" + * + * export default issuer({ + * providers: { + * oauth2: Oauth2Provider({ + * clientId: "1234567890", + * clientSecret: "0987654321", + * endpoint: { + * authorization: "https://auth.myserver.com/authorize", + * token: "https://auth.myserver.com/token" + * } + * }) + * } + * }) + * ``` + * + * + * @packageDocumentation + */ + import { OauthError } from "../error.js" import { getRelativeUrl } from "../util.js" import { Provider } from "./provider.js" @@ -24,10 +48,36 @@ export interface Oauth2Config { * The client secret. * * This is a private key that's used to authenticate your app. It should be kept secret. + * + * @example + * ```ts + * { + * clientSecret: "0987654321" + * } + * ``` */ clientSecret: string + /** + * The URLs of the authorization and token endpoints. + * + * @example + * ```ts + * { + * endpoint: { + * authorization: "https://auth.myserver.com/authorize", + * token: "https://auth.myserver.com/token" + * } + * } + * ``` + */ endpoint: { + /** + * The URL of the authorization endpoint. + */ authorization: string + /** + * The URL of the token endpoint. + */ token: string } /** @@ -56,8 +106,14 @@ export interface Oauth2Config { query?: Record } +/** + * @internal + */ export type Oauth2WrappedConfig = Omit +/** + * @internal + */ export interface Oauth2Token { access: string refresh: string diff --git a/packages/openauth/src/provider/oidc.ts b/packages/openauth/src/provider/oidc.ts index 6a5dbdb8..72a7a473 100644 --- a/packages/openauth/src/provider/oidc.ts +++ b/packages/openauth/src/provider/oidc.ts @@ -1,3 +1,23 @@ +/** + * Use this to connect authentication providers that support OIDC. + * + * ```ts {5-8} + * import { OidcProvider } from "@openauthjs/openauth/provider/oidc" + * + * export default issuer({ + * providers: { + * oauth2: OidcProvider({ + * clientId: "1234567890", + * issuer: "https://auth.myserver.com" + * }) + * } + * }) + * ``` + * + * + * @packageDocumentation + */ + import { createLocalJWKSet, JSONWebKeySet, jwtVerify } from "jose" import { WellKnown } from "../client.js" import { OauthError } from "../error.js" @@ -23,6 +43,16 @@ export interface OidcConfig { * ``` */ clientID: string + /** + * The URL of your authorization server. + * + * @example + * ```ts + * { + * issuer: "https://auth.myserver.com" + * } + * ``` + */ issuer: string /** * A list of OIDC scopes that you want to request. @@ -49,6 +79,9 @@ export interface OidcConfig { query?: Record } +/** + * @internal + */ export type OidcWrappedConfig = Omit interface ProviderState { @@ -57,6 +90,9 @@ interface ProviderState { redirect: string } +/** + * @internal + */ export interface IdTokenResponse { idToken: string claims: Record diff --git a/packages/openauth/src/provider/slack.ts b/packages/openauth/src/provider/slack.ts index 63bf214f..539ac162 100644 --- a/packages/openauth/src/provider/slack.ts +++ b/packages/openauth/src/provider/slack.ts @@ -1,43 +1,59 @@ -import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" - /** - * Represents the possible OAuth scopes for the Slack provider. + * Use this provider to authenticate with Slack. * - * @typedef {("openid" | "email" | "profile")} Scopes + * ```ts {5-10} + * import { SlackProvider } from "@openauthjs/openauth/provider/slack" * - * @property {"openid"} openid - Grants permission to use OpenID Connect to verify the user's identity. - * @property {"email"} email - Grants permission to access the user's email address. - * @property {"profile"} profile - Grants permission to access the user's profile information. + * export default issuer({ + * providers: { + * slack: SlackProvider({ + * team: "T1234567890", + * clientId: "1234567890", + * clientSecret: "0987654321", + * scopes: ["openid", "email", "profile"] + * }) + * } + * }) + * ``` * - * @see {@link https://api.slack.com/authentication/sign-in-with-slack} + * @packageDocumentation */ -type Scope = "openid" | "email" | "profile" -/** - * @interface SlackConfig - * @extends Oauth2WrappedConfig - * - * @property {string} team - The workspace the user is intending to authenticate. If that workspace - * has been previously authenticated, the user will be signed in directly, bypassing the consent screen. - * @property {Scopes[]} scopes - The scopes to request from the user. - * - * @see {@link https://api.slack.com/authentication/sign-in-with-slack} - */ +import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" + export interface SlackConfig extends Oauth2WrappedConfig { + /** + * The workspace the user is intending to authenticate. + * + * If that workspace has been previously authenticated, the user will be signed in directly, + * bypassing the consent screen. + */ team: string - // NOTE: We overrode the scopes to be constrained to the Slack scopes. Scopes will be - // redundant with different providers, we may want to create a larger union type - // and use `Extract` or `Exclude` to constrain the scopes. - scopes: Scope[] + /** + * The scopes to request from the user. + * + * | Scope | Description | + * |-|-| + * | `email` | Grants permission to access the user's email address. | + * | `profile` | Grants permission to access the user's profile information. | + * | `openid` | Grants permission to use OpenID Connect to verify the user's identity. | + */ + scopes: ("email" | "profile" | "openid")[] } /** - * Creates an OAuth2 provider for Slack authentication. - * - * This function configures an OAuth2 provider specifically for Slack by - * providing the necessary authorization and token endpoints. + * Creates a [Slack OAuth2 provider](https://api.slack.com/authentication/sign-in-with-slack). * - * @see {@link https://api.slack.com/authentication/sign-in-with-slack} + * @param {SlackConfig} config - The config for the provider. + * @example + * ```ts + * SlackProvider({ + * team: "T1234567890", + * clientId: "1234567890", + * clientSecret: "0987654321", + * scopes: ["openid", "email", "profile"] + * }) + * ``` */ export function SlackProvider(config: SlackConfig) { return Oauth2Provider({ diff --git a/packages/openauth/src/provider/spotify.ts b/packages/openauth/src/provider/spotify.ts index 5b62120f..d4887313 100644 --- a/packages/openauth/src/provider/spotify.ts +++ b/packages/openauth/src/provider/spotify.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with Spotify. + * + * ```ts {5-8} + * import { SpotifyProvider } from "@openauthjs/openauth/provider/spotify" + * + * export default issuer({ + * providers: { + * spotify: SpotifyProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, type Oauth2WrappedConfig } from "./oauth2.js" -export function SpotifyProvider(config: Oauth2WrappedConfig) { +export interface SpotifyConfig extends Oauth2WrappedConfig { } + +/** + * Create a Spotify OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * SpotifyProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function SpotifyProvider(config: SpotifyConfig) { return Oauth2Provider({ ...config, type: "spotify", diff --git a/packages/openauth/src/provider/twitch.ts b/packages/openauth/src/provider/twitch.ts index b018f0b7..9ee37352 100644 --- a/packages/openauth/src/provider/twitch.ts +++ b/packages/openauth/src/provider/twitch.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with Twitch. + * + * ```ts {5-8} + * import { TwitchProvider } from "@openauthjs/openauth/provider/twitch" + * + * export default issuer({ + * providers: { + * twitch: TwitchProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" -export function TwitchProvider(config: Oauth2WrappedConfig) { +export interface TwitchConfig extends Oauth2WrappedConfig { } + +/** + * Create a Twitch OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * TwitchProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function TwitchProvider(config: TwitchConfig) { return Oauth2Provider({ type: "twitch", ...config, diff --git a/packages/openauth/src/provider/x.ts b/packages/openauth/src/provider/x.ts index 9d69e284..a747f0bf 100644 --- a/packages/openauth/src/provider/x.ts +++ b/packages/openauth/src/provider/x.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with X.com. + * + * ```ts {5-8} + * import { XProvider } from "@openauthjs/openauth/provider/x" + * + * export default issuer({ + * providers: { + * x: XProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" -export function XProvider(config: Oauth2WrappedConfig) { +export interface XProviderConfig extends Oauth2WrappedConfig { } + +/** + * Create a X.com OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * XProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function XProvider(config: XProviderConfig) { return Oauth2Provider({ ...config, type: "x", diff --git a/packages/openauth/src/provider/yahoo.ts b/packages/openauth/src/provider/yahoo.ts index f6ca19a9..a4e017fe 100644 --- a/packages/openauth/src/provider/yahoo.ts +++ b/packages/openauth/src/provider/yahoo.ts @@ -1,6 +1,39 @@ +/** + * Use this provider to authenticate with Yahoo. + * + * ```ts {5-8} + * import { YahooProvider } from "@openauthjs/openauth/provider/yahoo" + * + * export default issuer({ + * providers: { + * yahoo: YahooProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * } + * }) + * ``` + * + * @packageDocumentation + */ + import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js" -export function YahooProvider(config: Oauth2WrappedConfig) { +export interface YahooConfig extends Oauth2WrappedConfig { } + +/** + * Create a Yahoo OAuth2 provider. + * + * @param config - The config for the provider. + * @example + * ```ts + * YahooProvider({ + * clientId: "1234567890", + * clientSecret: "0987654321" + * }) + * ``` + */ +export function YahooProvider(config: YahooConfig) { return Oauth2Provider({ ...config, type: "yahoo", diff --git a/www/astro.config.mjs b/www/astro.config.mjs index c59ce93f..82fd0749 100644 --- a/www/astro.config.mjs +++ b/www/astro.config.mjs @@ -80,17 +80,31 @@ export default defineConfig({ label: "Core", items: [ "docs/client", - { label: "Subject", slug: "docs/subject" }, { label: "Issuer", slug: "docs/issuer" }, + { label: "Subject", slug: "docs/subject" }, ], }, { label: "Providers", items: [ { label: "Code", slug: "docs/provider/code" }, + { label: "OIDC", slug: "docs/provider/oidc" }, + { label: "OAuth", slug: "docs/provider/oauth2" }, { label: "Apple", slug: "docs/provider/apple" }, + { label: "X.com", slug: "docs/provider/x" }, + { label: "Slack", slug: "docs/provider/slack" }, + { label: "Yahoo", slug: "docs/provider/yahoo" }, { label: "Google", slug: "docs/provider/google" }, + { label: "Github", slug: "docs/provider/github" }, + { label: "Twitch", slug: "docs/provider/twitch" }, + { label: "Spotify", slug: "docs/provider/spotify" }, + { label: "Cognito", slug: "docs/provider/cognito" }, + { label: "Discord", slug: "docs/provider/discord" }, + { label: "Facebook", slug: "docs/provider/facebook" }, + { label: "Keycloak", slug: "docs/provider/keycloak" }, { label: "Password", slug: "docs/provider/password" }, + { label: "Microsoft", slug: "docs/provider/microsoft" }, + { label: "JumpCloud", slug: "docs/provider/jumpcloud" }, ], }, { diff --git a/www/generate.ts b/www/generate.ts index 0b131fef..a78e5d5c 100644 --- a/www/generate.ts +++ b/www/generate.ts @@ -66,11 +66,86 @@ const FRONTMATTER: Record< description: "Reference doc for the `AppleProvider`.", editUrl: `${config.github}/blob/master/packages/openauth/src/provider/apple.ts`, }, + google: { + title: "GoogleProvider", + description: "Reference doc for the `GoogleProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/google.ts`, + }, + x: { + title: "XProvider", + description: "Reference doc for the `XProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/x.ts`, + }, + yahoo: { + title: "YahooProvider", + description: "Reference doc for the `YahooProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/yahoo.ts`, + }, + github: { + title: "GithubProvider", + description: "Reference doc for the `GithubProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/github.ts`, + }, + microsoft: { + title: "MicrosoftProvider", + description: "Reference doc for the `MicrosoftProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/microsoft.ts`, + }, password: { title: "PasswordProvider", description: "Reference doc for the `PasswordProvider`.", editUrl: `${config.github}/blob/master/packages/openauth/src/provider/password.ts`, }, + keycloak: { + title: "KeycloakProvider", + description: "Reference doc for the `KeycloakProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/keycloak.ts`, + }, + slack: { + title: "SlackProvider", + description: "Reference doc for the `SlackProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/slack.ts`, + }, + jumpcloud: { + title: "JumpCloudProvider", + description: "Reference doc for the `JumpCloudProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/jumpcloud.ts`, + }, + spotify: { + title: "SpotifyProvider", + description: "Reference doc for the `SpotifyProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/spotify.ts`, + }, + discord: { + title: "DiscordProvider", + description: "Reference doc for the `DiscordProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/discord.ts`, + }, + cognito: { + title: "CognitoProvider", + description: "Reference doc for the `CognitoProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/cognito.ts`, + }, + facebook: { + title: "FacebookProvider", + description: "Reference doc for the `FacebookProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/facebook.ts`, + }, + twitch: { + title: "TwitchProvider", + description: "Reference doc for the `TwitchProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/twitch.ts`, + }, + oidc: { + title: "OidcProvider", + description: "Reference doc for the `OidcProvider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/oidc.ts`, + }, + oauth2: { + title: "Oauth2Provider", + description: "Reference doc for the `Oauth2Provider`.", + editUrl: `${config.github}/blob/master/packages/openauth/src/provider/oauth2.ts`, + }, code: { title: "CodeProvider", description: "Reference doc for the `CodeProvider`.", @@ -398,13 +473,13 @@ function renderComment(comment?: TypeDoc.Comment) { // Otherwise render it as a comment ie. No domains configured tag.content.length === 1 && tag.content[0].kind === "code" ? `**Default** ${renderType( - new TypeDoc.IntrinsicType( - tag.content[0].text - .replace(/`/g, "") - .replace(/{/g, "{") - .replace(/}/g, "}"), - ), - )}` + new TypeDoc.IntrinsicType( + tag.content[0].text + .replace(/`/g, "") + .replace(/{/g, "{") + .replace(/}/g, "}"), + ), + )}` : `**Default** ${tag.content.map((c) => c.text)}`, ``, ] @@ -539,8 +614,8 @@ function renderType(type: TypeDoc.SomeType): Text { function renderArrayType(type: TypeDoc.ArrayType) { return type.elementType.type === "union" ? `(${renderType( - type.elementType, - )})[]` + type.elementType, + )})[]` : `${renderType(type.elementType)}[]` } function renderCallbackType(type: TypeDoc.ReflectionType) { @@ -638,17 +713,17 @@ function flattenNestedTypes( { prefix, subType, depth }, ...(subType.kind === TypeDoc.ReflectionKind.Property ? flattenNestedTypes( - subType.type!, - `${prefix}.${subType.name}`, - depth + 1, - ) + subType.type!, + `${prefix}.${subType.name}`, + depth + 1, + ) : []), ...(subType.kind === TypeDoc.ReflectionKind.Accessor ? flattenNestedTypes( - subType.getSignature?.type!, - `${prefix}.${subType.name}`, - depth + 1, - ) + subType.getSignature?.type!, + `${prefix}.${subType.name}`, + depth + 1, + ) : []), ]) } @@ -669,7 +744,7 @@ function saveFile(moduleName: string, content: any[]) { function configureLogger() { if (process.env.DEBUG) return - console.debug = () => {} + console.debug = () => { } } async function build() { @@ -687,7 +762,21 @@ async function build() { "../packages/openauth/src/provider/code.ts", "../packages/openauth/src/provider/apple.ts", "../packages/openauth/src/provider/google.ts", + "../packages/openauth/src/provider/github.ts", "../packages/openauth/src/provider/password.ts", + "../packages/openauth/src/provider/oauth2.ts", + "../packages/openauth/src/provider/oidc.ts", + "../packages/openauth/src/provider/slack.ts", + "../packages/openauth/src/provider/spotify.ts", + "../packages/openauth/src/provider/twitch.ts", + "../packages/openauth/src/provider/yahoo.ts", + "../packages/openauth/src/provider/microsoft.ts", + "../packages/openauth/src/provider/keycloak.ts", + "../packages/openauth/src/provider/jumpcloud.ts", + "../packages/openauth/src/provider/facebook.ts", + "../packages/openauth/src/provider/discord.ts", + "../packages/openauth/src/provider/cognito.ts", + "../packages/openauth/src/provider/x.ts", "../packages/openauth/src/subject.ts", "../packages/openauth/src/ui/theme.ts", "../packages/openauth/src/ui/code.tsx", @@ -712,4 +801,4 @@ async function build() { return project } -async function generate() {} +async function generate() { } diff --git a/www/src/content/docs/docs/provider/apple.mdx b/www/src/content/docs/docs/provider/apple.mdx index 9c8f1d60..423c86cd 100644 --- a/www/src/content/docs/docs/provider/apple.mdx +++ b/www/src/content/docs/docs/provider/apple.mdx @@ -11,30 +11,35 @@ import InlineSection from '../../../../components/tsdoc/InlineSection.astro';
-This is the Apple provider. - -Use this provider to authenticate with Apple. +Use this provider to authenticate with Apple. Supports both OAuth2 and OIDC. #### Using OAuth -```ts -import { AppleProvider } from "@openauthjs/openauth/provider/apple"; +```ts {5-8} +import { AppleProvider } from "@openauthjs/openauth/provider/apple" -AppleProvider({ - clientId: "1234567890", - clientSecret: "0987654321", -}); +export default issuer({ + providers: { + apple: AppleProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) ``` #### Using OIDC -```ts -import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple"; +```ts {5-7} +import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple" -AppleOidcProvider({ - clientId: "1234567890", - clientSecret: "0987654321", -}); +export default issuer({ + providers: { + apple: AppleOidcProvider({ + clientId: "1234567890" + }) + } +}) ```
--- @@ -49,16 +54,18 @@ AppleOidcProvider(config)
#### Parameters -

config [AppleOidcConfig](/docs/provider/apple#appleoidcconfig)

+The config for the provider.
**Returns** Provider -This function creates an Apple OIDC provider. +Create an Apple OIDC provider. + +This is useful if you just want to verify the user's email address. ```ts AppleOidcProvider({ - clientId: "1234567890", - clientSecret: "0987654321", -}); + clientId: "1234567890" +}) ``` ### AppleProvider @@ -71,17 +78,17 @@ AppleProvider(config)
#### Parameters -

config [AppleConfig](/docs/provider/apple#appleconfig)

-The configuration for the provider. +The config for the provider.
**Returns** Provider -This function creates an Apple OAuth2 provider. +Create an Apple OAuth2 provider. ```ts AppleProvider({ clientId: "1234567890", - clientSecret: "0987654321", -}); + clientSecret: "0987654321" +}) ``` ## AppleConfig @@ -119,6 +126,11 @@ This is just a string to identify your app. The client secret. This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` query? diff --git a/www/src/content/docs/docs/provider/cognito.mdx b/www/src/content/docs/docs/provider/cognito.mdx new file mode 100644 index 00000000..c7b7ee77 --- /dev/null +++ b/www/src/content/docs/docs/provider/cognito.mdx @@ -0,0 +1,160 @@ +--- +title: CognitoProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/cognito.ts +description: Reference doc for the `CognitoProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Cognito OAuth endpoint. + +```ts {5-10} +import { CognitoProvider } from "@openauthjs/openauth/provider/cognito" + +export default issuer({ + providers: { + cognito: CognitoProvider({ + domain: "your-domain.auth.us-east-1.amazoncognito.com", + region: "us-east-1", + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### CognitoProvider + +
+```ts +CognitoProvider(config) +``` +
+
+#### Parameters +-

config [CognitoConfig](/docs/provider/cognito#cognitoconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Cognito OAuth2 provider. +```ts +CognitoProvider({ + domain: "your-domain.auth.us-east-1.amazoncognito.com", + region: "us-east-1", + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## CognitoConfig + +
+-

[clientID](#cognitoconfig.clientid) string

+-

[clientSecret](#cognitoconfig.clientsecret) string

+-

[domain](#cognitoconfig.domain) string

+-

[query?](#cognitoconfig.query) Record<string, string>

+-

[region](#cognitoconfig.region) string

+-

[scopes](#cognitoconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +domain + +
+ +**Type** string + +
+The domain of the Cognito User Pool. +```ts +{ + domain: "your-domain.auth.us-east-1.amazoncognito.com" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +region + +
+ +**Type** string + +
+The region the Cognito User Pool is in. +```ts +{ + region: "us-east-1" +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/discord.mdx b/www/src/content/docs/docs/provider/discord.mdx new file mode 100644 index 00000000..1aa84fb5 --- /dev/null +++ b/www/src/content/docs/docs/provider/discord.mdx @@ -0,0 +1,126 @@ +--- +title: DiscordProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/discord.ts +description: Reference doc for the `DiscordProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Discord. + +```ts {5-8} +import { DiscordProvider } from "@openauthjs/openauth/provider/discord" + +export default issuer({ + providers: { + discord: DiscordProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### DiscordProvider + +
+```ts +DiscordProvider(config) +``` +
+
+#### Parameters +-

config [DiscordConfig](/docs/provider/discord#discordconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Discord OAuth2 provider. +```ts +DiscordProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## DiscordConfig + +
+-

[clientID](#discordconfig.clientid) string

+-

[clientSecret](#discordconfig.clientsecret) string

+-

[query?](#discordconfig.query) Record<string, string>

+-

[scopes](#discordconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/facebook.mdx b/www/src/content/docs/docs/provider/facebook.mdx new file mode 100644 index 00000000..cab8e5f2 --- /dev/null +++ b/www/src/content/docs/docs/provider/facebook.mdx @@ -0,0 +1,220 @@ +--- +title: FacebookProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/facebook.ts +description: Reference doc for the `FacebookProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Facebook. Supports both OAuth2 and OIDC. + +#### Using OAuth + +```ts {5-8} +import { FacebookProvider } from "@openauthjs/openauth/provider/facebook" + +export default issuer({ + providers: { + facebook: FacebookProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` + +#### Using OIDC + +```ts {5-7} +import { FacebookOidcProvider } from "@openauthjs/openauth/provider/facebook" + +export default issuer({ + providers: { + facebook: FacebookOidcProvider({ + clientId: "1234567890" + }) + } +}) +``` +
+--- +## Methods +### FacebookOidcProvider + +
+```ts +FacebookOidcProvider(config) +``` +
+
+#### Parameters +-

config [FacebookOidcConfig](/docs/provider/facebook#facebookoidcconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Facebook OIDC provider. + +This is useful if you just want to verify the user's email address. +```ts +FacebookOidcProvider({ + clientId: "1234567890" +}) +``` + +### FacebookProvider + +
+```ts +FacebookProvider(config) +``` +
+
+#### Parameters +-

config [FacebookConfig](/docs/provider/facebook#facebookconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Facebook OAuth2 provider. +```ts +FacebookProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## FacebookConfig + +
+-

[clientID](#facebookconfig.clientid) string

+-

[clientSecret](#facebookconfig.clientsecret) string

+-

[query?](#facebookconfig.query) Record<string, string>

+-

[scopes](#facebookconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +## FacebookOidcConfig + +
+-

[clientID](#facebookoidcconfig.clientid) string

+-

[query?](#facebookoidcconfig.query) Record<string, string>

+-

[scopes?](#facebookoidcconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + prompt: "consent" + } +} +``` + +scopes? + +
+ +**Type** string[] + +
+A list of OIDC scopes that you want to request. +```ts +{ + scopes: ["openid", "profile", "email"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/github.mdx b/www/src/content/docs/docs/provider/github.mdx new file mode 100644 index 00000000..2547cd44 --- /dev/null +++ b/www/src/content/docs/docs/provider/github.mdx @@ -0,0 +1,126 @@ +--- +title: GithubProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/github.ts +description: Reference doc for the `GithubProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Github. + +```ts {5-8} +import { GithubProvider } from "@openauthjs/openauth/provider/github" + +export default issuer({ + providers: { + github: GithubProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### GithubProvider + +
+```ts +GithubProvider(config) +``` +
+
+#### Parameters +-

config [GithubConfig](/docs/provider/github#githubconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Github OAuth2 provider. +```ts +GithubProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## GithubConfig + +
+-

[clientID](#githubconfig.clientid) string

+-

[clientSecret](#githubconfig.clientsecret) string

+-

[query?](#githubconfig.query) Record<string, string>

+-

[scopes](#githubconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/google.mdx b/www/src/content/docs/docs/provider/google.mdx index de7132cb..2f8349b1 100644 --- a/www/src/content/docs/docs/provider/google.mdx +++ b/www/src/content/docs/docs/provider/google.mdx @@ -1,7 +1,7 @@ --- -title: google -editUrl: false -description: A page for the google provider. +title: GoogleProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/google.ts +description: Reference doc for the `GoogleProvider`. --- import Segment from '../../../../components/tsdoc/Segment.astro'; @@ -11,6 +11,36 @@ import InlineSection from '../../../../components/tsdoc/InlineSection.astro';
+Use this provider to authenticate with Google. Supports both OAuth2 and OIDC. + +#### Using OAuth + +```ts {5-8} +import { GoogleProvider } from "@openauthjs/openauth/provider/google" + +export default issuer({ + providers: { + google: GoogleProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` + +#### Using OIDC + +```ts {5-7} +import { GoogleOidcProvider } from "@openauthjs/openauth/provider/google" + +export default issuer({ + providers: { + google: GoogleOidcProvider({ + clientId: "1234567890" + }) + } +}) +```
--- ## Methods @@ -23,11 +53,20 @@ GoogleOidcProvider(config)
#### Parameters --

config OidcWrappedConfig

+-

config [GoogleOidcConfig](/docs/provider/google#googleoidcconfig)

+The config for the provider.
**Returns** Provider +Create a Google OIDC provider. + +This is useful if you just want to verify the user's email address. +```ts +GoogleOidcProvider({ + clientId: "1234567890" +}) +``` ### GoogleProvider @@ -38,10 +77,144 @@ GoogleProvider(config)
#### Parameters --

config Oauth2WrappedConfig

+-

config [GoogleConfig](/docs/provider/google#googleconfig)

+The config for the provider.
**Returns** Provider +Create a Google OAuth2 provider. +```ts +GoogleProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## GoogleConfig + +
+-

[clientID](#googleconfig.clientid) string

+-

[clientSecret](#googleconfig.clientsecret) string

+-

[query?](#googleconfig.query) Record<string, string>

+-

[scopes](#googleconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +## GoogleOidcConfig + +
+-

[clientID](#googleoidcconfig.clientid) string

+-

[query?](#googleoidcconfig.query) Record<string, string>

+-

[scopes?](#googleoidcconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + prompt: "consent" + } +} +``` + +scopes? + +
+ +**Type** string[] + +
+A list of OIDC scopes that you want to request. +```ts +{ + scopes: ["openid", "profile", "email"] +} +```
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/jumpcloud.mdx b/www/src/content/docs/docs/provider/jumpcloud.mdx new file mode 100644 index 00000000..6faa9cbf --- /dev/null +++ b/www/src/content/docs/docs/provider/jumpcloud.mdx @@ -0,0 +1,126 @@ +--- +title: JumpCloudProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/jumpcloud.ts +description: Reference doc for the `JumpCloudProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with JumpCloud. + +```ts {5-8} +import { JumpCloudProvider } from "@openauthjs/openauth/provider/jumpcloud" + +export default issuer({ + providers: { + jumpcloud: JumpCloudProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### JumpCloudProvider + +
+```ts +JumpCloudProvider(config) +``` +
+
+#### Parameters +-

config [JumpCloudConfig](/docs/provider/jumpcloud#jumpcloudconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a JumpCloud OAuth2 provider. +```ts +JumpCloudProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## JumpCloudConfig + +
+-

[clientID](#jumpcloudconfig.clientid) string

+-

[clientSecret](#jumpcloudconfig.clientsecret) string

+-

[query?](#jumpcloudconfig.query) Record<string, string>

+-

[scopes](#jumpcloudconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/keycloak.mdx b/www/src/content/docs/docs/provider/keycloak.mdx new file mode 100644 index 00000000..1dce1433 --- /dev/null +++ b/www/src/content/docs/docs/provider/keycloak.mdx @@ -0,0 +1,163 @@ +--- +title: KeycloakProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/keycloak.ts +description: Reference doc for the `KeycloakProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with a Keycloak server. + +```ts {5-10} +import { KeycloakProvider } from "@openauthjs/openauth/provider/keycloak" + +export default issuer({ + providers: { + keycloak: KeycloakProvider({ + baseUrl: "https://your-keycloak-domain", + realm: "your-realm", + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### KeycloakProvider + +
+```ts +KeycloakProvider(config) +``` +
+
+#### Parameters +-

config [KeycloakConfig](/docs/provider/keycloak#keycloakconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Keycloak OAuth2 provider. +```ts +KeycloakProvider({ + baseUrl: "https://your-keycloak-domain", + realm: "your-realm", + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## KeycloakConfig + +
+-

[baseUrl](#keycloakconfig.baseurl) string

+-

[clientID](#keycloakconfig.clientid) string

+-

[clientSecret](#keycloakconfig.clientsecret) string

+-

[query?](#keycloakconfig.query) Record<string, string>

+-

[realm](#keycloakconfig.realm) string

+-

[scopes](#keycloakconfig.scopes) string[]

+
+ +baseUrl + +
+ +**Type** string + +
+The base URL of the Keycloak server. +```ts +{ + baseUrl: "https://your-keycloak-domain" +} +``` + +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +realm + +
+ +**Type** string + +
+The realm in the Keycloak server to authenticate against. + +A realm in Keycloak is like a tenant or namespace that manages a set of +users, credentials, roles, and groups. +```ts +{ + realm: "your-realm" +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/microsoft.mdx b/www/src/content/docs/docs/provider/microsoft.mdx new file mode 100644 index 00000000..a72036a4 --- /dev/null +++ b/www/src/content/docs/docs/provider/microsoft.mdx @@ -0,0 +1,239 @@ +--- +title: MicrosoftProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/microsoft.ts +description: Reference doc for the `MicrosoftProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Microsoft. Supports both OAuth2 and OIDC. + +#### Using OAuth + +```ts {5-9} +import { MicrosoftProvider } from "@openauthjs/openauth/provider/microsoft" + +export default issuer({ + providers: { + microsoft: MicrosoftProvider({ + tenant: "1234567890", + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` + +#### Using OIDC + +```ts {5-7} +import { MicrosoftOidcProvider } from "@openauthjs/openauth/provider/microsoft" + +export default issuer({ + providers: { + microsoft: MicrosoftOidcProvider({ + clientId: "1234567890" + }) + } +}) +``` +
+--- +## Methods +### MicrosoftOidcProvider + +
+```ts +MicrosoftOidcProvider(config) +``` +
+
+#### Parameters +-

config [MicrosoftOidcConfig](/docs/provider/microsoft#microsoftoidcconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Microsoft OIDC provider. + +This is useful if you just want to verify the user's email address. +```ts +MicrosoftOidcProvider({ + clientId: "1234567890" +}) +``` + +### MicrosoftProvider + +
+```ts +MicrosoftProvider(config) +``` +
+
+#### Parameters +-

config [MicrosoftConfig](/docs/provider/microsoft#microsoftconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Microsoft OAuth2 provider. +```ts +MicrosoftProvider({ + tenant: "1234567890", + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## MicrosoftConfig + +
+-

[clientID](#microsoftconfig.clientid) string

+-

[clientSecret](#microsoftconfig.clientsecret) string

+-

[query?](#microsoftconfig.query) Record<string, string>

+-

[scopes](#microsoftconfig.scopes) string[]

+-

[tenant](#microsoftconfig.tenant) string

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +tenant + +
+ +**Type** string + +
+The tenant ID of the Microsoft account. + +This is usually the same as the client ID. +```ts +{ + tenant: "1234567890" +} +``` + +## MicrosoftOidcConfig + +
+-

[clientID](#microsoftoidcconfig.clientid) string

+-

[query?](#microsoftoidcconfig.query) Record<string, string>

+-

[scopes?](#microsoftoidcconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + prompt: "consent" + } +} +``` + +scopes? + +
+ +**Type** string[] + +
+A list of OIDC scopes that you want to request. +```ts +{ + scopes: ["openid", "profile", "email"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/oauth2.mdx b/www/src/content/docs/docs/provider/oauth2.mdx new file mode 100644 index 00000000..d40b2986 --- /dev/null +++ b/www/src/content/docs/docs/provider/oauth2.mdx @@ -0,0 +1,160 @@ +--- +title: Oauth2Provider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/oauth2.ts +description: Reference doc for the `Oauth2Provider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this to connect authentication providers that support OAuth 2.0. + +```ts {5-12} +import { Oauth2Provider } from "@openauthjs/openauth/provider/oauth2" + +export default issuer({ + providers: { + oauth2: Oauth2Provider({ + clientId: "1234567890", + clientSecret: "0987654321", + endpoint: { + authorization: "https://auth.myserver.com/authorize", + token: "https://auth.myserver.com/token" + } + }) + } +}) +``` +
+--- +## Methods +### Oauth2Provider + +
+```ts +Oauth2Provider(config) +``` +
+
+#### Parameters +-

config [Oauth2Config](/docs/provider/oauth2#oauth2config)

+
+ +**Returns** Provider + + +## Oauth2Config + +
+-

[clientID](#oauth2config.clientid) string

+-

[clientSecret](#oauth2config.clientsecret) string

+-

[endpoint](#oauth2config.endpoint) { authorization: string, token: string }

+ -

[authorization](#endpoint.authorization) string

+ -

[token](#endpoint.token) string

+-

[query?](#oauth2config.query) Record<string, string>

+-

[scopes](#oauth2config.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +endpoint + +
+ +**Type** { authorization: string, token: string } + +
+The URLs of the authorization and token endpoints. +```ts +{ + endpoint: { + authorization: "https://auth.myserver.com/authorize", + token: "https://auth.myserver.com/token" + } +} +``` + +authorization + +
+ +**Type** string + +
+The URL of the authorization endpoint. + +token + +
+ +**Type** string + +
+The URL of the token endpoint. + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/oidc.mdx b/www/src/content/docs/docs/provider/oidc.mdx new file mode 100644 index 00000000..4b863dc8 --- /dev/null +++ b/www/src/content/docs/docs/provider/oidc.mdx @@ -0,0 +1,115 @@ +--- +title: OidcProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/oidc.ts +description: Reference doc for the `OidcProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this to connect authentication providers that support OIDC. + +```ts {5-8} +import { OidcProvider } from "@openauthjs/openauth/provider/oidc" + +export default issuer({ + providers: { + oauth2: OidcProvider({ + clientId: "1234567890", + issuer: "https://auth.myserver.com" + }) + } +}) +``` +
+--- +## Methods +### OidcProvider + +
+```ts +OidcProvider(config) +``` +
+
+#### Parameters +-

config [OidcConfig](/docs/provider/oidc#oidcconfig)

+
+ +**Returns** Provider + + +## OidcConfig + +
+-

[clientID](#oidcconfig.clientid) string

+-

[issuer](#oidcconfig.issuer) string

+-

[query?](#oidcconfig.query) Record<string, string>

+-

[scopes?](#oidcconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +issuer + +
+ +**Type** string + +
+The URL of your authorization server. +```ts +{ + issuer: "https://auth.myserver.com" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + prompt: "consent" + } +} +``` + +scopes? + +
+ +**Type** string[] + +
+A list of OIDC scopes that you want to request. +```ts +{ + scopes: ["openid", "profile", "email"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/slack.mdx b/www/src/content/docs/docs/provider/slack.mdx new file mode 100644 index 00000000..5ad72114 --- /dev/null +++ b/www/src/content/docs/docs/provider/slack.mdx @@ -0,0 +1,144 @@ +--- +title: SlackProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/slack.ts +description: Reference doc for the `SlackProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Slack. + +```ts {5-10} +import { SlackProvider } from "@openauthjs/openauth/provider/slack" + +export default issuer({ + providers: { + slack: SlackProvider({ + team: "T1234567890", + clientId: "1234567890", + clientSecret: "0987654321", + scopes: ["openid", "email", "profile"] + }) + } +}) +``` +
+--- +## Methods +### SlackProvider + +
+```ts +SlackProvider(config) +``` +
+
+#### Parameters +-

config [SlackConfig](/docs/provider/slack#slackconfig)

+The config for the provider. +
+ +**Returns** Provider + +Creates a [Slack OAuth2 provider](https://api.slack.com/authentication/sign-in-with-slack). +```ts +SlackProvider({ + team: "T1234567890", + clientId: "1234567890", + clientSecret: "0987654321", + scopes: ["openid", "email", "profile"] +}) +``` + +## SlackConfig + +
+-

[clientID](#slackconfig.clientid) string

+-

[clientSecret](#slackconfig.clientsecret) string

+-

[query?](#slackconfig.query) Record<string, string>

+-

[scopes](#slackconfig.scopes) (“email” | “profile” | “openid”)[]

+-

[team](#slackconfig.team) string

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** (“email” | “profile” | “openid”)[] + +
+The scopes to request from the user. + +| Scope | Description | +|-|-| +| `email` | Grants permission to access the user's email address. | +| `profile` | Grants permission to access the user's profile information. | +| `openid` | Grants permission to use OpenID Connect to verify the user's identity. | + +team + +
+ +**Type** string + +
+The workspace the user is intending to authenticate. + +If that workspace has been previously authenticated, the user will be signed in directly, +bypassing the consent screen. + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/spotify.mdx b/www/src/content/docs/docs/provider/spotify.mdx new file mode 100644 index 00000000..c8ecc00e --- /dev/null +++ b/www/src/content/docs/docs/provider/spotify.mdx @@ -0,0 +1,126 @@ +--- +title: SpotifyProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/spotify.ts +description: Reference doc for the `SpotifyProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Spotify. + +```ts {5-8} +import { SpotifyProvider } from "@openauthjs/openauth/provider/spotify" + +export default issuer({ + providers: { + spotify: SpotifyProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### SpotifyProvider + +
+```ts +SpotifyProvider(config) +``` +
+
+#### Parameters +-

config [SpotifyConfig](/docs/provider/spotify#spotifyconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Spotify OAuth2 provider. +```ts +SpotifyProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## SpotifyConfig + +
+-

[clientID](#spotifyconfig.clientid) string

+-

[clientSecret](#spotifyconfig.clientsecret) string

+-

[query?](#spotifyconfig.query) Record<string, string>

+-

[scopes](#spotifyconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/twitch.mdx b/www/src/content/docs/docs/provider/twitch.mdx new file mode 100644 index 00000000..92c75606 --- /dev/null +++ b/www/src/content/docs/docs/provider/twitch.mdx @@ -0,0 +1,126 @@ +--- +title: TwitchProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/twitch.ts +description: Reference doc for the `TwitchProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Twitch. + +```ts {5-8} +import { TwitchProvider } from "@openauthjs/openauth/provider/twitch" + +export default issuer({ + providers: { + twitch: TwitchProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### TwitchProvider + +
+```ts +TwitchProvider(config) +``` +
+
+#### Parameters +-

config [TwitchConfig](/docs/provider/twitch#twitchconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Twitch OAuth2 provider. +```ts +TwitchProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## TwitchConfig + +
+-

[clientID](#twitchconfig.clientid) string

+-

[clientSecret](#twitchconfig.clientsecret) string

+-

[query?](#twitchconfig.query) Record<string, string>

+-

[scopes](#twitchconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/x.mdx b/www/src/content/docs/docs/provider/x.mdx new file mode 100644 index 00000000..21b25e13 --- /dev/null +++ b/www/src/content/docs/docs/provider/x.mdx @@ -0,0 +1,126 @@ +--- +title: XProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/x.ts +description: Reference doc for the `XProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with X.com. + +```ts {5-8} +import { XProvider } from "@openauthjs/openauth/provider/x" + +export default issuer({ + providers: { + x: XProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### XProvider + +
+```ts +XProvider(config) +``` +
+
+#### Parameters +-

config [XProviderConfig](/docs/provider/x#xproviderconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a X.com OAuth2 provider. +```ts +XProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## XProviderConfig + +
+-

[clientID](#xproviderconfig.clientid) string

+-

[clientSecret](#xproviderconfig.clientsecret) string

+-

[query?](#xproviderconfig.query) Record<string, string>

+-

[scopes](#xproviderconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file diff --git a/www/src/content/docs/docs/provider/yahoo.mdx b/www/src/content/docs/docs/provider/yahoo.mdx new file mode 100644 index 00000000..357cf212 --- /dev/null +++ b/www/src/content/docs/docs/provider/yahoo.mdx @@ -0,0 +1,126 @@ +--- +title: YahooProvider +editUrl: https://github.com/openauthjs/openauth/blob/master/packages/openauth/src/provider/yahoo.ts +description: Reference doc for the `YahooProvider`. +--- + +import Segment from '../../../../components/tsdoc/Segment.astro'; +import Section from '../../../../components/tsdoc/Section.astro'; +import NestedTitle from '../../../../components/tsdoc/NestedTitle.astro'; +import InlineSection from '../../../../components/tsdoc/InlineSection.astro'; + +
+
+Use this provider to authenticate with Yahoo. + +```ts {5-8} +import { YahooProvider } from "@openauthjs/openauth/provider/yahoo" + +export default issuer({ + providers: { + yahoo: YahooProvider({ + clientId: "1234567890", + clientSecret: "0987654321" + }) + } +}) +``` +
+--- +## Methods +### YahooProvider + +
+```ts +YahooProvider(config) +``` +
+
+#### Parameters +-

config [YahooConfig](/docs/provider/yahoo#yahooconfig)

+The config for the provider. +
+ +**Returns** Provider + +Create a Yahoo OAuth2 provider. +```ts +YahooProvider({ + clientId: "1234567890", + clientSecret: "0987654321" +}) +``` + +## YahooConfig + +
+-

[clientID](#yahooconfig.clientid) string

+-

[clientSecret](#yahooconfig.clientsecret) string

+-

[query?](#yahooconfig.query) Record<string, string>

+-

[scopes](#yahooconfig.scopes) string[]

+
+ +clientID + +
+ +**Type** string + +
+The client ID. + +This is just a string to identify your app. +```ts +{ + clientID: "my-client" +} +``` + +clientSecret + +
+ +**Type** string + +
+The client secret. + +This is a private key that's used to authenticate your app. It should be kept secret. +```ts +{ + clientSecret: "0987654321" +} +``` + +query? + +
+ +**Type** Record<string, string> + +
+Any additional parameters that you want to pass to the authorization endpoint. +```ts +{ + query: { + access_type: "offline", + prompt: "consent" + } +} +``` + +scopes + +
+ +**Type** string[] + +
+A list of OAuth scopes that you want to request. +```ts +{ + scopes: ["email", "profile"] +} +``` + +
\ No newline at end of file