From ed49597399c3e0d05ce5c295d53381fa2064286a Mon Sep 17 00:00:00 2001 From: beerose Date: Mon, 26 Aug 2024 15:49:41 +0200 Subject: [PATCH 1/6] Update auth helpers READMEs to include full EdgeDB Auth setup --- packages/auth-core/readme.md | 7 +- packages/auth-express/readme.md | 95 +++++++++++++++++++++++++-- packages/auth-nextjs/readme.md | 103 ++++++++++++++++++++++++++++-- packages/auth-remix/readme.md | 103 ++++++++++++++++++++++++++++-- packages/auth-sveltekit/readme.md | 87 ++++++++++++++++++++++++- 5 files changed, 376 insertions(+), 19 deletions(-) diff --git a/packages/auth-core/readme.md b/packages/auth-core/readme.md index 33bf96348..fe703185c 100644 --- a/packages/auth-core/readme.md +++ b/packages/auth-core/readme.md @@ -4,7 +4,10 @@ This library contains some low-level utilities to help working with the EdgeDB auth extension; namely resolving the api endpoint urls from an edgedb `Client` object, providing wrappers around those api's to help handle the various auth flows (including handling PKCE), and adding typesafety. -It is recommended to instead use the separate helper libraries created to make integration with popular frameworks as easy as possible. Currently supported frameworks: +It is recommended to instead use the separate helper libraries created to make integration with popular frameworks as easy as possible. Currently supported frameworks and libraries: -- Next.js (@edgedb/auth-nextjs) +- Next.js ([@edgedb/auth-nextjs](https://github.com/edgedb/edgedb-js/tree/master/packages/auth-nextjs)) +- Remix ([@edgedb/auth-remix](https://github.com/edgedb/edgedb-js/tree/master/packages/auth-remix)) +- SvelteKit ([@edgedb/auth-sveltekit](https://github.com/edgedb/edgedb-js/tree/master/packages/auth-sveltekit)) +- Express ([@edgedb/auth-express](https://github.com/edgedb/edgedb-js/tree/master/packages/auth-express)) - _...more coming soon_ diff --git a/packages/auth-express/readme.md b/packages/auth-express/readme.md index 537288382..3fbec95bd 100644 --- a/packages/auth-express/readme.md +++ b/packages/auth-express/readme.md @@ -17,7 +17,6 @@ npm install @edgedb/auth-express **Prerequisites**: - Node v18+ - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. -- Before adding EdgeDB auth to your Express app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers (you can do this in CLI or EdgeDB UI). Refer to the auth extension docs for details on how to do this. - We depend on the following middleware being installed in your Express app: - `body-parser`: both JSON and urlencoded - `cookie-parser` @@ -39,7 +38,93 @@ This library provides a few affordances for adding EdgeDB Auth to your existing - Middleware to attach sessions to requests. - Some additional utility functions for handling various auth related concerns. -## Configuring the `ExpressAuth` class +### EdgeDB Auth Setup + +Before adding EdgeDB auth to your Express server, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers. + +1. Enable the EdgeDB Auth extension in your schema: + + Add the following to your EdgeDB schema: + + ```sql + using extension auth; + ``` + + Once added, make sure to apply the schema changes by migrating your database schema: + + ```sh + $ edgedb migration create + $ edgedb migrate + ``` + +2. Configure EdgeDB Auth settings: + + Next, you'll need to configure the EdgeDB Auth extension. This involves setting up essential parameters, such as signing keys and allowed redirect URLs. + + _Below, we're showing how to set up the EdgeDB authentication using EdgeQL queries. To run these commands, you need to start the EdgeDB instance first (`edgedb`). Alternatively, you can use the EdgeDB UI (`edgedb ui`) to configure the authentication settings interactively._ + + **Signing Key** + + This key is used to sign JWT tokens. You can generate one using OpenSSL: + + ```sh + $ openssl rand -base64 32 + ``` + + Once generated, configure the signing key in EdgeDB: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::auth_signing_key := ''; + ``` + + **Allowed Redirect URLs** + + This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::allowed_redirect_urls := { + 'http://localhost:3000', + 'http://localhost:3000/auth' + }; + ``` + + **Authentication providers** + + You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: + + ```sql + CONFIGURE CURRENT BRANCH + INSERT ext::auth::EmailPasswordProviderConfig { + require_verification := false + }; + ``` + + _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + + **SMTP for email verification (optional)** + + If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::sender := 'hello@example.com'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::host := 'localhost'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::port := 1025; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::security := 'STARTTLSOrPlainText'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::validate_certs := false; + ``` + +### Configuring the `ExpressAuth` class After [configuring the EdgeDB Auth extension](https://www.edgedb.com/docs/guides/auth/index), you can set up the various auth routes with our route builders. @@ -56,7 +141,7 @@ const auth = createExpressAuth(client, { }); ``` -## Using the session middleware: `createSessionMiddleware` +### Using the session middleware: `createSessionMiddleware` We provide a middleware factory that will attach an `ExpressAuthSession` object to your request object, which you can use to make authenticated queries, or protect routes. @@ -80,7 +165,7 @@ app.get("/dashboard", (req: expressAuth.SessionRequest, res) => { }); ``` -### Create your own `requireAuth` middleware +#### Create your own `requireAuth` middleware You can centralize the logic to redirect unauthenticated routes into a custom middleware like this: @@ -110,7 +195,7 @@ app.get("/dashboard", requireAuth, (req: expressAuth.SessionRequest, res) => { }); ``` -## Adding route handlers +### Adding route handlers Route handlers can be added either using one or more of our "router factories", or by constructing your own Express `Router` object, and attaching the necessary middleware to routes that you configure yourself. The factory pattern makes it easy to quickly get a standardized set of routes to handle either the built-in UI, or some combination of email/password and/or OAuth routes. For maximum control over route locations, custom middleware patterns, or integration into existing router structures, you can use the router middleware. diff --git a/packages/auth-nextjs/readme.md b/packages/auth-nextjs/readme.md index 87a9a01c5..25bad2fe2 100644 --- a/packages/auth-nextjs/readme.md +++ b/packages/auth-nextjs/readme.md @@ -2,14 +2,101 @@ > Warning: This library is still in an alpha state, and so, bugs are likely and the api's should be considered unstable and may change in future releases. -### Setup +## Setup **Prerequisites**: - Node v18+ - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. -- Before adding EdgeDB auth to your Next.js app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers. Refer to the auth extension docs for details on how to do this. -1. Initialize the auth helper by passing an EdgeDB `Client` object to `createAuth()`, along with some configuration options. This will return a `NextAppAuth` object which you can use across your app. Similarly to the `Client` it's recommended to export this auth object from some root configuration file in your app. +### EdgeDB Auth Setup + +Before adding EdgeDB auth to your Next.js app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers. + +1. Enable the EdgeDB Auth extension in your schema: + + Add the following to your EdgeDB schema: + + ```sql + using extension auth; + ``` + + Once added, make sure to apply the schema changes by migrating your database schema: + + ```sh + $ edgedb migration create + $ edgedb migrate + ``` + +2. Configure EdgeDB Auth settings: + + Next, you'll need to configure the EdgeDB Auth extension. This involves setting up essential parameters, such as signing keys and allowed redirect URLs. + + _Below, we're showing how to set up the EdgeDB authentication using EdgeQL queries. To run these commands, you need to start the EdgeDB instance first (`edgedb`). Alternatively, you can use the EdgeDB UI (`edgedb ui`) to configure the authentication settings interactively._ + + **Signing Key** + + This key is used to sign JWT tokens. You can generate one using OpenSSL: + + ```sh + $ openssl rand -base64 32 + ``` + + Once generated, configure the signing key in EdgeDB: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::auth_signing_key := ''; + ``` + + **Allowed Redirect URLs** + + This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::allowed_redirect_urls := { + 'http://localhost:3000', + 'http://localhost:3000/auth' + }; + ``` + + **Authentication providers** + + You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: + + ```sql + CONFIGURE CURRENT BRANCH + INSERT ext::auth::EmailPasswordProviderConfig { + require_verification := false + }; + ``` + + _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + + **SMTP for email verification (optional)** + + If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::sender := 'hello@example.com'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::host := 'localhost'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::port := 1025; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::security := 'STARTTLSOrPlainText'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::validate_certs := false; + ``` + +### Initialize EdgeDB Auth Helper + +Initialize the auth helper by passing an EdgeDB `Client` object to `createAuth()`, along with some configuration options. This will return a `NextAppAuth` object which you can use across your app. Similarly to the `Client` it's recommended to export this auth object from some root configuration file in your app. ```ts // edgedb.ts @@ -33,7 +120,9 @@ - `passwordResetPath?: string`: The path relative to the `baseUrl` of the the password reset page; needed if you want to enable password reset emails in your app. - `magicLinkFailurePath?: string`: The path relative to the `baseUrl` of the page we should redirect users to if there is an error when trying to sign in with a magic link. The page will get an `error` search parameter attached with an error message. This property is required if you use the Magic Link authentication feature. -2. Setup the auth route handlers, with `auth.createAuthRouteHandlers()`. Callback functions can be provided to handle various auth events, where you can define what to do in the case of successful signin's or errors. You only need to configure callback functions for the types of auth you wish to use in your app. +### Auth Route Handlers Setup + +Setup the auth route handlers, with `auth.createAuthRouteHandlers()`. Callback functions can be provided to handle various auth events, where you can define what to do in the case of successful signin's or errors. You only need to configure callback functions for the types of auth you wish to use in your app. ```ts // app/auth/[...auth]/route.ts @@ -68,7 +157,9 @@ By default the handlers expect to exist under the `/auth` path in your app, however if you want to place them elsewhere, you will also need to configure the `authRoutesPath` option of `createAuth` to match. -3. Now we just need to setup the UI to allow your users to sign in/up, etc. The easiest way to get started is to use the EdgeDB Auth's builtin UI. Or alternatively you can implement your own custom UI. +### UI Setup + +Now we need to setup the UI to allow your users to sign in/up, etc. The easiest way to get started is to use the EdgeDB Auth's builtin UI. Or alternatively you can implement your own custom UI. **Builtin UI** @@ -92,7 +183,7 @@ - `signout` - `isPasswordResetTokenValid(resetToken: string)`: Checks if a password reset token is still valid. -### Usage +## Usage Now you have auth all configured and user's can signin/signup/etc. you can use the `auth.getSession()` method in your app pages to retrieve an `AuthSession` object. This session object allows you to check if the user is currently logged in with the `isSignedIn` method, and also provides a `Client` object automatically configured with the `ext::auth::client_token` global, so you can run queries using the `ext::auth::ClientTokenIdentity` of the currently signed in user. diff --git a/packages/auth-remix/readme.md b/packages/auth-remix/readme.md index 05d5b5783..578adadc0 100644 --- a/packages/auth-remix/readme.md +++ b/packages/auth-remix/readme.md @@ -16,9 +16,96 @@ npm install @edgedb/auth-remix **Prerequisites**: - Node v18+ - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. -- Before adding EdgeDB auth to your Remix app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers (you can do this in CLI or EdgeDB UI). Refer to the auth extension docs for details on how to do this. -1. Initialize the client auth helper by passing configuration options to `createClientAuth()`. This will return a `RemixClientAuth` object which you can use in your components. You can skip this part if you find it unnecessary and provide all your data through the loader (the next step), but we suggest having the client auth too and use it directly in your components to get OAuth, BuiltinUI and signout URLs. +### EdgeDB Auth Setup + +Before adding EdgeDB auth to your Remix app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers. + +1. Enable the EdgeDB Auth extension in your schema: + + Add the following to your EdgeDB schema: + + ```sql + using extension auth; + ``` + + Once added, make sure to apply the schema changes by migrating your database schema: + + ```sh + $ edgedb migration create + $ edgedb migrate + ``` + +2. Configure EdgeDB Auth settings: + + Next, you'll need to configure the EdgeDB Auth extension. This involves setting up essential parameters, such as signing keys and allowed redirect URLs. + + _Below, we're showing how to set up the EdgeDB authentication using EdgeQL queries. To run these commands, you need to start the EdgeDB instance first (`edgedb`). Alternatively, you can use the EdgeDB UI (`edgedb ui`) to configure the authentication settings interactively._ + + **Signing Key** + + This key is used to sign JWT tokens. You can generate one using OpenSSL: + + ```sh + $ openssl rand -base64 32 + ``` + + Once generated, configure the signing key in EdgeDB: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::auth_signing_key := ''; + ``` + + **Allowed Redirect URLs** + + This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::allowed_redirect_urls := { + 'http://localhost:3000', + 'http://localhost:3000/auth' + }; + ``` + + **Authentication providers** + + You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: + + ```sql + CONFIGURE CURRENT BRANCH + INSERT ext::auth::EmailPasswordProviderConfig { + require_verification := false + }; + ``` + + _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + + **SMTP for email verification (optional)** + + If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::sender := 'hello@example.com'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::host := 'localhost'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::port := 1025; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::security := 'STARTTLSOrPlainText'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::validate_certs := false; + ``` + +### Initialize Client Auth Helper + +Initialize the client auth helper by passing configuration options to `createClientAuth()`. This will return a `RemixClientAuth` object which you can use in your components. You can skip this part if you find it unnecessary and provide all your data through the loader (the next step), but we suggest having the client auth too and use it directly in your components to get OAuth, BuiltinUI and signout URLs. ```ts // app/services/auth.ts @@ -37,7 +124,9 @@ const auth = createClientAuth(options); export default auth; ``` -2. Initialize the server auth helper by passing an EdgeDB `Client` object to `createServerAuth()`, along with configuration options. This will return a `RemixServerAuth` object which you can use across your app on the server side. +### Initialize Server Auth Helper + +Initialize the server auth helper by passing an EdgeDB `Client` object to `createServerAuth()`, along with configuration options. This will return a `RemixServerAuth` object which you can use across your app on the server side. ```ts // app/services/auth.server.ts @@ -62,7 +151,9 @@ export default auth; - `pkceVerifierCookieName?: string`: The name of the cookie where the verifier for the PKCE flow will be stored, defaults to `'edgedb-pkce-verifier'` - `passwordResetUrl?: string`: The url of the the password reset page; needed if you want to enable password reset emails in your app. -3. Setup the auth route handlers, with `auth.createAuthRouteHandlers()`. Callback functions can be provided to handle various auth events, where you can define what to do in the case of successful signin's or errors. You only need to configure callback functions for the types of auth you wish to use in your app. +### Auth Route Handlers Setup + +Setup the auth route handlers, with `auth.createAuthRouteHandlers()`. Callback functions can be provided to handle various auth events, where you can define what to do in the case of successful signin's or errors. You only need to configure callback functions for the types of auth you wish to use in your app. ```ts // app/routes/auth.$.ts @@ -89,7 +180,9 @@ export default auth; By default the handlers expect to exist under the `/routes/auth` path in your app, however if you want to place them elsewhere, you will also need to configure the `authRoutesPath` option of `createServerAuth` to match. -4. Now we just need to setup the UI to allow your users to sign in/up, etc. The easiest way to get started is to use the EdgeDB Auth's builtin UI. Or alternatively you can implement your own custom UI. +### UI Setup + +Now we just need to setup the UI to allow your users to sign in/up, etc. The easiest way to get started is to use the EdgeDB Auth's builtin UI. Or alternatively you can implement your own custom UI. **Builtin UI** diff --git a/packages/auth-sveltekit/readme.md b/packages/auth-sveltekit/readme.md index 4654b5f03..322402230 100644 --- a/packages/auth-sveltekit/readme.md +++ b/packages/auth-sveltekit/readme.md @@ -16,7 +16,92 @@ npm install @edgedb/auth-sveltekit **Prerequisites**: - Node v18+ - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. -- Before adding EdgeDB auth to your SvelteKit app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers (you can do this in CLI or EdgeDB UI). Refer to the auth extension docs for details on how to do this. + +### EdgeDB Auth Setup + +Before adding EdgeDB auth to your SvelteKit app, you will first need to enable the `auth` extension in your EdgeDB schema, and have configured the extension with some providers. + +1. Enable the EdgeDB Auth extension in your schema: + + Add the following to your EdgeDB schema: + + ```sql + using extension auth; + ``` + + Once added, make sure to apply the schema changes by migrating your database schema: + + ```sh + $ edgedb migration create + $ edgedb migrate + ``` + +2. Configure EdgeDB Auth settings: + + Next, you'll need to configure the EdgeDB Auth extension. This involves setting up essential parameters, such as signing keys and allowed redirect URLs. + + _Below, we're showing how to set up the EdgeDB authentication using EdgeQL queries. To run these commands, you need to start the EdgeDB instance first (`edgedb`). Alternatively, you can use the EdgeDB UI (`edgedb ui`) to configure the authentication settings interactively._ + + **Signing Key** + + This key is used to sign JWT tokens. You can generate one using OpenSSL: + + ```sh + $ openssl rand -base64 32 + ``` + + Once generated, configure the signing key in EdgeDB: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::auth_signing_key := ''; + ``` + + **Allowed Redirect URLs** + + This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::AuthConfig::allowed_redirect_urls := { + 'http://localhost:3000', + 'http://localhost:3000/auth' + }; + ``` + + **Authentication providers** + + You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: + + ```sql + CONFIGURE CURRENT BRANCH + INSERT ext::auth::EmailPasswordProviderConfig { + require_verification := false + }; + ``` + + _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + + **SMTP for email verification (optional)** + + If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: + + ```sql + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::sender := 'hello@example.com'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::host := 'localhost'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::port := 1025; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::security := 'STARTTLSOrPlainText'; + + CONFIGURE CURRENT BRANCH SET + ext::auth::SMTPConfig::validate_certs := false; + ``` ### Client auth helper From c0c474917f7f5939bdbe1164af66988b6e3d2dd5 Mon Sep 17 00:00:00 2001 From: beerose Date: Tue, 27 Aug 2024 13:10:24 +0200 Subject: [PATCH 2/6] sql -> esdl --- packages/auth-express/readme.md | 10 +++++----- packages/auth-nextjs/readme.md | 10 +++++----- packages/auth-remix/readme.md | 10 +++++----- packages/auth-sveltekit/readme.md | 10 +++++----- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/packages/auth-express/readme.md b/packages/auth-express/readme.md index 3fbec95bd..267edf97a 100644 --- a/packages/auth-express/readme.md +++ b/packages/auth-express/readme.md @@ -46,7 +46,7 @@ Before adding EdgeDB auth to your Express server, you will first need to enable Add the following to your EdgeDB schema: - ```sql + ```esdl using extension auth; ``` @@ -73,7 +73,7 @@ Before adding EdgeDB auth to your Express server, you will first need to enable Once generated, configure the signing key in EdgeDB: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::auth_signing_key := ''; ``` @@ -82,7 +82,7 @@ Before adding EdgeDB auth to your Express server, you will first need to enable This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', @@ -94,7 +94,7 @@ Before adding EdgeDB auth to your Express server, you will first need to enable You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH INSERT ext::auth::EmailPasswordProviderConfig { require_verification := false @@ -107,7 +107,7 @@ Before adding EdgeDB auth to your Express server, you will first need to enable If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::SMTPConfig::sender := 'hello@example.com'; diff --git a/packages/auth-nextjs/readme.md b/packages/auth-nextjs/readme.md index 25bad2fe2..37d6181a6 100644 --- a/packages/auth-nextjs/readme.md +++ b/packages/auth-nextjs/readme.md @@ -16,7 +16,7 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the Add the following to your EdgeDB schema: - ```sql + ```esdl using extension auth; ``` @@ -43,7 +43,7 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the Once generated, configure the signing key in EdgeDB: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::auth_signing_key := ''; ``` @@ -52,7 +52,7 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', @@ -64,7 +64,7 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH INSERT ext::auth::EmailPasswordProviderConfig { require_verification := false @@ -77,7 +77,7 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::SMTPConfig::sender := 'hello@example.com'; diff --git a/packages/auth-remix/readme.md b/packages/auth-remix/readme.md index 578adadc0..11e5816e4 100644 --- a/packages/auth-remix/readme.md +++ b/packages/auth-remix/readme.md @@ -25,7 +25,7 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` Add the following to your EdgeDB schema: - ```sql + ```esdl using extension auth; ``` @@ -52,7 +52,7 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` Once generated, configure the signing key in EdgeDB: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::auth_signing_key := ''; ``` @@ -61,7 +61,7 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', @@ -73,7 +73,7 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH INSERT ext::auth::EmailPasswordProviderConfig { require_verification := false @@ -86,7 +86,7 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::SMTPConfig::sender := 'hello@example.com'; diff --git a/packages/auth-sveltekit/readme.md b/packages/auth-sveltekit/readme.md index 322402230..a5b268e4a 100644 --- a/packages/auth-sveltekit/readme.md +++ b/packages/auth-sveltekit/readme.md @@ -25,7 +25,7 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t Add the following to your EdgeDB schema: - ```sql + ```esdl using extension auth; ``` @@ -52,7 +52,7 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t Once generated, configure the signing key in EdgeDB: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::auth_signing_key := ''; ``` @@ -61,7 +61,7 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t This setting ensures that redirects are limited to the URLs under your control. Configure the allowed URLs with the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', @@ -73,7 +73,7 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t You need to configure at least one authentication provider. For example, to add an email/password provider, use the following command: - ```sql + ```esdl CONFIGURE CURRENT BRANCH INSERT ext::auth::EmailPasswordProviderConfig { require_verification := false @@ -86,7 +86,7 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t If using the email/password provider, you need to configure SMTP for email verification and password reset emails. Here's an example using a local SMTP server like Mailpit for development purposes: - ```sql + ```esdl CONFIGURE CURRENT BRANCH SET ext::auth::SMTPConfig::sender := 'hello@example.com'; From 0d3de7c93d1946d18fc7fc2d5648c3c3ef31099e Mon Sep 17 00:00:00 2001 From: beerose Date: Tue, 27 Aug 2024 13:15:55 +0200 Subject: [PATCH 3/6] replace note with CAUTION --- packages/auth-express/readme.md | 6 ++++-- packages/auth-nextjs/readme.md | 6 ++++-- packages/auth-remix/readme.md | 6 ++++-- packages/auth-sveltekit/readme.md | 6 ++++-- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/packages/auth-express/readme.md b/packages/auth-express/readme.md index 267edf97a..bf3a387de 100644 --- a/packages/auth-express/readme.md +++ b/packages/auth-express/readme.md @@ -16,7 +16,8 @@ npm install @edgedb/auth-express **Prerequisites**: - Node v18+ - - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + > [!CAUTION] + > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. - We depend on the following middleware being installed in your Express app: - `body-parser`: both JSON and urlencoded - `cookie-parser` @@ -101,7 +102,8 @@ Before adding EdgeDB auth to your Express server, you will first need to enable }; ``` - _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + > [!CAUTION] + > In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses. **SMTP for email verification (optional)** diff --git a/packages/auth-nextjs/readme.md b/packages/auth-nextjs/readme.md index 37d6181a6..fa820def2 100644 --- a/packages/auth-nextjs/readme.md +++ b/packages/auth-nextjs/readme.md @@ -6,7 +6,8 @@ **Prerequisites**: - Node v18+ - - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + > [!CAUTION] + > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. ### EdgeDB Auth Setup @@ -71,7 +72,8 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the }; ``` - _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + > [!CAUTION] + > In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses. **SMTP for email verification (optional)** diff --git a/packages/auth-remix/readme.md b/packages/auth-remix/readme.md index 11e5816e4..15c2fbd29 100644 --- a/packages/auth-remix/readme.md +++ b/packages/auth-remix/readme.md @@ -15,7 +15,8 @@ npm install @edgedb/auth-remix **Prerequisites**: - Node v18+ - - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + > [!CAUTION] + > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. ### EdgeDB Auth Setup @@ -80,7 +81,8 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` }; ``` - _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + > [!CAUTION] + > In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses. **SMTP for email verification (optional)** diff --git a/packages/auth-sveltekit/readme.md b/packages/auth-sveltekit/readme.md index a5b268e4a..2ce56e372 100644 --- a/packages/auth-sveltekit/readme.md +++ b/packages/auth-sveltekit/readme.md @@ -15,7 +15,8 @@ npm install @edgedb/auth-sveltekit **Prerequisites**: - Node v18+ - - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + > [!CAUTION] + > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. ### EdgeDB Auth Setup @@ -80,7 +81,8 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t }; ``` - _Note: In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses._ + > [!CAUTION] + > In production environments, it is recommended to set require_verification to true to ensure users verify their email addresses. **SMTP for email verification (optional)** From d7e7d322d086166eb2a07a8f222b3e80724c9757 Mon Sep 17 00:00:00 2001 From: beerose Date: Tue, 27 Aug 2024 13:20:12 +0200 Subject: [PATCH 4/6] add ngrok and cloudflare tunnel urls examples --- packages/auth-express/readme.md | 3 ++- packages/auth-nextjs/readme.md | 3 ++- packages/auth-remix/readme.md | 3 ++- packages/auth-sveltekit/readme.md | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/packages/auth-express/readme.md b/packages/auth-express/readme.md index bf3a387de..bbc0335bd 100644 --- a/packages/auth-express/readme.md +++ b/packages/auth-express/readme.md @@ -87,7 +87,8 @@ Before adding EdgeDB auth to your Express server, you will first need to enable CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', - 'http://localhost:3000/auth' + 'https://example.trycloudflare.com', + 'https://example.ngrok.io', }; ``` diff --git a/packages/auth-nextjs/readme.md b/packages/auth-nextjs/readme.md index fa820def2..5d90c8a17 100644 --- a/packages/auth-nextjs/readme.md +++ b/packages/auth-nextjs/readme.md @@ -57,7 +57,8 @@ Before adding EdgeDB auth to your Next.js app, you will first need to enable the CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', - 'http://localhost:3000/auth' + 'https://example.trycloudflare.com', + 'https://example.ngrok.io', }; ``` diff --git a/packages/auth-remix/readme.md b/packages/auth-remix/readme.md index 15c2fbd29..126fcee14 100644 --- a/packages/auth-remix/readme.md +++ b/packages/auth-remix/readme.md @@ -66,7 +66,8 @@ Before adding EdgeDB auth to your Remix app, you will first need to enable the ` CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', - 'http://localhost:3000/auth' + 'https://example.trycloudflare.com', + 'https://example.ngrok.io', }; ``` diff --git a/packages/auth-sveltekit/readme.md b/packages/auth-sveltekit/readme.md index 2ce56e372..158a42d2a 100644 --- a/packages/auth-sveltekit/readme.md +++ b/packages/auth-sveltekit/readme.md @@ -66,7 +66,8 @@ Before adding EdgeDB auth to your SvelteKit app, you will first need to enable t CONFIGURE CURRENT BRANCH SET ext::auth::AuthConfig::allowed_redirect_urls := { 'http://localhost:3000', - 'http://localhost:3000/auth' + 'https://example.trycloudflare.com', + 'https://example.ngrok.io', }; ``` From c9cd2e2e18072600635d0e7c5c9db1e1127cf41d Mon Sep 17 00:00:00 2001 From: Aleksandra Date: Tue, 27 Aug 2024 13:21:33 +0200 Subject: [PATCH 5/6] Update packages/auth-express/readme.md --- packages/auth-express/readme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/auth-express/readme.md b/packages/auth-express/readme.md index bbc0335bd..754fff511 100644 --- a/packages/auth-express/readme.md +++ b/packages/auth-express/readme.md @@ -16,6 +16,7 @@ npm install @edgedb/auth-express **Prerequisites**: - Node v18+ + > [!CAUTION] > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. - We depend on the following middleware being installed in your Express app: From 7ba1a06debcb767df82adb4b8d8eba74eec3d636 Mon Sep 17 00:00:00 2001 From: beerose Date: Tue, 27 Aug 2024 13:22:56 +0200 Subject: [PATCH 6/6] revert --- packages/auth-express/readme.md | 3 +-- packages/auth-nextjs/readme.md | 3 +-- packages/auth-remix/readme.md | 3 +-- packages/auth-sveltekit/readme.md | 3 +-- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/packages/auth-express/readme.md b/packages/auth-express/readme.md index bbc0335bd..2d9503b3c 100644 --- a/packages/auth-express/readme.md +++ b/packages/auth-express/readme.md @@ -16,8 +16,7 @@ npm install @edgedb/auth-express **Prerequisites**: - Node v18+ - > [!CAUTION] - > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. - We depend on the following middleware being installed in your Express app: - `body-parser`: both JSON and urlencoded - `cookie-parser` diff --git a/packages/auth-nextjs/readme.md b/packages/auth-nextjs/readme.md index 5d90c8a17..72ff8b4ce 100644 --- a/packages/auth-nextjs/readme.md +++ b/packages/auth-nextjs/readme.md @@ -6,8 +6,7 @@ **Prerequisites**: - Node v18+ - > [!CAUTION] - > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. ### EdgeDB Auth Setup diff --git a/packages/auth-remix/readme.md b/packages/auth-remix/readme.md index 126fcee14..08f1ca917 100644 --- a/packages/auth-remix/readme.md +++ b/packages/auth-remix/readme.md @@ -15,8 +15,7 @@ npm install @edgedb/auth-remix **Prerequisites**: - Node v18+ - > [!CAUTION] - > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. ### EdgeDB Auth Setup diff --git a/packages/auth-sveltekit/readme.md b/packages/auth-sveltekit/readme.md index 158a42d2a..016cfec3b 100644 --- a/packages/auth-sveltekit/readme.md +++ b/packages/auth-sveltekit/readme.md @@ -15,8 +15,7 @@ npm install @edgedb/auth-sveltekit **Prerequisites**: - Node v18+ - > [!CAUTION] - > Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. + - **Note**: Due to using the `crypto` global, you will need to start Node with `--experimental-global-webcrypto`. You can add this option to your `NODE_OPTIONS` environment variable, like `NODE_OPTIONS='--experimental-global-webcrypto'` in the appropriate `.env` file. ### EdgeDB Auth Setup