config.yml_example

# Vouch Proxy configuration

# you should probably start with one of the other example configs in this directory
# Vouch Proxy does a fairly good job of setting its config to sane defaults

# be aware of the yaml indentation, the only top level elements are `vouch` and `oauth`. 

# Vouch Proxy can also be configured using Environmental Variables.  The associated env var for
# each configuration is shown such as VOUCH_LOGLEVEL.

vouch:
  # logLevel: debug # VOUCH_LOGLEVEL
  logLevel: info

  # testing: false - VOUCH_TESTING
  # force all 302 redirects to be rendered as a webpage with a link
  # if you're having problems, turn on testing
  testing: true

  listen: 0.0.0.0  # VOUCH_LISTEN
  port: 9090       # VOUCH_PORT

  # Listen can specify a Unix domain socket instead.
  # listen: unix:/path/to/socket # VOUCH_LISTEN

  # Optionally set the mode of the Unix domain socket. The default if not specified is 0777.
  # socket_mode: 0770 # VOUCH_SOCKETMODE

  # Optionally set the group owner of the Unix domain socket.
  # socket_group: users # VOUCH_SOCKETGROUP

  # The default read, write and idle timeouts are 15 seconds.
  # If you have a load balancer or proxy in front that has its
  # own idle timeout, you may need to ensure that the Vouch idle
  # timeout is longer than the proxy's, to avoid intermittent
  # 502 errors.
  # See https://github.com/vouch/vouch-proxy/issues/317 for more
  # information.
  writeTimeout: 15 # VOUCH_WRITETIMEOUT
  readTimeout: 15  # VOUCH_READTIMEOUT
  idleTimeout: 15  # VOUCH_IDLETIMEOUT

  # document_root - VOUCH_DOCUMENT_ROOT
  # see README for `Vouch Proxy "in a path"` - https://github.com/vouch/vouch-proxy#vouch-proxy-in-a-path
  # document_root: vp_in_a_path

  # domains - VOUCH_DOMAINS
  # each of these domains must serve the url https://vouch.$domains[0] https://vouch.$domains[1] ...
  # so that the cookie which stores the JWT can be set in the relevant domain
  # you usually *don't* want to list every individual website that will be protected
  # if you have siteA.internal.yourdomain.com and siteB.internal.yourdomain.com 
  # then your domains should be set as yourdomain.com or perhaps internal.yourdomain.com   
  # usually you'll just have one.
  # Comment `domains:` out if you set allowAllUser:true
  domains:
  - yourdomain.com
  - yourotherdomain.com

  # Set allowAllUsers: true to use Vouch Proxy to just accept anyone who can authenticate at the configured provider - VOUCH_ALLOWALLUSERS
  # allowAllUsers: false
  # vouch.cookie.domain must be set below when enabling allowAllUsers

  # Setting publicAccess: true will accept all requests, even without a valid jwt/cookie.  - VOUCH_PUBLICACCESS
  # 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 Vouch Proxy login page from your application.
  # publicAccess: false

  # whiteList (optional) allows only the listed usernames - VOUCH_WHITELIST
  # usernames are usually email addresses (google, most oidc providers) or login/username for github and github enterprise
  whiteList:
  - bob@yourdomain.com
  - alice@yourdomain.com
  - joe@yourdomain.com

  # teamWhitelist - VOUCH_TEAMWHITELIST
  # only used for github orgs/teams
  # teamWhitelist:
  # - vouch
  # - myOrg
  # - myOrg/myTeam

  tls:
    # cert: /path/to/signed_cert_plus_intermediates # VOUCH_TLS_CERT
    # key: /path/to/private_key                     # VOUCH_TLS_KEY
    # profile - defines the TLS configuration profile (modern, intermediate, old, default)
    profile: intermediate                           # VOUCH_TLS_PROFILE

  jwt:
    # signing_method: the algorithm used to sign the JWT.  # VOUCH_JWT_SIGNING_METHOD
    # Can be one of HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512
    # Default is HS256 (HMAC) - and requires jwt.secret to be set
    # Both RS* (RSA) and ES* (ECDSA) methods require jwt.private_key_file and
    # jwt.public_key_file to be set.
    # signing_method: HS256

    # secret - VOUCH_JWT_SECRET
    # a random string used to cryptographically sign the jwt when signing_method is set to HS256, HS384 or HS512
    # Vouch Proxy complains if the string is less than 44 characters (256 bits as 32 base64 bytes)
    # if the secret is not set here then Vouch Proxy will..
    # - 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 vouch on multiple servers (perhaps purely for validating the jwt),
    # you'll want them all to have the same secret
    secret: your_random_string

    # Path to the public/private key files when using an RSA or ECDSA signing method.
    # public_key_file:  # VOUCH_JWT_PUBLIC_KEY_FILE
    # private_key_file: # VOUCH_JWT_PRIVATE_KEY_FILE

    # issuer: Vouch # VOUCH_JWT_ISSUER

    # number of minutes until jwt expires - VOUCH_JWT_MAXAGE
    maxAge: 240

    # compress the jwt - VOUCH_JWT_COMPRESS
    compress: true 

  cookie: 
    # name of cookie to store the jwt - VOUCH_COOKIE_NAME
    name: VouchCookie

    # optionally force the domain of the cookie to set
    # domain: yourdomain.com # VOUCH_COOKIE_DOMAIN

    # Set `secure: false` when protecting a non-https site such as http://app.yourdmain.com - VOUCH_COOKIE_SECURE
    secure: true

    # httpOnly: true # VOUCH_COOKIE_HTTPONLY

    # Number of minutes until session cookie expires - VOUCH_COOKIE_MAXAGE
    # Set cookie maxAge to 0 to delete the cookie every time the browser is closed.
    # Must not be longer than jwt.maxAge
    maxAge: 240

    # Set SameSite attribute to restrict browser behaviour wrt sending the cookie along with cross-site requests. - VOUCH_COOKIE_SAMESITE
    # Possible attribute values lax, strict, none.
    # If attribute not specified then cross-site behaviour will depend on the browser used. If sameSite=none then secure must be set to true
    # More context: https://github.com/vouch/vouch-proxy/issues/210
    sameSite: lax

  session:
    # name of session variable stored locally - VOUCH_SESSION_NAME
    name: VouchSession
    # number of minutes for maximum session age, configuring how long the user has to login at their IdP (defaults to 5) - VOUCH_SESSION_MAXAGE
    maxAge: 5
    # key - a cryptographic string used to store the session variable - VOUCH_SESSION_KEY
    # if the key is not set here then it is generated at startup and stored in memory
    # Vouch Proxy complains if the string is less than 44 characters (256 bits as 32 base64 bytes)
    # you only want to set this if you're running multiple user facing vouch.yourdomain.com instances
    # where each instance may rely on a session cookie for state or the original requested URL
    # key: your_random_key


  headers:
    jwt: X-Vouch-Token                # VOUCH_HEADERS_JWT
    querystring: access_token         # VOUCH_HEADERS_QUERYSTRING
    redirect: X-Vouch-Requested-URI   # VOUCH_HEADERS_REDIRECT

    # GENERAL WARNING ABOUT claims AND tokens
    # all of these config elements can cause performance impacts due to the amount of information being 
    # moved around.  They will get added to the Vouch cookie and (possibly) make it large.  The Vouch cookie will 
    # get split up into several cookies. But if you need it, you need it.
    # With large cookies and headers it will require additional nginx config to open up the buffers a bit..
    # see `large_client_header_buffers` http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers
    # and `proxy_buffer_size` http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size

    # claims - a list of claims that will be stored in the JWT and passed down to applications via headers - VOUCH_HEADERS_CLAIMS
    # By default claims are sent down as headers with a prefix of X-Vouch-IdP-Claims-ClaimKey
    # Only when a claim is found in the user's info will the header exist.  This is optional.  These are case sensitive.
    claims:
      - groups
      - given_name
    # these will result in two headers being passed back to nginx as the headers
    #   X-Vouch-IdP-Claims-Groups: groupa, groupb, groupc
    #   X-Vouch-IdP-Claims-Given-Name: Robert
    # nginx will populate the variables
    #   $auth_resp_x_vouch_idp_claims_groups
    #   $auth_resp_x_vouch_idp_claims_given-name
    # see https://github.com/vouch/vouch-proxy/issues/183 regarding claims and header naming

    # claimheader - Customizable claim header prefix (instead of default `X-Vouch-IdP-Claims-`) - VOUCH_HEADERS_CLAIMHEADER
    # claimheader: My-Custom-Claim-Prefix

    # accesstoken - Pass the user's access token from the provider.  This is useful if you need to pass the IdP token to a downstream - VOUCH_HEADERS_ACCESSTOKEN
    # application. This is optional.
    # accesstoken: X-Vouch-IdP-AccessToken
    # idtoken - Pass the user's Id token from the provider.  This is useful if you need to pass this token to a downstream - VOUCH_HEADERS_IDTOKEN
    # application. This is optional.
    # idtoken: X-Vouch-IdP-IdToken

  # test_url - add this URL to the page which vouch displays during testing (a convenience for testing) - VOUCH_TESTURL
  test_url: http://yourdomain.com

  # post_logout_redirect_uris - VOUCH_POST_LOGOUT_REDIRECT_URIS
  # in order to prevent redirection attacks all redirected URLs to /logout must be specified
  # the URL must still be passed to Vouch Proxy as https://vouch.yourdomain.com/logout?url=${ONE OF THE URLS BELOW}
  # in line with the OIDC spec https://openid.net/specs/openid-connect-session-1_0.html#RedirectionAfterLogout
  post_logout_redirect_uris:
    # your apps login page
    - http://myapp.yourdomain.com/login
    # your IdPs logout enpoint
    # from https://accounts.google.com/.well-known/openid-configuration
    - https://oauth2.googleapis.com/revoke
    # you may be daisy chaining to your IdP
    - https://myorg.okta.com/oauth2/123serverid/v1/logout?post_logout_redirect_uri=http://myapp.yourdomain.com/login


#
# OAuth
#

# environmental variables for OAuth config:
#   provider:                OAUTH_PROVIDER
#   client_id:               OAUTH_CLIENT_ID
#   client_secret:           OAUTH_CLIENT_SECRET
#   auth_url:                OAUTH_AUTH_URL
#   token_url:               OAUTH_TOKEN_URL
#   end_session_endpoint:    OAUTH_END_SESSION_ENDPOINT
#   callback_url:            OAUTH_CALLBACK_URL
#   user_info_url:           OAUTH_USER_INFO_URL
#   user_team_url:           OAUTH_USER_TEAM_URL
#   user_org_url:            OAUTH_USER_ORG_URL
#   preferreddomain:         OAUTH_PREFERREDDOMAIN
#   callback_urls:           OAUTH_CALLBACK_URLS
#   scopes:                  OAUTH_SCOPES
#   claims:                  OAUTH_CLAIMS
#   code_challenge_method:   OAUTH_CODE_CHALLENGE_METHOD
#   relying_party_id         OAUTH_RELYING_PARTY_ID

#
# configure ONLY ONE of the following oauth providers
#

oauth:

  # Google
  provider: google
  # create new credentials at:
  # https://console.developers.google.com/apis/credentials
  client_id: 
  client_secret: 
  callback_urls:
    - http://vouch.yourdomain.com:9090/auth
    - http://vouch.yourotherdomain.com:9090/auth
  preferredDomain: yourdomain.com
  # optionally set scopes, defaults to 'email'
  # https://developers.google.com/identity/protocols/googlescopes#google_sign-in
  # scopes:
  #  - email

  # GitHub
  # https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-authorization-options-for-oauth-apps/
  provider: github
  client_id:
  client_secret:
  # callback_url is configured at github.com when setting up the app
  # Set to e.g. https://vouch.yourdomain.com/auth
  # 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
  client_id: 
  client_secret: 
  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
  # end_session_endpoint is usually the IdP's logout URL
  # see https://github.com/vouch/vouch-proxy/pull/258
  end_session_endpoint: https://{yourOktaDomain}/oauth2/default/v1/logout
  scopes:
    - openid
    - email
    - profile
  callback_url: http://vouch.yourdomain.com:9090/auth
  # optionally set the "claims" request parameter (see https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter)
  # required by Twitch, resolves issue https://github.com/vouch/vouch-proxy/issues/414
  # claims:
    # userinfo:
      # given_name:
        # essential: true
      # nickname: null
      # email:
        # essential: true
      # email_verified:
        # essential: true
      # picture: null
      # "http://example.info/claims/groups": null
    # id_token:
      # auth_time:
        # essential: true
      # acr:
        # values:
          # - "urn:mace:incommon:iap:silver"
  # PKCE method if enabled, S256 is currently supported (check https://www.oauth.com/oauth2-servers/pkce/)
  # resolves issue https://github.com/vouch/vouch-proxy/issues/303
  code_challenge_method: S256

  # IndieAuth
  # https://indielogin.com/api
  provider: indieauth
  client_id: http://yourdomain.com
  auth_url: https://indielogin.com/auth
  callback_url: http://vouch.yourdomain.com:9090/auth

  # adfs
  provider: adfs
  client_id:
  client_secret:
  auth_url: https://adfs.yourdomain.com/adfs/oauth2/authorize/
  token_url: https://adfs.yourdomain.com/adfs/oauth2/token/
  # vouch-proxy use RedirectURL as relying party identifier by default, if you want a custom one:
  # see https://github.com/vouch/vouch-proxy/issues/189
  # relying_party_id:  487d8ff7-80a8-4f62-b926-c2852ab06e94
  scopes:
    - openid
    - email
    - profile
  callback_url: https://vouch.yourdomain.com/auth