wasp-lang/wasp
1
1
Fork 0
mirror of https://github.com/wasp-lang/wasp.git synced 2024-11-23 19:29:17 +03:00
Code Issues Projects Releases Wiki Activity

cleanup and improvements

Browse Source
This commit is contained in:
vincanger 2023-01-31 11:18:52 +01:00
parent f359ef6e18
commit f91b2a4fad
4 changed files with 129 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
web/docs/examples.md
View File

@ -15,7 +15,7 @@ The full list of examples can be found [here](https://github.com/wasp-lang/wasp/
- in-browser dev environment: [GitPod](https://gitpod.io/#https://github.com/wasp-lang/gitpod-template)
## Waspello (Trello Clone)
- **Features**: Auth ([Google](language/features#social-login-providers-oauth-20---google-github), [username/password](language/features#authentication--authorization)), [Optimistic Updates](language/features#the-useaction-hook), [Tailwind CSS integration](integrations/css-frameworks)
- **Features**: Auth ([Google](language/features#social-login-providers-oauth-20), [username/password](language/features#authentication--authorization)), [Optimistic Updates](language/features#the-useaction-hook), [Tailwind CSS integration](integrations/css-frameworks)
- Source code: [GitHub](https://github.com/wasp-lang/wasp/tree/main/examples/waspello)
- Hosted at [https://waspello-demo.netlify.app](https://waspello-demo.netlify.app/login)
<p align='center'>

8
web/docs/integrations/github.md
View File

@ -1,10 +1,10 @@
---
title: GitHub Integrations
title: GitHub
---
import useBaseUrl from '@docusaurus/useBaseUrl';
# GitHub Integrations
# GitHub
To implement GitHub Auth, you'll need to add the Auth object with the following configuration to your `main.wasp` file:
```c title="main.wasp"
@ -45,7 +45,7 @@ entity SocialLogin {=psl
psl=}
```
For more info on the specific fields, check out this [Auth](../language/features#social-login-providers-oauth-20---google-github) section of the docs.
For more info on the specific fields, check out this [Auth](../language/features#social-login-providers-oauth-20) section of the docs.
You'll also need to add these environment variables to your `.env.server` file at the root of your project:
@ -59,7 +59,7 @@ We will cover how to get these values in the next section.
## GitHub Auth
To use GitHub as an authentication method (covered [here](/docs/language/features#social-login-providers-oauth-20---google-github)), you'll first need to create a GitHub OAuth App and provide Wasp with your client key and secret. Here is how to do so:
To use GitHub as an authentication method (covered [here](/docs/language/features#social-login-providers-oauth-20)), you'll first need to create a GitHub OAuth App and provide Wasp with your client key and secret. Here is how to do so:
1. Log into your GitHub account and navigate to: https://github.com/settings/developers
2. Select "New OAuth App"

8
web/docs/integrations/google.md
View File

@ -1,10 +1,10 @@
---
title: Google Integrations
title: Google
---
import useBaseUrl from '@docusaurus/useBaseUrl';
# Google Integrations
# Google
To implement Google Auth, you'll need to add the Auth object with the following configuration to your `main.wasp` file:
```c title="main.wasp"
@ -45,7 +45,7 @@ entity SocialLogin {=psl
psl=}
```
For more info on the specific fields, check out this [Auth](../language/features#social-login-providers-oauth-20---google-github) section of the docs.
For more info on the specific fields, check out this [Auth](../language/features#social-login-providers-oauth-20) section of the docs.
You'll also need to add these environment variables to your `.env.server` file at the root of your project:
@ -58,7 +58,7 @@ We will cover how to get these values in the next section.
## Google Auth
To use Google as an authentication method (covered [here](/docs/language/features#social-login-providers-oauth-20---google-github)), you'll first need to create a Google project and provide Wasp with your client key and secret. Here is how to do so:
To use Google as an authentication method (covered [here](/docs/language/features#social-login-providers-oauth-20)), you'll first need to create a Google project and provide Wasp with your client key and secret. Here is how to do so:
1. Create a Google Cloud Platform account if you do not already have one: https://cloud.google.com/
2. Create and configure a new Google project here: https://console.cloud.google.com/home/dashboard

242
web/docs/language/features.md
View File

@ -2,6 +2,9 @@
title: Features
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
## App
There can be only one declaration of `app` type per Wasp project.
@ -836,7 +839,7 @@ app MyApp {
Entity which represents the user (sometimes also referred to as *Principal*).
#### `externalAuthEntity: entity` (optional)
Entity which associates a user with some external authentication provider. We currently offer support for Google and GitHub. See the sections on [Social Login Providers](#social-login-providers-oauth-20---google-github) for more info.
Entity which associates a user with some external authentication provider. We currently offer support for Google and GitHub. See the sections on [Social Login Providers](#social-login-providers-oauth-20) for more info.
#### `methods: dict` (required)
List of authentication methods that Wasp app supports. Currently supported methods are:
@ -1129,117 +1132,76 @@ import AuthError from '@wasp/core/AuthError.js'
}
```
### Social Login Providers (OAuth 2.0) - Google, GitHub
Wasp currently supports the following Social Login providers (with more to come) :
- [GitHub](features#github)
- [Google](features#google)
## Social Login Providers (OAuth 2.0)
Wasp allows you to easily add social login providers to your app.
The following is a quick example of how your `.wasp` file might look like when implementing social login. Make sure to read the specific sections for further requirements (env variables) and override options:
The following is a list of links to guides that will help you get started with the currently supported providers:
- [Google](/docs/integrations/google)
- [GitHub](/docs/integrations/github)
```c title="main.wasp"
app MyApp {
title: "My app",
//...
When using Social Login Providers, Wasp gives you the following options:
- Default settings to get you started quickly
- UI Helpers to make it easy to add social login buttons and actions
- Override settings to customize the behavior of the providers
### Default Settings
<Tabs>
<TabItem value="google" label="Google" default>
```c
auth: {
// both userEntity and externalAuthEntity are required
userEntity: User,
externalAuthEntity: SocialLogin,
methods: {
google: {},
gitHub: {}
},
}
}
// Wasp requires the userEntity to have at least the following fields
entity User {=psl
id Int @id @default(autoincrement())
username String @unique
password String
externalAuthAssociations SocialLogin[]
psl=}
// Different social login providers can use the same externalAuthEntity
entity SocialLogin {=psl
id Int @id @default(autoincrement())
provider String
providerId String
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
userId Int
createdAt DateTime @default(now())
@@unique([provider, providerId, userId])
psl=}
```
:::caution
Be sure to include an `externalAuthEntity` in your `auth` declaration, as [described here](features#externalauthentity). Note that the same `externalAuthEntity` can be used across different social login providers (e.g., both GitHub and Google can use the same entity).
:::
<p>Add <code>google: &#123;&#125;</code> to your <code>auth.methods</code> dictionary to use it with default settings</p>
<p>By default, Wasp expects you to set two environment variables in order to use Google authentication:</p>
<ul>
<li><code>GOOGLE_CLIENT_ID</code></li>
<li><code>GOOGLE_CLIENT_SECRET</code></li>
</ul>
<p>These can be obtained in your Google Cloud Console project dashboard. See <a href="/docs/integrations/google">here</a> for a detailed guide.</p>
</TabItem>
<TabItem value="gitHub" label="GitHub">
```c
auth: {
userEntity: User,
externalAuthEntity: SocialLogin,
methods: {
gitHub: {},
},
}
```
<p>Add <code>gitHub: &#123;&#125;</code> to your <code>auth.methods</code> dictionary to use it with default settings</p>
<p>By default, Wasp expects you to set two environment variables in order to use GitHub authentication:</p>
<ul>
<li><code>GITHUB_CLIENT_ID</code></li>
<li><code>GITHUB_CLIENT_SECRET</code></li>
</ul>
<p>These can be obtained in your GitHub project dashboard. See <a href="/docs/integrations/github">here</a> for a detailed guide.</p>
</TabItem>
</Tabs>
:::info Default User Fields
When a user signs in for the first time, Wasp assigns generated values to the `username` and `password` fields of the `userEntity` by default (e.g. `username: nice-blue-horse-14357`), so make sure to include these in your `userEntity` declaration even if you're only using a Social Login provider. If you'd like to change this behavior, these values can be overridden as described below.
:::
:::tip UI Helpers and Overrides
Wasp provides you with a few UI helper components and functions to make implementing social login easier. See [here](features#ui-helpers-for-social-login-providers) for more details.
:::tip Overriding Defaults
It is also posslbe to [override the default](features#overrides-for-social-login-providers) login behaviors that Wasp provides for you. This allows you to create custom setups, such as allowing Users to define a username rather than the default random username assigned by Wasp on initial Login.
:::
#### Google
`google` authentication makes it possible to use Google's OAuth 2.0 service to sign Google users into your app. To enable it, add `google: {}` to your `auth.methods` dictionary to use it with default settings:
```c {6}
auth: {
// both userEntity and externalAuthEntity are required
userEntity: User,
externalAuthEntity: SocialLogin,
methods: {
google: {},
},
}
```
##### Google Default settings
- Configuration:
- By default, Wasp expects you to set two environment variables in order to use Google authentication:
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- These can be obtained in your Google Cloud Console project dashboard. See [here](/docs/integrations/google#google-auth) for a detailed guide.
Here is a link to the default implementations: https://github.com/wasp-lang/wasp/blob/release/waspc/data/Generator/templates/server/src/routes/auth/passport/google/defaults.js.
#### GitHub
`gitHub` authentication makes it possible to use GitHub's OAuth 2.0 service to sign GitHub users into your app. To enable it, add `gitHub: {}` to your `auth.methods` dictionary to use it with default settings:
```c {7}
//...
auth: {
userEntity: User,
externalAuthEntity: SocialLogin,
methods: {
gitHub: {}
},
//...
}
```
##### GitHub Default settings
- Configuration:
- By default, Wasp expects you to set two environment variables in order to use GitHub authentication:
- `GITHUB_CLIENT_ID`
- `GITHUB_CLIENT_SECRET`
- These can be obtained in your GitHub project dashboard. See [here](/docs/integrations/github#github-auth) for a detailed guide.
Here is a link to the default implementations: https://github.com/wasp-lang/wasp/blob/release/waspc/data/Generator/templates/server/src/routes/auth/passport/github/defaults.js
#### `externalAuthEntity`
Anytime an authentication method is used that relies on an external authorization provider, for example, Google, we require an `externalAuthEntity` specified in `auth`, in addition to the `userEntity`, that contains at least the following highlighted fields:
Anytime an authentication method is used that relies on an external authorization provider, for example, Google, we require an `externalAuthEntity` specified in `auth`, in addition to the `userEntity`, that contains the following configuration:
```c {4,11,16-19,21}
```c {4,14}
...
auth: {
userEntity: User,
@ -1263,10 +1225,12 @@ entity SocialLogin {=psl
@@unique([provider, providerId, userId])
psl=}
```
:::note
the same `externalAuthEntity` can be used across different social login providers (e.g., both GitHub and Google can use the same entity).
:::
### UI helpers
#### UI helpers for Social Login Providers
To use the provided sign-in buttons, logos or URLs on your login page, do either of the following:
Wasp provides sign-in buttons, logos and URLs for your login page:
```jsx
...
@ -1292,13 +1256,16 @@ export default Login
If you need more customization than what the buttons provide, you can create your own custom components using the `signInUrl`s.
#### Overrides for Social Login Providers
### Overrides
When a user signs in for the first time, Wasp will create a new User account and link it to the chosen Auth Provider account (e.g. Google, GitHub) for future logins. The `username` will default to a random dictionary phrase that does not exist in the database, such as "nice-blue-horse-27160"
When a user signs in for the first time, Wasp will create a new User account and link it to the chosen Auth Provider account for future logins. The `username` will default to a random dictionary phrase that does not exist in the database, such as `nice-blue-horse-27160`.
If you would like to allow the user to select their own username, or some other sign up flow, you could add a boolean property to your User entity which indicates if the account setup is complete. You can then check this user's property on the client with the [`useAuth()`](#useauth) hook and redirect them when appropriate -- e.g. check on homepage if `user.isAuthSetup === false`, redirect them to `EditUserDetailsPage`.
If you would like to allow the user to select their own username, or some other sign up flow, you could add a boolean property to your User entity indicating the account setup is incomplete. You can then check this user's property on the client with the [`useAuth()`](#useauth) hook and redirect them when appropriate
- e.g. check on homepage if `user.isAuthSetup === false`, redirect them to `EditUserDetailsPage`.
Alternatively, you could add a `displayName` property to your User entity and assign it using the details of their provider account. Below is an example of how to do this:
Alternatively, you could add a `displayName` property to your User entity and assign it using the details of their provider account. Below is an example of how to do this by using:
- the `getUserFieldsFn` function to configure the user's `username` or `displayName` from their provider account
- the `configFn` function to customize the configuration of the Provider's settings
```c title=main.wasp {9,10,13,14,26}
app Example {
@ -1334,33 +1301,50 @@ psl=}
```
- `configFn`: This function should return an object with the following shape:
```js title=src/server/auth/google.js
export function config() {
// ...
return {
clientID, // look up from env or elsewhere,
clientSecret, // look up from env or elsewhere,
scope: ['profile'] // must include at least 'profile' for Google
}
}
#### `configFn`
This function should return an object with the following shape:
<Tabs>
<TabItem value="google" label="Google" default>
```js title=src/server/auth/google.js
export function config() {
// ...
```
```js title=src/server/auth/github.js
export function config() {
// ...
return {
clientID, // look up from env or elsewhere,
clientSecret, // look up from env or elsewhere,
scope: [] // pass an empty array for GitHub
}
return {
clientID, // look up from env or elsewhere,
clientSecret, // look up from env or elsewhere,
scope: ['profile'] // must include at least 'profile' for Google
}
}
// ...
```
<p>Here is a link to the <a href="https://github.com/wasp-lang/wasp/blob/release/waspc/data/Generator/templates/server/src/routes/auth/passport/google/defaults.js">default implementations</a> as a reference</p>
</TabItem>
<TabItem value="github" label="GitHub">
```js title=src/server/auth/github.js
export function config() {
// ...
```
- `getUserFieldsFn`: This function should return the user fields to use when creating a new user upon their first time logging in with a Social Auth Provider. The context contains a User entity for DB access, and the args are what the OAuth provider responds with. Here is how you could generate a username based on the Google display name. In your model, you could choose to add more attributes and set additional information.
return {
clientID, // look up from env or elsewhere,
clientSecret, // look up from env or elsewhere,
scope: [] // default is an empty array for GitHub
}
}
// ...
```
<p>Here is a link to the <a href="https://github.com/wasp-lang/wasp/blob/release/waspc/data/Generator/templates/server/src/routes/auth/passport/github/defaults.js">default implementations</a> as a reference</p>
</TabItem>
</Tabs>
#### `getUserFieldsFn`
This function should return the user fields to use when creating a new user upon their first time logging in with a Social Auth Provider. The context contains a User entity for DB access, and the args are what the OAuth provider responds with. Here is how you could generate a username based on the Google display name. In your model, you could choose to add more attributes and set additional information.
```js title=src/server/auth/google.js
import { generateAvailableUsername } from '@wasp/core/auth.js'
@ -1371,7 +1355,21 @@ psl=}
return { username }
}
```
Or you could set the optional `displayName` property on the `User` entity instead:
```js title=src/server/auth/google.js
import { generateAvailableDictionaryUsername, generateAvailableUsername } from '@wasp/core/auth.js'
// ...
export async function getUserFields(_context, args) {
const username = await generateAvailableDictionaryUsername()
const displayName = await generateAvailableUsername(args.profile.displayName.split(' '), { separator: '.' })
return { username, displayName }
}
```
- `generateAvailableUsername` takes an array of Strings and an optional separator and generates a string ending with a random number that is not yet in the database. For example, the above could produce something like "Jim.Smith.3984" for a Google user Jim Smith.
- `generateAvailableDictionaryUsername` generates a random dictionary phrase that is not yet in the database. For example, `nice-blue-horse-27160`.
## Client configuration