wasp-lang/wasp
1
1
Fork 0
mirror of https://github.com/wasp-lang/wasp.git synced 2024-11-26 22:36:01 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #959 from wasp-lang/vince-improve-google-auth-docs

Browse Source 
improve docs -- auth & intro video
This commit is contained in:
vincanger 2023-01-20 09:48:23 +01:00 committed by GitHub
commit 04286874d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 103 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -796,7 +796,7 @@ app MyApp {
("redux", "^4.0.5"),
("react-redux", "^7.1.3")
]
)
}
```
You will need to re-run `wasp start` after adding a dependency for Wasp to pick it up.
@ -817,12 +817,17 @@ app MyApp {
//...
auth: {
userEntity: User,
externalAuthEntity: SocialLogin,
methods: {
usernameAndPassword: {}
usernameAndPassword: {},
google: {},
gitHub: {},
},
onAuthFailedRedirectTo: "/someRoute"
}
}
//...
```
`app.auth` is a dictionary with following fields:
@ -831,7 +836,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](#google) and [GitHub](#github).
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.
#### `methods: dict` (required)
List of authentication methods that Wasp app supports. Currently supported methods are:
@ -854,12 +859,36 @@ Automatic redirect on successful login only works when using the Wasp provided [
### Username and Password
`usernameAndPassword` authentication method makes it possible to signup/login into the app by using a username and password.
This method requires that `userEntity` specified in `auth` contains `username: string` and `password: string` fields. `username`s are stored in a case-sensitive manner.
This method requires that `userEntity` specified in `auth` contains `username: string` and `password: string` fields:
```c
app MyApp {
title: "My app",
//...
auth: {
userEntity: User,
methods: {
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/someRoute"
}
}
// Wasp requires the userEntity to have at least the following fields
entity User {=psl
id Int @id @default(autoincrement())
username String @unique
password String
psl=}
```
We provide basic validations out of the box, which you can customize as shown below. Default validations are:
- `username`: non-empty
- `password`: non-empty, at least 8 characters, and contains a number
Note that `username`s are stored in a case-sensitive manner.
#### High-level API
The quickest way to get started is by using the following API generated by Wasp:
@ -988,7 +1017,7 @@ const SignOut = () => {
#### Reset password
Coming soon.
### Updating a user's password
#### Updating a user's password
If you need to update user's password, you can do it safely via Prisma client, e.g. within an action:
```js
export const updatePassword = async (args, context) => {
@ -1100,28 +1129,74 @@ import AuthError from '@wasp/core/AuthError.js'
}
```
### Google
### 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)
`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:
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 furter requirements (env variables) and override options:
```js
```c title="main.wasp"
app MyApp {
title: "My app",
//...
auth: {
// both userEntity and externalAuthEntity are required
userEntity: User,
externalAuthEntity: SocialLogin,
methods: {
google: {}
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=}
```
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).
:::info
Wasp assigns generated values to the `username` and `password` fields of the `userEntity` by default, so make sure to include it them your `userEntity` declaration even if you're only using a Social Login provider.
If you require custom configuration setup or user entity field assignment, you can [override the defaults](features#google-overrides).
:::
#### 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: {},
},
//...
}
```
This method also requires that `externalAuthEntity` be specified in `auth` as [described here](features#externalauthentity). NOTE: The same `externalAuthEntity` can be used across different social login providers (e.g., both GitHub and Google can use the same entity).
If you require custom configuration setup or user entity field assignment, you can [override the defaults](features#google-overrides).
#### Google Default settings
##### Google Default settings
- Configuration:
- By default, Wasp expects you to set two environment variables in order to use Google authentication:
- `GOOGLE_CLIENT_ID`
@ -1136,7 +1211,7 @@ If you require custom configuration setup or user entity field assignment, you c
:::
- 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 . These can be overriden as explained below.
#### Google Overrides
##### Google Overrides
If you require modifications to the above, you can add one or more of the following to your `auth.methods.google` dictionary:
```js
@ -1179,7 +1254,7 @@ If you require modifications to the above, you can add one or more of the follow
```
- `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.
#### Google UI helpers
##### Google UI helpers
To use the Google sign-in button, logo or URL on your login page, do either of the following:
@ -1204,11 +1279,11 @@ export default Login
If you need more customization than what the buttons provide, you can create your own custom component using the `googleSignInUrl`.
### GitHub
#### 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:
```js
```c {7}
//...
auth: {
@ -1225,7 +1300,7 @@ This method requires also requires that `externalAuthEntity` be specified in `au
If you require custom configuration setup or user entity field assignment, you can override the defaults. Please check out that section for [Google overrides](features#google-overrides), as the information is the same.
#### GitHub Default settings
##### GitHub Default settings
- Configuration:
- By default, Wasp expects you to set two environment variables in order to use GitHub authentication:
- `GITHUB_CLIENT_ID`
@ -1236,10 +1311,10 @@ If you require custom configuration setup or user entity field assignment, you c
NOTE: The same UI helpers apply as for Google. Please [see here](features#google-ui-helpers) for more.
### `externalAuthEntity`
Anytime an authentication method is used that relies on an external authorization provider, for example, Google, we require an `externalAuthEntity` specified in `auth` that contains at least the following highlighted fields:
#### `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:
```css {4,11,16-19,21}
```c {4,11,16-19,21}
...
auth: {
userEntity: User,

7
web/docs/tutorials/todo-app.md
View File

@ -4,9 +4,10 @@ title: Introduction
import useBaseUrl from '@docusaurus/useBaseUrl';
:::tip Skip the Tutorial & See Wasp in Action 👹?
It's possible because we've set up an in-browser dev environment for you on Gitpod.
You will be able to see and edit the finished ToDo app with no setup required.
:::tip See Wasp in Action
Prefer Videos? We have a YouTube tutorial which walks you through building this Todo App step by step. Check it out [here](https://youtu.be/R8uOu6ZEr5s).
We've also set up an in-browser dev environment for you on Gitpod, which allows you to see and edit the finished ToDo app with no setup required.
<p align="center">
<a href="https://gitpod.io/#https://github.com/wasp-lang/gitpod-template">
<img src="https://gitpod.io/button/open-in-gitpod.svg" />