Puppet oauth2_proxy Module

Table of Contents

1. Overview
2. Description
3. Major API Changes
4. Usage
   • Examples
   • Classes
     • oauth2_proxy
   • Defines
     • oauth2_proxy::instance
5. Limitations
   • Tested Platforms
   • Puppet Version Compatibility
   • systemd
6. Versioning
7. Support
8. Contributing
9. See Also

Overview

manages the oauth2_proxy reverse proxy with oauth authentication

Description

This module installs and configures the oauth2_proxy package and provides a minimal systemd service unit.

Log messages [from stdout & stderr] are sent to the systemd journal. This may be undesirable with moderate to high volumes of traffic.

Major API Changes

• Version 1.x

Represents a significant and backwards incompatible API change.

Previously, the only public interface was through the oauth2_proxy classs and a single proxy instance was managed. As of 1.x, multiple proxy instances are supported via the oauth2_proxy::instance defined type.

Usage

Examples

include ::oauth2_proxy

::oauth2_proxy::instance { 'proxy1':
  config => {
    http_address      => '127.0.0.1:4180',
    client_id         => '1234',
    client_secret     => 'abcd',
    github_org        => 'foo',
    upstreams         => [ 'http://127.0.0.1:3000' ],
    cookie_secret     => '1234',
    pass_access_token => false,
    pass_host_header  => true,
    provider          => 'github',
    redirect_url      => 'https://foo.example.org/oauth2/callback',
    email_domains     => [ '*' ],
  }
}

class { '::oauth2_proxy':
  source   => 'https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.3.0/oauth2_proxy-7.3.0.linux-amd64.go1.4.2.tar.gz',
  checksum => '950e08d52c04104f0539e6945fc42052b30c8d1b',
}

::oauth2_proxy::instance { 'proxy1':
  config => {
    http_address      => '127.0.0.1:4180',
    client_id         => '1234',
    client_secret     => 'abcd',
    github_org        => 'foo',
    upstreams         => [ 'http://127.0.0.1:3000' ],
    cookie_secret     => '1234',
    pass_access_token => false,
    pass_host_header  => true,
    provider          => 'github',
    redirect_url      => 'https://foo.example.org/oauth2/callback',
    email_domains     => [ '*' ],
  }
}

Classes

oauth2_proxy

# defaults
class { '::oauth2_proxy':
  user         => 'oauth2',
  manage_user  => true,
  group        => 'oauth2',
  manage_group => true,
  install_root => '/opt/oauth2_proxy',
  source       => 'https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.3.0/oauth2-proxy-v7.3.0.linux-amd64.tar.gz',
  checksum     => '625ce0f0b23bc5791d1b9a64d2d9a7349a4f94c12f3eea8e8f05055067e6c55a',
}

user

String defaults to: oauth2

The name/uid of the system role account to execute the proxy process under and will have ownership of files.

manage_user

Boolean defaults to: true

Whether or not this module should manage the system role account to execute the proxy process under.

group

String defaults to: oauth2

The group/gid of the system role account and group ownership of files.

manage_group

Boolean defaults to: true

Weather or not this module should manage the group of the system role account.

install_root

String defaults to: /opt/oauth2_proxy

The dirname under which to install the proxy files.

source

String defaults to: <a long url>

The URL from which to download the oauth2_proxy binary. The file is assumed to be in tar.gz format.

checksum

String defaults to: <a sha1 checksum>

The sha1 format checksum of the source file.

Defines

oauth2_proxy::instance

# defaults
::oauth2_proxy::instance { 'proxy1':
  config         => { ... }, # mandatory
  manage_service => true,
}

config

Hash mandatory

A list of key/value pairs to be serialized into a configuration file @ /etc/oauth2_proxy/< title >.conf. No validation of this hash is done beyond checking the parameter type.

The configuration file parameters are similar to the CLI options but have some variance in terms of name and format. The oauth2_proxy.cfg.example provided is the best [only] documentation available beyond the source code itself.

Please note that oauth2_proxy does have several mandatory parameters and will fail to start-up if they are not present.

manage_service

Boolean defaults to: true

Whether or not to manage a service resource for the proxy instance.

Limitations

Tested Platforms

• el7
• ubuntu 14.04

Puppet Version Compatibility

systemd

This module should in theory be able to function on any x86_64 Linux distribution that uses systemd for service management. However, since this has not been tested the module is limited to el7/x86_64.

Versioning

This module is versioned according to the Semantic Versioning 2.0.0 specification.

Support

Please log tickets and issues at github

Contributing

1. Fork it on github
2. Make a local clone of your fork
3. Create a topic branch. Eg, feature/mousetrap
4. Make/commit changes
   • Commit messages should be in imperative tense
   • Check that linter warnings or errors are not introduced - bundle exec rake lint
   • Check that Rspec-puppet unit tests are not broken and coverage is added for new features - bundle exec rake spec
   • Documentation of API/features is updated as appropriate in the README
   • If present, beaker acceptance tests should be run and potentially updated - bundle exec rake beaker
5. When the feature is complete, rebase / squash the branch history as necessary to remove "fix typo", "oops", "whitespace" and other trivial commits
6. Push the topic branch to github
7. Open a Pull Request (PR) from the topic branch onto parent repo's master branch

See Also

• oauth2_proxy

Fork from https://github.com/jhoblitt/puppet-oauth2_proxy.git

Includes a number of changes for Puppet6+ syntax from https://github.com/Fabian1976/puppet-oauth2_proxy/

Reference

Table of Contents

Classes

• oauth2_proxy: Class to install and configure an oauth2_proxy
• oauth2_proxy::install: Class to install and configure an oauth2_proxy This class should be considered private.
• oauth2_proxy::params: Class with default parameters This class should be considered private.

Defined types

• oauth2_proxy::instance: Defined type to configure a oauth2_proxy instance

Classes

oauth2_proxy

Class to install and configure an oauth2_proxy

Parameters

The following parameters are available in the oauth2_proxy class:

• manage_user
• manage_group
• manage_service
• user
• group
• install_root
• version
• source_base_url
• tarball_name
• provider
• shell
• systemd_path
• instances

manage_user

Data type: Boolean

Should the module manage the user creation Default: true

Default value: $oauth2_proxy::params::manage_user

manage_group

Data type: Boolean

Should the module manage the group creation Default: true

Default value: $oauth2_proxy::params::manage_group

manage_service

Data type: Boolean

Should the module manage the systemd service Default: true

Default value: $oauth2_proxy::params::manage_service

user

Data type: String

The useraccount to create the files needed for the proxy Default: 'oauth2'

Default value: $oauth2_proxy::params::user

group

Data type: String

The users group accountname Default: same as user

Default value: $oauth2_proxy::params::group

install_root

Data type: Stdlib::Unixpath

The path where the proxy will be installed Default: '/opt/oauth2_proxy'

Default value: $oauth2_proxy::params::install_root

version

Data type: String

The version of oauth2_proxy to install Default: '6.1.1'

Default value: $oauth2_proxy::params::version

source_base_url

Data type: Stdlib::HTTPUrl

The base URL where the software tarball can be found Default: "https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v${version}"

Default value: $oauth2_proxy::params::source_base_url

tarball_name

Data type: String

The name of the tarball Default: "oauth2-proxy-v${version}.linux-amd64.tar.gz"

Default value: $oauth2_proxy::params::tarball_name

provider

Data type: String

Provider to use Default: 'systemd'

Default value: $oauth2_proxy::params::provider

shell

Data type: Stdlib::Unixpath

Shell to use for oauth2 user Default: '/sbin/nologin'

Default value: $oauth2_proxy::params::shell

systemd_path

Data type: Stdlib::Unixpath

Path of systemd Default: '/usr/lib/systemd/system'

Default value: $oauth2_proxy::params::systemd_path

instances

Data type: Optional[Hash]

A Hash of oauth2_proxy instances and its configuration Default: '/usr/lib/systemd/system'

Default value: undef

oauth2_proxy::install

Class to install and configure an oauth2_proxy This class should be considered private.

oauth2_proxy::params

Class with default parameters This class should be considered private.

Defined types

oauth2_proxy::instance

Defined type to configure a oauth2_proxy instance

Parameters

The following parameters are available in the oauth2_proxy::instance defined type:

• config

config

Data type: Hash

Hash with configuration parameter for oauth2_proxy Details can be founce here https://oauth2-proxy.github.io/oauth2-proxy/docs/6.1.x/configuration/overview

Changelog

All notable changes to this project will be documented in this file.

Release 1.0.1

Minor bugfix release to have parameter 'version' before it's used in 'source_base_url'.

Release 1.0.0

Main line version of upstream Oauth Proxy upgraded to v7.3.0 Removed params class in favour of proper params in init.pp, meaning better upgradability and configurability Tested as working with recent Ubuntu LTS versions 20.04 and 22.04

Features

Bugfixes

Known Issues