@travetto/auth-passport/README.md

Rest authentication integration support for the travetto framework

<!-- This file was generated by @travetto/doc and should not be modified directly -->
<!-- Please modify https://github.com/travetto/travetto/tree/main/module/auth-passport/doc.ts and execute "npx trv doc" to rebuild -->
# Rest Auth Passport
## Rest authentication integration support for the travetto framework

**Install: @travetto/auth-passport**
```bash
npm install @travetto/auth-passport
```

This is a primary integration for the [Rest Auth](https://github.com/travetto/travetto/tree/main/module/auth-rest#readme "Rest authentication integration support for the travetto framework") module.  This is another level of scaffolding allowing for compatible authentication frameworks to integrate.  

Within the node ecosystem, the most prevalent auth framework is [passport](http://passportjs.org).  With countless integrations, the desire to leverage as much of it as possible, is extremely high. To that end, this module provides support for [passport](http://passportjs.org) baked in. Registering and configuring a [passport](http://passportjs.org) strategy is fairly straightforward.

**Code: Sample Facebook/passport config**
```typescript
import { Strategy as FacebookStrategy } from 'passport-facebook';

import { InjectableFactory } from '@travetto/di';
import { Authenticator, Authorizer, Principal } from '@travetto/auth';
import { PassportAuthenticator } from '@travetto/auth-passport';

export class FbUser {
  username: string;
  roles: string[];
}

export const FB_AUTH = Symbol.for('auth_facebook');

export class AppConfig {
  @InjectableFactory(FB_AUTH)
  static facebookPassport(): Authenticator {
    return new PassportAuthenticator('facebook',
      new FacebookStrategy(
        {
          clientID: '<appId>',
          clientSecret: '<appSecret>',
          callbackURL: 'http://localhost:3000/auth/facebook/callback',
          profileFields: ['id', 'username', 'displayName', 'photos', 'email'],
        },
        (accessToken, refreshToken, profile, cb) =>
          cb(undefined, profile)
      ),
      (user: FbUser) => ({
        id: user.username,
        permissions: user.roles,
        details: user
      })
    );
  }

  @InjectableFactory()
  static principalSource(): Authorizer {
    return new class implements Authorizer {
      async authorize(p: Principal) {
        return p;
      }
    }();
  }
}
```

As you can see, [PassportAuthenticator](https://github.com/travetto/travetto/tree/main/module/auth-passport/src/authenticator.ts#L14) will take care of the majority of the work, and all that is required is:
   
   *  Provide the name of the strategy (should be unique)
   *  Provide the strategy instance. **Note**: you will need to provide the callback for the strategy to ensure you pass the external principal back into the framework
   *  The conversion functions which defines the mapping between external and local identities.

After that, the provider is no different than any other, and can be used accordingly.  Additionally, because [passport](http://passportjs.org) runs first, in it's entirety, you can use the provider as you normally would any [passport](http://passportjs.org) middleware.

**Code: Sample routes using Facebook/passport provider**
```typescript
import { Controller, Get, Redirect, Post, Request } from '@travetto/rest';
import { AuthService, Authenticate, Authenticated, Unauthenticated } from '@travetto/auth-rest';
import { Inject } from '@travetto/di';

import { FB_AUTH } from './conf';

@Controller('/auth')
export class SampleAuth {

  @Inject()
  auth: AuthService;

  @Get('/name')
  async getName() {
    return { name: 'bob' };
  }

  @Get('/facebook')
  @Authenticate(FB_AUTH)
  async fbLogin() {

  }

  @Get('/self')
  @Authenticated()
  async getSelf(req: Request) {
    return req.auth;
  }

  @Get('/facebook/callback')
  @Authenticate(FB_AUTH)
  async fbLoginComplete() {
    return new Redirect('/auth/self', 301);
  }

  @Post('/logout')
  @Unauthenticated()
  async logout(req: Request) {
    await this.auth.logout(req);
  }

  /**
   * Simple Echo
   */
  @Post('/')
  async echo(req: Request): Promise<object> {
    return req.body;
  }
}
```