mirror of
https://github.com/feathersjs/feathers.git
synced 2025-12-08 19:46:22 +00:00
327 lines
18 KiB
Markdown
327 lines
18 KiB
Markdown
---
|
|
outline: deep
|
|
---
|
|
|
|
# OAuth
|
|
|
|
<Badges>
|
|
|
|
[](https://www.npmjs.com/package/@feathersjs/authentication-oauth)
|
|
[](https://github.com/feathersjs/feathers/blob/dove/packages/authentication-oauth/CHANGELOG.md)
|
|
|
|
</Badges>
|
|
|
|
```
|
|
npm install @feathersjs/authentication-oauth --save
|
|
```
|
|
|
|
`@feathersjs/authentication-oauth` allows to authenticate with over 180 OAuth providers (Google, Facebook, GitHub etc.) using [grant](https://github.com/simov/grant), an OAuth middleware module for NodeJS.
|
|
|
|
## Usage
|
|
|
|
The following section covers oAuth authentication strategy [setup](#setup) and a more detailed description of the possible oAuth [flows](#flow) and [oAuth URLs](#oauth-urls).
|
|
|
|
### Setup
|
|
|
|
The following is a standard oAuth setup. The `OAuthStrategy` often needs to be [customized](#customization) to include additional fields (like the avatar, email address or username) from the oAuth provider.
|
|
|
|
```ts
|
|
import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication'
|
|
import { LocalStrategy } from '@feathersjs/authentication-local'
|
|
import { OAuthStrategy, oauth } from '@feathersjs/authentication-oauth'
|
|
import type { Application } from './declarations'
|
|
|
|
declare module './declarations' {
|
|
interface ServiceTypes {
|
|
authentication: AuthenticationService
|
|
}
|
|
}
|
|
|
|
export const authentication = (app: Application) => {
|
|
const authentication = new AuthenticationService(app)
|
|
|
|
authentication.register('jwt', new JWTStrategy())
|
|
authentication.register('github', new OAuthStrategy())
|
|
authentication.register('google', new OAuthStrategy())
|
|
|
|
app.use('authentication', authentication)
|
|
app.configure(oauth({}))
|
|
}
|
|
```
|
|
|
|
The following settings for `app.configure(oauth())` are available:
|
|
|
|
- `linkStrategy` (default: `'jwt'`) - The name of the stratagy to use for [account linking](#account-linking)
|
|
- `authService` (default: `app.get('defaultAuthentication')`) - The path of the authentication service to use
|
|
- `expressSession` - An Express middleware for handling sessions. By default will use an HTTP cookie that is only available for the oAuth flow. **This normally does not need to be changed.**
|
|
- `koaSession` - A Koa middleware for handling sessions. By default will use an HTTP cookie that is only available for the oAuth flow. **This normally does not need to be changed.**
|
|
|
|
### Providers
|
|
|
|
For specific OAuth provider setup see the following [cookbook](../../cookbook/) guides:
|
|
|
|
- [Auth0](../../cookbook/authentication/auth0.md)
|
|
- [Facebook](../../cookbook/authentication/facebook.md)
|
|
- [Google](../../cookbook/authentication/google.md)
|
|
|
|
### Flow
|
|
|
|
There are two ways to initiate OAuth authentication:
|
|
|
|
1. Through the browser (most common)
|
|
|
|
- User clicks on link to OAuth URL (`oauth/<provider>`)
|
|
- Gets redirected to provider and authorizes the application
|
|
- Callback to the [OauthStrategy](#oauthstrategy) which
|
|
- Gets the users profile
|
|
- Finds or creates the user (entity) for that profile
|
|
- The [AuthenticationService](./service.md) creates an access token for that entity
|
|
- Redirects back to the origin URL including the generated access token
|
|
- The frontend (e.g. the Feathers [authentication client](./client.md)) uses the returned access token to authenticate
|
|
|
|
2. With an existing access token, e.g. obtained through the Facebook mobile SDK
|
|
- Authenticate normally through the [authentication service](./service.md) with `{ strategy: '<name>', accessToken: 'oauth access token' }`.
|
|
- Calls the [OauthStrategy](#oauthstrategy) which
|
|
- Gets the users profile
|
|
- Finds or creates the entity for that profile
|
|
- Returns the authentication result
|
|
|
|
<BlockQuote type="warning" label="Important">
|
|
|
|
If you are attempting to authenticate using an existing oAuth access token, ensure that you have added the strategy (e.g. 'facebook') to the allowed [authStrategies](./service.md#configuration) configuration.
|
|
|
|
</BlockQuote>
|
|
|
|
### OAuth URLs
|
|
|
|
There are two URLs and redirects that are important for OAuth authentication:
|
|
|
|
- `http(s)://<host>/oauth/<provider>`: The main URL to initiate the OAuth flow. **Link to this from the browser.**
|
|
- `http(s)://<host>/oauth/<provider>/callback`: The callback path that should be **set in the OAuth provider application settings.**
|
|
|
|
In the browser any OAuth flow can be initiated with a link like this:
|
|
|
|
```html
|
|
<a href="/oauth/github">Login with GitHub</a>
|
|
```
|
|
|
|
### Account linking
|
|
|
|
To **link an existing user** the current access token can be added to the OAuth flow query using the `feathers_token` query parameter:
|
|
|
|
```html
|
|
<a href="/oauth/github?feathers_token=<your access token>"> Login with GitHub </a>
|
|
```
|
|
|
|
This will use the user (entity) of that access token to link the OAuth account to. Using the [authentication client](./client.md) you can get the current access token via `app.get('authentication')`:
|
|
|
|
```ts
|
|
const { accessToken } = await app.get('authentication')
|
|
```
|
|
|
|
### Redirects
|
|
|
|
The recommended way to enable redirects is to set a list of allowed `origins` in your [application configuration](../configuration.md) (e.g. `config/default.json`). This will ensure cross origin restrictions across your application and allow oAuth authentication from different frontend applications.
|
|
|
|
```js
|
|
{
|
|
"origins": [
|
|
// Allow redirect to a local development frontend
|
|
// (e.g. a create-react-app server) and our production URL
|
|
"http://localhost:500", "https://myapp.feathersjs.com"
|
|
]
|
|
}
|
|
```
|
|
|
|
**Alternatively**, the `redirect` configuration can be used to redirect back to the frontend application after OAuth authentication was successful and an access token for the user has been created by the [authentication service](./service.md) or if authentication failed. It works cross domain and by default includes the access token or error message in the window location hash. The following configuration
|
|
|
|
```js
|
|
{
|
|
"authentication": {
|
|
"oauth": {
|
|
"redirect": "https://app.mydomain.com/"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
A successful oAuth flow will redirect to the origin or redirect URL in the form of `https://app.mydomain.com/#access_token=<user jwt>` or `https://app.mydomain.com/#error=<some error message>`. Redirects can be customized with the [getRedirect()](#getredirect-data) method of the OAuth strategy. The [authentication client](./client.md) handles the default redirects automatically already.
|
|
|
|
<BlockQuote type="info" label="Note">
|
|
|
|
The redirect is using a hash instead of a query string by default because it is not logged server side and can be easily read on the client. You can force query based redirect by adding a `?` to the end of the `redirect` option.
|
|
|
|
</BlockQuote>
|
|
|
|
If the `redirect` option is not set and no origin is available the authentication result data will be sent as JSON instead.
|
|
|
|
Dynamic redirects to the same URL are possible by setting the `redirect` query parameter in the OAuth flow. For example, the following OAuth link:
|
|
|
|
```html
|
|
<a href="/oauth/github?redirect=dashboard"> Login with GitHub </a>
|
|
```
|
|
|
|
With the above configuration will redirect to `https://app.mydomain.com/dashboard` after the OAuth flow.
|
|
|
|
## Options
|
|
|
|
Options are usually set under the registered name via [Feathers configuration](../configuration.md) in `config/default.json` or `config/<environment>.json` under the `authentication.oauth` section. Available options are:
|
|
|
|
- `origins` (default: `app.get('origins')`): A list of URLs from which oAuth authentication should be allowed. For example setting this option to`[ "https://feathersjs.com", "https://feathers.cloud" ]` would allow requests from those domains and redirect back to where the request came from. This can be used **instead of** the `redirect` option for a more consisten cross origin configuration via the `app.get('origins')` configuration value and to allow oAuth logins from multiple domains.
|
|
- `redirect`: The URL of the frontend to redirect to with the access token (or error message). The [authentication client](./client.md) handles those redirects automatically. If not set, the authentication result will be sent as JSON instead.
|
|
- `defaults`: Default [Grant configuration](https://github.com/simov/grant#configuration) used for all strategies. The following default options are set automatically:
|
|
- `prefix` (default: `'/oauth'`) - The OAuth base path
|
|
- `origin` (default: `http(s)://host[:port]`) - The server path for the oAuth flow to redirect back to. Set this if you are e.g. running your local server on HTTPS
|
|
- `<strategy-name>` (e.g. `twitter`): The [Grant configuration](https://github.com/simov/grant#configuration) used for a specific strategy.
|
|
|
|
<BlockQuote type="tip">
|
|
|
|
Removing the `redirect` option allows to troubleshoot troubleshoot OAuth authentication errors as a JSON response by opening the oAuth URL directly in the browser.
|
|
|
|
</BlockQuote>
|
|
|
|
```json
|
|
{
|
|
"authentication": {
|
|
"origins": ["localhost:3030"],
|
|
"oauth": {
|
|
"redirect": "/frontend",
|
|
"google": {
|
|
"key": "...",
|
|
"secret": "...",
|
|
"custom_params": { "access_type": "offline" }
|
|
},
|
|
"twitter": {
|
|
"key": "...",
|
|
"secret": "..."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<BlockQuote type="info" label="Note">
|
|
|
|
All OAuth strategies will by default always look for configuration under `authentication.oauth.<name>`. If `authentication.oauth` is not set in the configuration, OAuth authentication will be disabled.
|
|
|
|
</BlockQuote>
|
|
|
|
Here is a [list of all Grant configuration options](https://github.com/simov/grant#all-available-options) that are available:
|
|
|
|
| Key | Location | Description |
|
|
| :------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
|
|
| request_url | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth1/step1 |
|
|
| authorize_url | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth1/step2 or OAuth2/step1 |
|
|
| access_url | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth1/step3 or OAuth2/step2 |
|
|
| oauth | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth version number |
|
|
| scope_delimiter | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | string delimiter used for concatenating multiple scopes |
|
|
| protocol, host, path | `defaults` | used to generate `redirect_uri` |
|
|
| transport | `defaults` | [transport](#response-data-transport) to use to deliver the response data in your final `callback` route |
|
|
| state | `defaults` | toggle random `state` string generation for OAuth2 |
|
|
| key | `[provider]` | OAuth app key, reserved aliases: `consumer_key` and `client_id` |
|
|
| secret | `[provider]` | OAuth app secret, reserved aliases: `consumer_secret` and `client_secret` |
|
|
| scope | `[provider]` | list of scopes to request |
|
|
| custom_params | `[provider]` | custom authorization [parameters](#custom-parameters) and their values |
|
|
| subdomain | `[provider]` | string to be [embedded](#subdomain-urls) in `request_url`, `authorize_url` and `access_url` |
|
|
| nonce | `[provider]` | toggle random `nonce` string generation for [OpenID Connect](#openid-connect) providers |
|
|
| callback | `[provider]` | final callback route on your server to receive the [response data](#response-data) |
|
|
| dynamic | `[provider]` | allow [dynamic override](#dynamic-override) of configuration |
|
|
| overrides | `[provider]` | [static overrides](#static-overrides) for a provider |
|
|
| response | `[provider]` | [limit](#limit-response-data) the response data |
|
|
| token_endpoint_auth_method | `[provider]` | authentication method for the [token endpoint](#token-endpoint-auth-method) |
|
|
| name | generated | provider's [name](#grant), used to generate `redirect_uri` |
|
|
| profile_url | [grant-profile](https://github.com/simov/grant-profile) | The URL to retrieve the user profile from |
|
|
| [provider] | generated | provider's [name](#grant) as key |
|
|
| redirect_uri | generated | OAuth app [redirect URI](#redirect-uri), generated using `protocol`, `host`, `path` and `name` |
|
|
|
|
## OAuthStrategy
|
|
|
|
### entityId
|
|
|
|
`oauthStrategy.entityId -> string` returns the name of the id property of the entity.
|
|
|
|
### getEntityQuery(profile, params)
|
|
|
|
`oauthStrategy.getEntityQuery(profile, params) -> Promise` returns the entity lookup query to find the entity for a profile. By default returns
|
|
|
|
```js
|
|
{
|
|
[`${this.name}Id`]: profile.sub || profile.id
|
|
}
|
|
```
|
|
|
|
### getEntityData(profile, entity, params)
|
|
|
|
`oauthStrategy.getEntityData(profile, existing, params) -> Promise` returns the data to either create a new or update an existing entity. `entity` is either the existing entity or `null` when creating a new entity.
|
|
|
|
### getProfile(data, params)
|
|
|
|
`oauthStrategy.getProfile(data, params) -> Promise` returns the user profile information from the OAuth provider that was used for the login. `data` is the OAuth callback information which normally contains e.g. the OAuth access token.
|
|
|
|
### getRedirect (data)
|
|
|
|
`oauthStrategy.getRedirect(data) -> Promise` returns the URL to redirect to after a successful OAuth login and entity lookup or creation. By default it redirects to `authentication.oauth.redirect` from the configuration with `#access_token=<access token for entity>` added to the end of the URL. The `access_token` hash is e.g. used by the [authentication client](./client.md) to log the user in after a successful OAuth login. The default redirects do work cross domain.
|
|
|
|
### getAllowedOrigin (params)
|
|
|
|
`oauthStrategy.getAllowedOrigin(params) -> Promise` returns the redirect base URL or throws an error if it is not allowed.
|
|
|
|
### getCurrentEntity(params)
|
|
|
|
`oauthStrategy.getCurrentEntity(params) -> Promise` returns the currently linked entity for the given `params`. It will either use the entity authenticated by `params.authentication` or return `null`.
|
|
|
|
### findEntity(profile, params)
|
|
|
|
`oauthStrategy.findEntity(profile, params) -> Promise` finds an entity for a given OAuth profile. Uses `{ [${this.name}Id]: profile.id }` by default.
|
|
|
|
### createEntity(profile, params)
|
|
|
|
`oauthStrategy.createEntity(profile, params) -> Promise` creates a new entity for the given OAuth profile. Uses `{ [${this.name}Id]: profile.id }` by default.
|
|
|
|
### updateEntity(entity, profile, params)
|
|
|
|
`oauthStrategy.updateEntity(entity, profile, params) -> Promise` updates an existing entity with the given profile. Uses `{ [${this.name}Id]: profile.id }` by default.
|
|
|
|
### authenticate(authentication, params)
|
|
|
|
`oauthStrategy.authenticate(authentication, params)` is the main endpoint implemented by any [authentication strategy](./strategy.md). It is usually called for authentication requests for this strategy by the [AuthenticationService](./service.md).
|
|
|
|
## Customization
|
|
|
|
Normally, any OAuth provider set up in the [configuration](#configuration) will be initialized with the default [OAuthStrategy](#oauthstrategy). The flow for a specific provider can be customized by extending `OAuthStrategy` class and registering it under that name on the [AuthenticationService](./service.md):
|
|
|
|
```ts
|
|
import { Application } from '@feathersjs/feathers'
|
|
import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication'
|
|
import type { OAuthProfile } from '@feathersjs/authentication'
|
|
import { OAuthStrategy } from '@feathersjs/authentication-oauth'
|
|
|
|
declare module './declarations' {
|
|
interface ServiceTypes {
|
|
authentication: AuthenticationService
|
|
}
|
|
}
|
|
|
|
class MyGithubStrategy extends OAuthStrategy {
|
|
async getEntityData(profile: OAuthProfile) {
|
|
// Include the `email` from the GitHub profile when creating
|
|
// or updating a user that logged in with GitHub
|
|
const baseData = await super.getEntityData(profile)
|
|
|
|
return {
|
|
...baseData,
|
|
email: profile.email
|
|
}
|
|
}
|
|
}
|
|
|
|
export default (app: Application) => {
|
|
const authentication = new AuthenticationService(app)
|
|
|
|
authentication.register('github', new MyGithubStrategy())
|
|
|
|
// ...
|
|
app.use('authentication', authentication)
|
|
}
|
|
```
|