You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/contributing.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,7 +40,7 @@ Before running the tests from the `test/` folder `npm test` will run ESlint. You
40
40
41
41
### Documentation
42
42
43
-
Feathers documentation is contained in Markdown files in the [docs folder](https://github.com/feathersjs/feathers) of the mainr repository. To change the documentation submit a pull request to that repo, referencing any other PR if applicable, and the docs will be updated as soon as it is merged.
43
+
Feathers documentation is contained in Markdown files in the [docs folder](https://github.com/feathersjs/feathers) of the main repository. To change the documentation submit a pull request to that repo, referencing any other PR if applicable, and the docs will be updated as soon as it is merged.
Copy file name to clipboardExpand all lines: docs/guides/basics/authentication.md
+49-9Lines changed: 49 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ outline: deep
4
4
5
5
# Authentication
6
6
7
-
We now have a fully functional chat application consisting of [services](./services.md) and [schemas](./schemas.md). The services come with authentication enabled by default, so before we can use it we need to create a new user and learn how Feathers authentication works. We will look at authenticating our REST API, and then how to authenticate with Feathers in the browser. Finally we will implement a "Login with GitHub".
7
+
We now have a fully functional chat application consisting of [services](./services.md) and [schemas](./schemas.md). The services come with authentication enabled by default, so before we can use it we need to create a new user and learn how Feathers authentication works. We will look at authenticating our REST API, and then how to authenticate with Feathers in the browser. Finally we will implement a "Login with GitHub" button.
8
8
9
9
## Registering a user
10
10
@@ -36,33 +36,49 @@ For SQL databases, creating a user with the same email address will only work on
Which means our user has been created successfully.
48
64
49
65
<BlockQuotetype="info">
50
66
51
-
The password is stored securely in the database but will never be included in an external response.
67
+
The password has been encrypted and stored securely in the database but will never be included in an external response.
52
68
53
69
</BlockQuote>
54
70
55
71
## Logging in
56
72
57
-
By default, Feathers uses [JSON web token](https://jwt.io/) for authentication. It is an access token that is valid for a limited time (one day by default) that is issued by the Feathers server and needs to be sent with every API request that requires authentication. Usually a token is issued for a specific user and in our case we want a JWT for the user we just created.
73
+
By default, Feathers uses [JSON Web Tokens](https://jwt.io/) for authentication. It is an access token that is issued by the Feathers server for a limited time (one day by default) and needs to be sent with every API request that requires authentication. Usually a token is issued for a specific user, Let's see if we can issue a JWT for the user that we just created.
58
74
59
75
<BlockQuotetype="tip">
60
76
61
77
If you are wondering why Feathers is using JWT for authentication, have a look at [this FAQ](../../help/faq.md#why-are-you-using-jwt-for-sessions).
62
78
63
79
</BlockQuote>
64
80
65
-
Tokens can be created by sending a POST request to the `/authentication` endpoint (which is the same as calling the `create` method on the `authentication` service set up in `src/authentication`) and passing the authentication strategy you want to use. To get a token for an existing user through a username (email) and password login we can use the built-in `local` authentication strategy with a request like this:
81
+
Tokens can be created by sending a POST request to the `/authentication` endpoint (which is the same as calling the `create` method on the `authentication` service set up in `src/authentication`) and passing the authentication strategy you want to use along with any other relevant data. To get a token for an existing user through a username (email) and password login, we can use the built-in `local` authentication strategy with a request like this:
The `accessToken` can now be used for other REST requests that require authentication by sending the `Authorization: Bearer <accessToken>` HTTP header. For example to create a new message:
103
141
104
142
```sh
@@ -114,11 +152,13 @@ Make sure to replace the `<accessToken>` in the above request. For more informat
114
152
115
153
</BlockQuote>
116
154
155
+
That's pretty neat, but emails and passwords are boring, let's spice things up a bit.
156
+
117
157
## Login with GitHub
118
158
119
-
OAuth is an open authentication standard supported by almost every major platform and what gets us the log in with Facebook, Google, GitHub etc. buttons. From the Feathers perspective the authentication flow is pretty similar. Instead of authenticating with the `local` strategy by sending a username and password, Feathers directs the user to authorize the application with the login provider. If it is successful Feathers authentication finds or creates the user in the `users` service with the information it got back from the provider and then issues a token for them.
159
+
OAuth is an open authentication standard supported by almost every major social platform and what gets us the log in with Facebook, Google, GitHub etc. buttons. From the Feathers perspective, the authentication flow with OAuth is pretty similar. Instead of authenticating with the `local` strategy by sending a username and password, Feathers directs the user to authorize the application with the login provider. If it is successful, Feathers authentication finds or creates the user in the `users` service with the information it got back from the provider and then issues a token for them.
120
160
121
-
To allow login with GitHub, first, we have to [create a new OAuth application on GitHub](https://github.com/settings/applications/new). You can put anything in the name, homepage and description fields. The callback URL **must** be set to
161
+
To allow login with GitHub, we first have to [create a new OAuth application on GitHub](https://github.com/settings/applications/new). You can put anything in the name, homepage and description fields. The callback URL **must** be set to
122
162
123
163
```sh
124
164
http://localhost:3030/oauth/github/callback
@@ -132,7 +172,7 @@ You can find your existing applications in the [GitHub OAuth apps developer sett
132
172
133
173
</BlockQuote>
134
174
135
-
Once you clicked "Register application" we have to update our Feathers app configuration with the client id and secret copied from the GitHub application settings:
175
+
Once you've clicked "Register application", we need to update our Feathers app configuration with the client id and secret copied from the GitHub application settings:
136
176
137
177

Copy file name to clipboardExpand all lines: docs/guides/basics/generator.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@ You can create a new Feathers application by running `npm create feathers <name>
18
18
npm create feathers@pre feathers-chat
19
19
```
20
20
21
-
If you never ran the command before you might be ask to confirm the package installation by pressing enter.
21
+
If you never ran the command before you might be asked to confirm the package installation by pressing enter.
22
22
23
23
<BlockQuotetype="warning">
24
24
@@ -137,4 +137,4 @@ Keep this command running throughout the rest of this guide so it will reload al
137
137
138
138
## What's next?
139
139
140
-
In this chapter we we created a new Feathers application. To learn more about the generated files and what you can do with the CLI, have a look at the CLI guide after finishing the Getting Started guide. In [the next chapter](./services.md) we will learn more about Feathers services and databases.
140
+
In this chapter, we've created a new Feathers application. To learn more about the generated files and what you can do with the CLI, have a look at the [CLI guide](../cli/index.md) after finishing the Getting Started guide. In [the next chapter](./services.md) we will learn more about Feathers services and databases.
Copy file name to clipboardExpand all lines: docs/guides/basics/hooks.md
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,18 +67,19 @@ The hook `context` is an object which contains information about the service met
67
67
68
68
Read-only properties are:
69
69
70
-
-`context.app` - The Feathers application object. This can be used to e.g. call other services
71
-
-`context.service` - The service this hook is currently running on
70
+
-`context.app` - The Feathers application object. This commonly used to call other services
71
+
-`context.service` - The service object this hook is currently running on
72
72
-`context.path` - The path (name) of the service
73
-
-`context.method` - The service method name
74
-
-`context.type` - The hook type
73
+
-`context.method` - The name of the service method being called
74
+
-`context.type` - The hook type (around, before, etc)
75
75
76
76
Writeable properties are:
77
77
78
78
-`context.params` - The service method call `params`. For external calls, `params` usually contains:
79
-
-`context.params.query` - The query (e.g. from the query string) for the service call
80
-
-`context.params.provider` - The name of the transport the call has been made through. Usually `rest` or `socketio`. Will be `undefined` for internal calls.
81
-
-`context.id` - The `id` for a `get`, `remove`, `update` and `patch` service method call
79
+
-`context.params.query` - The query filter (e.g. from the REST query string) for the service call
80
+
-`context.params.provider` - The name of the transport the call has been made through. Usually `"rest"` or `"socketio"`. Will be `undefined` for internal calls.
81
+
-`context.params.user` - *If authenticated*, the data of the user making the service method call.
82
+
-`context.id` - The `id` of the record if the service method call is a `get`, `remove`, `update` or `patch`
82
83
-`context.data` - The `data` sent by the user in a `create`, `update` and `patch` and custom service method call
83
84
-`context.error` - The error that was thrown (in `error` hooks)
84
85
-`context.result` - The result of the service method call (available after calling `await next()` or in `after` hooks)
Copy file name to clipboardExpand all lines: docs/guides/basics/schemas.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,27 +6,27 @@ In Feathers, schemas and resolvers allow us to define, validate and secure our d
6
6
7
7
As we've briefly seen in the [previous chapter about hooks](./hooks.md), there were a few hooks registered already to validate schemas and resolve data. Schema validators and resolvers are used with those hooks to modify data in the hook context. Similar to how Feathers services are transport independent, schemas and resolvers are database independent. It comes in two main parts:
8
8
9
-
-[TypeBox](../../api/schema//typebox.md) or [JSON schema](../../api/schema//schema.md) to define a schema. This allows us to do things like:
9
+
-[TypeBox](../../api/schema/typebox.md) or [JSON schema](../../api/schema/schema.md) to define a schema. This allows us to do things like:
10
10
- Ensure data is valid and always in the right format
11
11
- Automatically get up to date TypeScript types from schema definitions
12
12
- Create a typed client that can be used in React, Vue etc. apps
13
13
- Automatically generate API documentation
14
-
- Validate query string queries and convert them to the correct type
14
+
- Validate query string filters and convert them to the correct types
15
15
-[Resolvers](../../api/schema/resolvers.md) - Resolve schema properties based on a context (usually the [hook context](./hooks.md)). This can be used for many different things like:
16
16
- Populating associations
17
-
- Securing queries and e.g. limiting requests to the logged in user
17
+
- Securing queries and limiting the type of requests the logged in user can perform
18
18
- Safely hiding sensitive data for external clients
19
-
- Adding read- and write permissions on the property level
19
+
- Adding read and write permissions on the property field level
20
20
- Hashing passwords and validating dynamic password policies
21
21
22
22
In this chapter we will look at the generated schemas and resolvers and update them with the information we need for our chat application.
23
23
24
24
## Feathers schemas
25
25
26
-
While schemas and resolvers can be used outside of a Feather application, you will usually encounter them in a Feathers context where they come in four kinds:
26
+
While schemas and resolvers can be used outside of a Feathers application, you will usually encounter them in a Feathers context where they come in four kinds:
27
27
28
28
-**Result** schemas and resolvers that define the data that is being returned. This is also where associated data would be fetched
29
-
-**Data** schemas and resolvers handle the data from the`create`, `update` and `patch`service methods and can be used to add things like default or calculated values (like the created or updated at date) before saving to the database
29
+
-**Data** schemas and resolvers handle the data from a`create`, `update`, `patch`, or custom service method and can be used to add/replace things like default or calculated values (e.g. the createdAt/updatedAt date) before saving it to the database
30
30
-**Query** schemas and resolvers validate and convert the query string and can also be used for additional limitations like only allowing a user to see and modify their own data
31
31
-**External** resolvers that return a safe version of the data (e.g. hiding a users password) that can be sent to external clients
Next we can look at the messages service schema. We want to include the date when the message was created as `createdAt` and the id of the user who sent it as `userId`. When we get a message back, we also want to populate the `user` with the user data from `userId` so that we can show e.g. the user image and email.
247
+
Next we can look at the messages service schema. We want to include the date when the message was created as `createdAt` and the id of the user who sent it as `userId`. When we get a message back, we also want to populate the `user` with the user data from `userId` so that we can show their avatar and email.
248
248
249
249
<LanguageBlockglobal-id="ts">
250
250
@@ -424,7 +424,7 @@ The `virtual()` in the `messageResolver` `user` property is a [virtual property]
424
424
425
425
<DatabaseBlockglobal-id="sql">
426
426
427
-
Now that our schemas and resolvers have everything we need, we also have to update the database with those changes. For SQL databases this is done with migrations. Migrations are a best practise for SQL databases to roll out and undo changes to the data model. Every change we make in a schema will need its corresponding migration step.
427
+
Now that our schemas and resolvers have everything we need, we also have to update the database with those changes. For SQL databases this is done with migrations. Migrations are a best practice for SQL databases to roll out and undo changes to the data model. Every change we make in a schema will need its corresponding migration step.
428
428
429
429
<BlockQuotetype="warning">
430
430
@@ -498,4 +498,4 @@ For MongoDB no migrations are necessary.
498
498
499
499
## What's next?
500
500
501
-
In this chapter we learned about schemas and implemented all the things we need for our chat application. In the next chapter we will learn about [authentication](./authentication.md) and add a "Login with GitHub".
501
+
In this chapter we learned about schemas and implemented all the things we need for our chat application. In the next chapter we will learn about [authentication](./authentication.md) and add a "Login with GitHub" button.
0 commit comments