jwtauth

README

Vault Plugin: JWT Auth Backend

This is a standalone backend plugin for use with Hashicorp Vault. This plugin allows for JWTs (including OIDC tokens) to authenticate with Vault.

Please note: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault, please responsibly disclose by contacting us at security@hashicorp.com.

Quick Links

- Vault Website: https://www.vaultproject.io
- JWT Auth Docs: https://www.vaultproject.io/docs/auth/jwt.html
- Main Project Github: https://www.github.com/hashicorp/vault

Getting Started

This is a Vault plugin and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works.

Otherwise, first read this guide on how to get started with Vault.

To learn specifically about how plugins work, see documentation on Vault plugins.

Usage

Please see documentation for the plugin on the Vault website.

This plugin is currently built into Vault and by default is accessed at auth/jwt. To enable this in a running Vault server:

$ vault auth enable jwt 
Successfully enabled 'jwt' at 'jwt'!

To see all the supported paths, see the JWT auth backend docs.

Developing

If you wish to work on this plugin, you'll first need Go installed on your machine.

For local dev first make sure Go is properly installed, including setting up a GOPATH. Next, clone this repository into $GOPATH/src/github.com/hashicorp/vault-plugin-auth-jwt. You can then download any required build tools by bootstrapping your environment:

$ make bootstrap

To compile a development version of this plugin, run make or make dev. This will put the plugin binary in the bin and $GOPATH/bin folders. dev mode will only generate the binary for your platform and is faster:

$ make
$ make dev

Put the plugin binary into a location of your choice. This directory will be specified as the plugin_directory in the Vault config used to start the server.

...
plugin_directory = "path/to/plugin/directory"
...

Start a Vault server with this config file:

$ vault server -config=path/to/config.json ...
...

Once the server is started, register the plugin in the Vault server's plugin catalog:

$ vault write sys/plugins/catalog/jwt \
        sha_256=<expected SHA256 Hex value of the plugin binary> \
        command="vault-plugin-auth-jwt"
...
Success! Data written to: sys/plugins/catalog/jwt

Note you should generate a new sha256 checksum if you have made changes to the plugin. Example using openssl:

openssl dgst -sha256 $GOPATH/vault-plugin-auth-jwt
...
SHA256(.../go/bin/vault-plugin-auth-jwt)= 896c13c0f5305daed381952a128322e02bc28a57d0c862a78cbc2ea66e8c6fa1

Enable the auth plugin backend using the JWT auth plugin:

$ vault auth enable -plugin-name='jwt' plugin
...

Successfully enabled 'plugin' at 'jwt'!

Provider-specific handling

Provider-specific handling can be added by writing an object that conforms to one or more interfaces in provider_config.go. Some interfaces will be required, like CustomProvider, and others will be invoked if present during the login process (e.g. GroupsFetcher). The interfaces themselves will be small (usually a single method) as it is expected that the parts of the login that need specialization will be different per provider. This pattern allows us to start with a minimal set and add interfaces as necessary.

If a custom provider is configured on the backend object and satisfies a given interface, the interface will be used during the relevant part of the login flow. e.g. after an ID token has been received, the custom provider's UserInfoFetcher interface will be used, if present, to fetch and merge additional identity data.

The custom handlers will be standalone objects defined in their own file (one per provider). They'll be part of the main jwtauth package to avoid potential circular import issues.

Tests

If you are developing this plugin and want to verify it is still functioning (and you haven't broken anything else), we recommend running the tests.

To run the tests, invoke make test:

$ make test

You can also specify a TESTARGS variable to filter tests like so:

$ make test TESTARGS='--run=TestConfig'

Documentation

Overview

A minimal UI for simple testing via a UI without Vault

Index

• Constants
• func Factory(ctx context.Context, c *logical.BackendConfig) (logical.Backend, error)
• func ProviderMap() map[string]CustomProvider
• type AzureProvider
  • func (a *AzureProvider) FetchGroups(_ context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, ...) (interface{}, error)
  • func (a *AzureProvider) Initialize(_ context.Context, _ *jwtConfig) error
  • func (a *AzureProvider) SensitiveKeys() []string
• type CLIHandler
  • func (h *CLIHandler) Auth(c *api.Client, m map[string]string) (*api.Secret, error)
  • func (h *CLIHandler) Help() string
• type CustomProvider
  • func NewProviderConfig(ctx context.Context, jc *jwtConfig, providerMap map[string]CustomProvider) (CustomProvider, error)
• type GSuiteProvider
  • func (g *GSuiteProvider) FetchGroups(ctx context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, ...) (interface{}, error)
  • func (g *GSuiteProvider) FetchUserInfo(ctx context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, ...) error
  • func (g *GSuiteProvider) Initialize(ctx context.Context, jc *jwtConfig) error
  • func (g *GSuiteProvider) SensitiveKeys() []string
• type GSuiteProviderConfig
• type GroupsFetcher
• type UserInfoFetcher

Constants

const (
	StaticKeys = iota
	JWKS
	OIDCDiscovery
	OIDCFlow
)

Functions

func Factory

func Factory(ctx context.Context, c *logical.BackendConfig) (logical.Backend, error)

Factory is used by framework

func ProviderMap

func ProviderMap() map[string]CustomProvider

ProviderMap returns a map of provider names to custom types

Types

type AzureProvider

type AzureProvider struct {
	// contains filtered or unexported fields
}

AzureProvider is used for Azure-specific configuration

func (*AzureProvider) FetchGroups

func (a *AzureProvider) FetchGroups(_ context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, role *jwtRole, tokenSource oauth2.TokenSource) (interface{}, error)

FetchGroups - custom groups fetching for azure - satisfying GroupsFetcher interface

func (*AzureProvider) Initialize

func (a *AzureProvider) Initialize(_ context.Context, _ *jwtConfig) error

Initialize anything in the AzureProvider struct - satisfying the CustomProvider interface

func (*AzureProvider) SensitiveKeys

func (a *AzureProvider) SensitiveKeys() []string

SensitiveKeys - satisfying the CustomProvider interface

type CLIHandler

type CLIHandler struct{}

func (*CLIHandler) Auth

func (h *CLIHandler) Auth(c *api.Client, m map[string]string) (*api.Secret, error)

func (*CLIHandler) Help

func (h *CLIHandler) Help() string

Help method for OIDC cli

type CustomProvider

type CustomProvider interface {
	// Initialize should validate jwtConfig.ProviderConfig, set internal values
	// and run any initialization necessary for subsequent calls to interface
	// functions the provider implements
	Initialize(context.Context, *jwtConfig) error

	// SensitiveKeys returns any fields in a provider's jwtConfig.ProviderConfig
	// that should be masked or omitted when output
	SensitiveKeys() []string
}

CustomProvider - Any custom provider must implement this interface

func NewProviderConfig

func NewProviderConfig(ctx context.Context, jc *jwtConfig, providerMap map[string]CustomProvider) (CustomProvider, error)

NewProviderConfig - returns appropriate provider struct if provider_config is specified in jwtConfig. The provider map is provider name -to- instance of a CustomProvider.

type GSuiteProvider

type GSuiteProvider struct {
	// contains filtered or unexported fields
}

GSuiteProvider provides G Suite-specific configuration and behavior.

func (*GSuiteProvider) FetchGroups

func (g *GSuiteProvider) FetchGroups(ctx context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, role *jwtRole, _ oauth2.TokenSource) (interface{}, error)

FetchGroups fetches and returns groups from G Suite.

func (*GSuiteProvider) FetchUserInfo

func (g *GSuiteProvider) FetchUserInfo(ctx context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, role *jwtRole) error

FetchUserInfo fetches additional user information from G Suite using custom schemas.

func (*GSuiteProvider) Initialize

func (g *GSuiteProvider) Initialize(ctx context.Context, jc *jwtConfig) error

Initialize initializes the GSuiteProvider by validating and creating configuration.

func (*GSuiteProvider) SensitiveKeys

func (g *GSuiteProvider) SensitiveKeys() []string

SensitiveKeys returns keys that should be redacted when reading the config of this provider

type GSuiteProviderConfig

type GSuiteProviderConfig struct {
	// The path to or contents of a Google service account key file. Required.
	ServiceAccount string `mapstructure:"gsuite_service_account"`

	// Email address of a G Suite admin to impersonate. Required.
	AdminImpersonateEmail string `mapstructure:"gsuite_admin_impersonate"`

	// If set to true, groups will be fetched from G Suite.
	FetchGroups bool `mapstructure:"fetch_groups"`

	// If set to true, user info will be fetched from G Suite using UserCustomSchemas.
	FetchUserInfo bool `mapstructure:"fetch_user_info"`

	// Group membership recursion max depth (0 = do not recurse).
	GroupsRecurseMaxDepth int `mapstructure:"groups_recurse_max_depth"`

	// Comma-separated list of G Suite custom schemas to fetch as claims.
	UserCustomSchemas string `mapstructure:"user_custom_schemas"`
}

GSuiteProviderConfig represents the configuration for a GSuiteProvider.

type GroupsFetcher

type GroupsFetcher interface {
	// FetchGroups queries for groups claims during login
	FetchGroups(context.Context, *jwtAuthBackend, map[string]interface{}, *jwtRole, oauth2.TokenSource) (interface{}, error)
}

GroupsFetcher - Optional support for custom groups handling

type UserInfoFetcher

type UserInfoFetcher interface {
	FetchUserInfo(context.Context, *jwtAuthBackend, map[string]interface{}, *jwtRole) error
}

UserInfoFetcher - Optional support for custom user info handling