Forge Home

google_auth_proxy

Puppet module to deploy a Google OAuth2 proxy using nginx and google_auth_proxy from bitly

10,662 downloads

9,539 latest version

4.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.5 (latest)
  • 0.1.4
  • 0.1.3
  • 0.1.2
  • 0.1.1
  • 0.1.0
released Feb 12th 2015
This version is compatible with:

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'yo61-google_auth_proxy', '0.1.5'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add yo61-google_auth_proxy
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install yo61-google_auth_proxy --version 0.1.5

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

yo61/google_auth_proxy — version 0.1.5 Feb 12th 2015

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with google_auth_proxy
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

The google_auth_proxy module allows you to set up and manage instances of the bitly Google OAuth2 proxy with minimal effort.

Module Description

google_auth_proxy is an HTTP Reverse Proxy that provides authentication using Google’s OAuth2 API with flexibility to authorize individual Google Accounts (by email address) or a whole Google apps domain. Read more about it in this blog post and see detailed instructions on github.

This module makes it easy to deploy a proxy for an existing application.

This module was developed for, and only tested on, CentOS 7.

It was also developed for use in an AWS environment with SSL termination at the ELB, ie. there is no provision to set up https proxies. I may add this at some stage in the future. PRs welcome. :)

Architecture

Taken from the google_auth_proxy README:

    _______       ___________________       __________
    |Nginx| ----> |google_auth_proxy| ----> |upstream| 
    -------       -------------------       ----------
                          ||
                          \/
                  [google oauth2 api]

Setup

What google_auth_proxy affects

  • google_auth_proxy itself is a single, self-contained executable
  • nginx is installed and configured as a front end to the proxy
  • a service instance is created to run the proxy

Setup Requirements OPTIONAL

Make a note of the IP/hostname and port on which your application is running. Typically the proxy and application would run on the same node with the application bound to a high-numbered port and listening on localhost.

Follow the instructions in the README to set up your OAuth configuration with Google and make a note of your Client ID and Client Secret.

The google_auth_proxy RPM should be made available in a yum repo that has been configured on the target system. Both source and binary RPMs are available in my yum repo.

Sample puppet code to configure the repo:

yumrepo{'yo61':
  ensure   => present,
  name     => 'yo61',
  baseurl  => "http://repo.yo61.net/el/${::operatingsystemmajrelease}/${::architecture}/RPMS",
  enabled  => 1,
  gpgcheck => 1,
  gpgkey   => 'http://repo.yo61.net/RPM-GPG-KEY-YO61',
}

Beginning with google_auth_proxy

Creating the proxy is as simple as this:

  $redirect_url = 'https://your_app.example.com/oauth2/callback',
  $auth_domains = ['your_domain.com']
  $upstreams = ['http://localhost:8080']
  $cookie_secret = <seed string for secure cookies>
  $client_id = <your client id>
  $client_secret = <your client secret>

  google_auth_proxy{'puppetboard_stage':
    redirect_url        => $redirect_url,
    google_apps_domains => $auth_domains,
    upstreams           => $upstreams,
    cookie_secret       => $cookie_secret,
    client_id           => $client_id,
    client_secret       => $client_secret,
  }

This will create a nginx vhost listening on port 80 on all IP addresses with the proxy app listening on port 4180 on localhost.

Usage

###Classes and Defined Types

####Defined Type: google_auth_proxy This is the only public component of the module. It installs and sets up the google_auth_proxy service.

Parameters within google_auth_proxy: #####ensure Specify whether the proxy is present or absent. Defaults to 'present'. Valid values are 'present' and 'absent'. #####redirect_url The OAuth Redirect URL. eg. https://your_app.example.com/oauth2/callback #####google_apps_domains Authenticate against the given Google apps domain. May contain multiple values, ie. can be a string or an array of strings. #####upstreams The http url(s) of the upstream endpoint. May contain multiple values, ie. can be a string or an array of strings. If multiple, routing is based on path (what does this even mean?) #####cookie_secret The seed string for secure cookies. #####client_id The Google OAuth Client ID: ie: "123456.apps.googleusercontent.com" #####client_secret The OAuth Client Secret #####proxy_host The IP on which the nginx instance should listen. Default: '*' (all IPs) #####proxy_port The port on which the nginx instance should listen. Default: '80'. #####proxy_connect_timeout Timeout for the connection to the upstream server, ie. nginx -> google_auth_proxy Default: 1 #####proxy_read_timeout Timeout for the response of the upstream server, ie. the google_auth_proxy Default: 30 #####gap_host Hostname or IP on which the google_auth_proxy daemon should listen. Default: 'localhost' #####gap_port Port on which he google_auth_proxy daemon should listen. Default: '4180' #####gap_upstream_fail_timeout See: http://wiki.nginx.org/HttpUpstreamModule#server Default: '10s' #####user The user as which the google_auth_proxy daemon will run. Default: 'root' #####group The group as which the google_auth_proxy daemon will run. Default: 'root'

Reference

To be written

Limitations

This module was written and tested on CentOS 7. It could be modified to work on other platforms but I have no need to do so at the present time. PRs (with tests) welcome :)

Development

Feel free to improve anything.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request