fix #17 provid example configs and better explanation for config items

vouch · Oct 11, 2018 · ae9218a · ae9218a
1 parent f3f7d00
commit ae9218a
Show file tree

Hide file tree

Showing 6 changed files with 170 additions and 18 deletions.
diff --git a/config/config.yml_example b/config/config.yml_example
@@ -5,14 +5,6 @@ lasso:
   listen: 0.0.0.0
   port: 9090
 
-  # set allowAllUsers: true to use Lasso to just accept anyone who can authenticate at the configured provider
-  allowAllUsers: false
-
-  # Setting publicAccess: true will accept all requests, even without a cookie. 
-  # If the user is logged in, the cookie will be validated and the user header will be set.
-  # You will need to direct people to the Lasso login page from your application.
-  publicAccess: false
-
   # each of these domains must serve the url https://lasso.$domains[0] https://lasso.$domains[1] ...
   # so that the cookie which stores the JWT can be set in the relevant domain
   # usually you'll just have one.
@@ -21,22 +13,39 @@ lasso:
   - yourdomain.com
   - yourotherdomain.com
 
+  # set allowAllUsers: true to use Lasso to just accept anyone who can authenticate at the configured provider
+  allowAllUsers: false
+
+  # Setting publicAccess: true will accept all requests, even without a cookie. 
+  # If the user is logged in, the cookie will be validated and the user header will be set.
+  # You will need to direct people to the Lasso login page from your application.
+  publicAccess: false
+
   jwt:
+    # secret: a random 18 character string used to cryptographically sign the jwt
+    # if the secret is not set here then..
+    # look for the secret in `./config/secret`
+    # if `./config/secret` doesn't exist then randomly generate a secret and store it there
+    # in order to run multiple instances of lasso on multiple servers (perhaps purely for validating the jwt),
+    # you'll want them all to have the same secret
+    secret: your_random_string
     issuer: Lasso
+    # number of seconds until jwt expires
     maxAge: 240
-    secret: your_random_string
+    # compress the jwt
     compress: true
 
   cookie: 
     # name of cookie to store the jwt
-    name: Lasso-cookie
+    name: LassoCookie
     # optionally force the domain of the cookie to set
     # domain: yourdomain.com
     secure: true
     httpOnly: true
 
   session:
-    name: lasso-session
+    # just the name of session variable stored locally
+    name: lassoSession
 
   headers:
     jwt: X-Lasso-Token
@@ -46,13 +55,18 @@ lasso:
   db: 
     file: data/lasso_bolt.db
 
+  # testing: force all 302 redirects to be rendered as a webpage with a link
+  testing: true
+  # test_url: add this URL to the page which lasso displays
   test_url: http://yourdomain.com
+  # webapp: WIP for web interface to lasso (mostly logs)
+  webapp: true
 
 #
-# OAuth Provider Config
+# OAuth Provider
+# configure ONLY ONE of the following oauth providers
 #
 oauth:
-  # configure only one of the following
 
   # Google
   provider: google
@@ -70,13 +84,14 @@ oauth:
   provider: github
   client_id:
   client_secret:
-  auth_url: https://github.com/login/oauth/authorize
-  token_url: https://github.com/login/oauth/access_token
   # callback_url is configured at github.com when setting up the app
   # set to e.g. https://lasso.yourdomain.com/auth
-  scopes:
-    - user
-  user_info_url: https://api.github.com/user?access_token=
+  # defaults (uncomment and change these if you are using github enterprise on-prem)
+  # auth_url: https://github.com/login/oauth/authorize
+  # token_url: https://github.com/login/oauth/access_token
+  # user_info_url: https://api.github.com/user?access_token=
+  # scopes:
+    # - user
 
   # Generic OpenID Connect
   provider: oidc

diff --git a/config/config.yml_example_github b/config/config.yml_example_github
@@ -0,0 +1,31 @@
+
+# lasso config
+# bare minimum to get lasso running with github
+
+lasso:
+  # domains:
+  # valid domains that the jwt cookies can be set into
+  # the callback_urls will be to these domains
+  # for github that's only one domain since they only allow one callback URL
+  # https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#redirect-urls
+  # each of these domains must serve the url https://login.$domains[0] https://login.$domains[1] ...
+  domains:
+  - yourothersite.io
+
+  # set allowAllUsers: true to use Lasso to just accept anyone who can authenticate at GitHub
+  # allowAllUsers: true
+
+oauth:
+  # create a new OAuth application at:
+  # https://github.com/settings/applications/new
+  provider: github
+  client_id: xxxxxxxxxxxxxxxxxxxx
+  client_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+  # these GitHub OAuth defaults are set for you..
+  # from https://godoc.org/golang.org/x/oauth2/github
+  # auth_url: https://github.com/login/oauth/authorize
+  # token_url: https://github.com/login/oauth/access_token
+  # scopes:
+  #   - user
+  # user_info_url: https://api.github.com/user?access_token=
diff --git a/config/config.yml_example_github_enterprise b/config/config.yml_example_github_enterprise
@@ -0,0 +1,31 @@
+# lasso config
+# bare minimum to get lasso running with github enterprise
+# see config.yml_example for all options
+
+lasso:
+  # domains:
+  # valid domains that the jwt cookies can be set into
+  # each of these domains must serve the url https://login.$domains[0] https://login.$domains[1] ...
+  # the callback_urls will be to these domains
+  domains:
+  - yoursite.com
+  - yourothersite.io
+
+  # - OR -
+  # instead of setting specific domains you may prefer to allow all users...
+  # set allowAllUsers: true to use Lasso to just accept anyone who can authenticate at the configured provider
+  # allowAllUsers: true
+
+oauth:
+  # create a new OAuth application at:
+  # https://githubenterprise.yoursite.com/settings/applications/new
+  provider: github
+  client_id: xxxxxxxxxxxxxxxxxxxx
+  client_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+  auth_url: https://githubenterprise.yoursite.com/login/oauth/authorize
+  token_url: https://githubenterprise.yoursite.com/login/oauth/access_token
+  user_info_url: https://githubenterprise.yoursite.com/user?access_token=
+
+  # these GitHub OAuth defaults are set for you..
+  # scopes:
+  #   - user
diff --git a/config/config.yml_example_google b/config/config.yml_example_google
@@ -0,0 +1,20 @@
+
+# lasso config
+# bare minimum to get lasso running with google
+
+lasso:
+  domains:
+  - yourdomain.com
+  - yourotherdomain.com
+
+oauth:
+  provider: google
+  # get credentials from...
+  # https://console.developers.google.com/apis/credentials
+  client_id: xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
+  client_secret: xxxxxxxxxxxxxxxxxxxxxxxx
+  callback_urls: 
+    - http://yourdomain.com:9090/auth
+    - http://yourotherdomain.com:9090/auth
+  preferredDomain: yourdomain.com
+  # endpoints set from https://godoc.org/golang.org/x/oauth2/google
diff --git a/config/config.yml_example_indieauth b/config/config.yml_example_indieauth
@@ -0,0 +1,24 @@
+
+# lasso config
+# bare minimum to get lasso running with IndieAuth
+
+lasso:
+  # domains:
+  # valid domains that the jwt cookies can be set into
+  # the callback_urls will be to these domains
+  domains:
+  - yourdomain.com
+
+  # set allowAllUsers: true to use Lasso to just accept anyone who can authenticate at the configured provider
+  allowAllUsers: true
+
+  # Setting publicAccess: true will accept all requests, even without a cookie. 
+  publicAccess: true
+
+oauth:
+  # IndieAuth
+  # https://indielogin.com/api
+  provider: indieauth
+  client_id: http://yourdomain.com
+  auth_url: https://indielogin.com/auth
+  callback_url: http://lasso.yourdomain.com:9090/auth
diff --git a/config/config.yml_example_oidc b/config/config.yml_example_oidc
@@ -0,0 +1,31 @@
+
+# lasso config
+# bare minimum to get lasso running with OpenID Connect (such as okta)
+
+lasso:
+  # domains:
+  # valid domains that the jwt cookies can be set into
+  # the callback_urls will be to these domains
+  domains:
+  - yourdomain.com
+  - yourotherdomain.com
+
+  # - OR -
+  # instead of setting specific domains you may prefer to allow all users...
+  # set allowAllUsers: true to use Lasso to just accept anyone who can authenticate at the configured provider
+  # allowAllUsers: true
+
+oauth:
+  # Generic OpenID Connect
+  # including okta
+  provider: oidc
+  client_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+  client_secret: xxxxxxxxxxxxxxxxxxxxxxxx
+  auth_url: https://{yourOktaDomain}/oauth2/default/v1/authorize
+  token_url: https://{yourOktaDomain}/oauth2/default/v1/token
+  user_info_url: https://{yourOktaDomain}/oauth2/default/v1/userinfo
+  scopes:
+    - openid
+    - email
+    - profile
+  callback_url: http://lasso.yourdomain.com:9090/auth