README.md

   1 # netlify-serverless-oauth2-backend
   2
   3 This is an AWS Lambda based service to help perform authentication to Github via an OAuth2 authentication process.
   4
   5
   6 ## Installation
   7
   8 ```
   9 sudo npm -i serverless -g
  10 npm i
  11 ```
  12
  13 ## Configuration
  14
  15 This code can be run either locally (using the serverless-offline plugin) or deployed in AWS.
  16
  17 ### Offline
  18
  19 To run it locally:
  20
  21 ```
  22 sls offline
  23 ```
  24
  25 Before running it, update auth.js to reflect your desired configuration. The settings are defined in the initialization of the Secrets class:
  26
  27 ```
  28 // Change this stuff in auth.js to reflect your own dev testing
  29 const secrets = new Secrets({
  30   GIT_HOSTNAME: 'https://github.com',
  31   OAUTH_TOKEN_PATH: '/login/oauth/access_token',
  32   OAUTH_AUTHORIZE_PATH: '/login/oauth/authorize',
  33   OAUTH_CLIENT_ID: 'foo',
  34   OAUTH_CLIENT_SECRET: 'bar',
  35   REDIRECT_URL: 'http://localhost:3000/oauth/callback',
  36   OAUTH_SCOPES: 'repo,user',
  37 });
  38 ```
  39
  40 For this to work you'll also need to have your OAuth2 app setup properly in Github (and redirecting to the same callback url).
  41
  42 ### AWS Deployment
  43
  44 To deploy the Lambda function, you'll need to update serverless.yml and set your KMS key for the parameter store.
  45
  46 To grab the key id:
  47
  48 ```
  49 aws kms describe-key --key-id alias/aws/ssm --profile <YOURAWSPROFILE> --region <REGION>
  50 ```
  51
  52 ex:
  53
  54 ```
  55 aws kms describe-key --key-id alias/aws/ssm --profile ctrl-alt-del --region us-east-1
  56 ```
  57
  58 If you're unfamiliar with AWS profiles, see this documentation: https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html
  59
  60 Once you've added your key uuid to the serverless.yml configuration (mapping it to the correct region and stage), it's time to deploy the code.
  61
  62 ```
  63 sls deploy -s <STAGE> --aws-profile <YOURAWSPROFILE> --region <REGION>
  64 ```
  65
  66 Ex:
  67
  68 ```
  69 sls deploy -s prod --aws-profile ctrl-alt-del --region us-east-1
  70 ```
  71
  72 Finally, once the code is deployed you need to add some parameters to the AWS parameter store.
  73
  74 Head on over to the AWS console, find the Systems manager, and go to the Parameter store.
  75
  76 In there, you'll want to create the following parameters/values (as SecureStrings):
  77
  78 * /ctrl-alt-del/oauth/<STAGE>/GIT_HOSTNAME - The github host to use. Ex: https://github.com
  79 * /ctrl-alt-del/oauth/<STAGE>/OAUTH_TOKEN_PATH - The token api uri path. Most probably this: /login/oauth/access_token
  80 * /ctrl-alt-del/oauth/<STAGE>/OAUTH_AUTHORIZE_PATH - The authorize api uri path. Most probably this: /login/oauth/authorize
  81 * /ctrl-alt-del/oauth/<STAGE>/OAUTH_CLIENT_ID - Your Github OAuth client id
  82 * /ctrl-alt-del/oauth/<STAGE>/OAUTH_CLIENT_SECRET - Your Github OAuth client secret
  83 * /ctrl-alt-del/oauth/<STAGE>/REDIRECT_URL - Your callback URL. It will look something like this: https://RANDOMSTUFF.execute-api.us-east-1.amazonaws.com/<STAGE>/callback
  84 * /ctrl-alt-del/oauth/<STAGE>/OAUTH_SCOPES - The scopes to grant. Probably this: repo,user
  85