docs: format with prettier (#1218)
This commit is contained in:
Patrik Oldsberg
@@ -2,17 +2,21 @@
|
||||
|
||||
## Passport
|
||||
|
||||
We chose [Passport](http://www.passportjs.org/) as our authentication platform due to its comprehensive set of supported authentication [strategies](http://www.passportjs.org/packages/).
|
||||
We chose [Passport](http://www.passportjs.org/) as our authentication platform
|
||||
due to its comprehensive set of supported authentication
|
||||
[strategies](http://www.passportjs.org/packages/).
|
||||
|
||||
## How to add a new strategy provider
|
||||
|
||||
### Quick guide
|
||||
|
||||
[1.](#installing-the-dependencies) Install the passport-js based provider package.
|
||||
[1.](#installing-the-dependencies) Install the passport-js based provider
|
||||
package.
|
||||
|
||||
[2.](#create-implementation) Create a new folder structure for the provider.
|
||||
|
||||
[3.](#adding-an-oauth-based-provider) Implement the provider, extending the suitable framework if needed.
|
||||
[3.](#adding-an-oauth-based-provider) Implement the provider, extending the
|
||||
suitable framework if needed.
|
||||
|
||||
[4.](#hook-it-up-to-the-backend) Add the provider to the backend.
|
||||
|
||||
@@ -26,7 +30,8 @@ yarn add @types/passport-provider-a
|
||||
|
||||
### Create implementation
|
||||
|
||||
Make a new folder with the name of the provider following the below file structure:
|
||||
Make a new folder with the name of the provider following the below file
|
||||
structure:
|
||||
|
||||
```bash
|
||||
plugins/auth-backend/src/providers/providerA
|
||||
@@ -34,13 +39,16 @@ plugins/auth-backend/src/providers/providerA
|
||||
└── provider.ts
|
||||
```
|
||||
|
||||
**`plugins/auth-backend/src/providers/providerA/provider.ts`** defines the provider class which implements a handler for the chosen framework.
|
||||
**`plugins/auth-backend/src/providers/providerA/provider.ts`** defines the
|
||||
provider class which implements a handler for the chosen framework.
|
||||
|
||||
#### Adding an OAuth based provider
|
||||
|
||||
If we're adding an `OAuth` based provider we would implement the [OAuthProviderHandlers](#OAuthProviderHandlers) interface.
|
||||
If we're adding an `OAuth` based provider we would implement the
|
||||
[OAuthProviderHandlers](#OAuthProviderHandlers) interface.
|
||||
|
||||
The provider class takes the provider's configuration as a class parameter. It also imports the `Strategy` from the passport package.
|
||||
The provider class takes the provider's configuration as a class parameter. It
|
||||
also imports the `Strategy` from the passport package.
|
||||
|
||||
```ts
|
||||
import { Strategy as ProviderAStrategy } from 'passport-provider-a';
|
||||
@@ -64,9 +72,11 @@ export class ProviderAAuthProvider implements OAuthProviderHandlers {
|
||||
|
||||
#### Adding an non-OAuth based provider
|
||||
|
||||
_**Note**: We have prioritized OAuth-based providers and non-OAuth providers should be considered experimental._
|
||||
_**Note**: We have prioritized OAuth-based providers and non-OAuth providers
|
||||
should be considered experimental._
|
||||
|
||||
An non-`OAuth` based provider could implement [AuthProviderRouteHandlers](#AuthProviderRouteHandlers) instead.
|
||||
An non-`OAuth` based provider could implement
|
||||
[AuthProviderRouteHandlers](#AuthProviderRouteHandlers) instead.
|
||||
|
||||
```ts
|
||||
export class ProviderAAuthProvider implements AuthProviderRouteHandlers {
|
||||
@@ -90,9 +100,12 @@ export class ProviderAAuthProvider implements AuthProviderRouteHandlers {
|
||||
|
||||
#### Create method
|
||||
|
||||
Each provider exports a create method that creates the provider instance, optionally extending a supported authorization framework. This method exists to allow for flexibility if additional frameworks are supported in the future.
|
||||
Each provider exports a create method that creates the provider instance,
|
||||
optionally extending a supported authorization framework. This method exists to
|
||||
allow for flexibility if additional frameworks are supported in the future.
|
||||
|
||||
Implementing OAuth by returning an instance of `OAuthProvider` based of the provider's class:
|
||||
Implementing OAuth by returning an instance of `OAuthProvider` based of the
|
||||
provider's class:
|
||||
|
||||
```ts
|
||||
export function createProviderAProvider(config: AuthProviderConfig) {
|
||||
@@ -102,7 +115,9 @@ export function createProviderAProvider(config: AuthProviderConfig) {
|
||||
}
|
||||
```
|
||||
|
||||
Not extending with OAuth, the main difference here is that the create method is returning a instance of the class without adding the OAuth authorization framework to it.
|
||||
Not extending with OAuth, the main difference here is that the create method is
|
||||
returning a instance of the class without adding the OAuth authorization
|
||||
framework to it.
|
||||
|
||||
```ts
|
||||
export function createProviderAProvider(config: AuthProviderConfig) {
|
||||
@@ -112,14 +127,22 @@ export function createProviderAProvider(config: AuthProviderConfig) {
|
||||
|
||||
#### Verify Callback
|
||||
|
||||
> Strategies require what is known as a verify callback. The purpose of a verify callback is to find the user that possesses a set of credentials.
|
||||
> When Passport authenticates a request, it parses the credentials contained in the request. It then invokes the verify callback with those credentials as arguments [...]. If the credentials are valid, the verify callback invokes done to supply Passport with the user that authenticated.
|
||||
> Strategies require what is known as a verify callback. The purpose of a verify
|
||||
> callback is to find the user that possesses a set of credentials. When
|
||||
> Passport authenticates a request, it parses the credentials contained in the
|
||||
> request. It then invokes the verify callback with those credentials as
|
||||
> arguments [...]. If the credentials are valid, the verify callback invokes
|
||||
> done to supply Passport with the user that authenticated.
|
||||
>
|
||||
> If the credentials are not valid (for example, if the password is incorrect), done should be invoked with false instead of a user to indicate an authentication failure.
|
||||
> If the credentials are not valid (for example, if the password is incorrect),
|
||||
> done should be invoked with false instead of a user to indicate an
|
||||
> authentication failure.
|
||||
>
|
||||
> http://www.passportjs.org/docs/configure/
|
||||
|
||||
**`plugins/auth-backend/src/providers/providerA/index.ts`** is simply re-exporting the create method to be used for hooking the provider up to the backend.
|
||||
**`plugins/auth-backend/src/providers/providerA/index.ts`** is simply
|
||||
re-exporting the create method to be used for hooking the provider up to the
|
||||
backend.
|
||||
|
||||
```ts
|
||||
export { createProviderAProvider } from './provider';
|
||||
@@ -127,7 +150,9 @@ export { createProviderAProvider } from './provider';
|
||||
|
||||
### Hook it up to the backend
|
||||
|
||||
**`plugins/auth-backend/src/providers/config.ts`** The provider needs to be configured properly so you need to add it to the list of configured providers, all of which implement [AuthProviderConfig](#AuthProviderConfig):
|
||||
**`plugins/auth-backend/src/providers/config.ts`** The provider needs to be
|
||||
configured properly so you need to add it to the list of configured providers,
|
||||
all of which implement [AuthProviderConfig](#AuthProviderConfig):
|
||||
|
||||
```ts
|
||||
export const providers = [
|
||||
@@ -138,7 +163,10 @@ export const providers = [
|
||||
},
|
||||
```
|
||||
|
||||
**`plugins/auth-backend/src/providers/factories.ts`** When the `auth-backend` starts it sets up routing for all the available providers by calling `createAuthProviderRouter` on each provider. You need to import the create method from the provider and add it to the factory:
|
||||
**`plugins/auth-backend/src/providers/factories.ts`** When the `auth-backend`
|
||||
starts it sets up routing for all the available providers by calling
|
||||
`createAuthProviderRouter` on each provider. You need to import the create
|
||||
method from the provider and add it to the factory:
|
||||
|
||||
```ts
|
||||
import { createProviderAProvider } from './providerA';
|
||||
@@ -157,11 +185,14 @@ router.post('/auth/providerA/logout');
|
||||
router.get('/auth/providerA/refresh'); // if supported
|
||||
```
|
||||
|
||||
As you can see each endpoint is prefixed with both `/auth` and its provider name.
|
||||
As you can see each endpoint is prefixed with both `/auth` and its provider
|
||||
name.
|
||||
|
||||
### Test the new provider
|
||||
|
||||
You can `curl -i localhost:7000/auth/providerA/start` and which should provide a `302` redirect with a `Location` header. Paste the url from that header into a web browser and you should be able to trigger the authorization flow.
|
||||
You can `curl -i localhost:7000/auth/providerA/start` and which should provide a
|
||||
`302` redirect with a `Location` header. Paste the url from that header into a
|
||||
web browser and you should be able to trigger the authorization flow.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user