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://developer.hashicorp.com/vault/docs/auth/jwt
- 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.hcl ...
...

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

$ vault plugin register \
        -sha256=<SHA256 Hex value of the plugin binary> \
        -command="vault-plugin-auth-jwt" \
        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'

Additionally, there are some BATs tests in the tests dir.

Prerequisites

• Install Bats Core
• Docker or a vault binary in the tests directory.

Setup

• Configure an OIDC provider
• Save and export the following values to your shell:
  • CLIENT_ID
  • CLIENT_SECRET
  • ISSUER
• Export VAULT_IMAGE to test the image of your choice or place a vault binary in the tests directory.
• Export VAULT_LICENSE. This test will only work for enterprise images.

Logs

Vault logs will be written to VAULT_OUTFILE. BATs test logs will be written to SETUP_TEARDOWN_OUTFILE.

Run Bats tests

# export env vars
export CLIENT_ID="12345"
export CLIENT_SECRET="6789"
export ISSUER="my-issuer-url"
export VAULT_LICENSE="abcde"

# run tests
cd tests/
./test.bats

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 IBMISAMProvider
  • func (a *IBMISAMProvider) FetchGroups(_ context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, ...) (interface{}, error)
  • func (a *IBMISAMProvider) Initialize(_ context.Context, _ *jwtConfig) error
  • func (a *IBMISAMProvider) SensitiveKeys() []string
• type JWKSPair
  • func Initialize(jp map[string]interface{}) (*JWKSPair, error)
  • func NewJWKSPairsConfig(jc *jwtConfig) ([]*JWKSPair, error)
• type SecureAuthProvider
  • func (a *SecureAuthProvider) FetchGroups(_ context.Context, b *jwtAuthBackend, allClaims map[string]interface{}, ...) (interface{}, error)
  • func (a *SecureAuthProvider) Initialize(_ context.Context, _ *jwtConfig) error
  • func (a *SecureAuthProvider) SensitiveKeys() []string
• type UserInfoFetcher

Constants

const (
	FieldCallbackHost   = "callbackhost"
	FieldCallbackMethod = "callbackmethod"
	FieldListenAddress  = "listenaddress"
	FieldPort           = "port"
	FieldCallbackPort   = "callbackport"
	FieldSkipBrowser    = "skip_browser"
	FieldAbortOnError   = "abort_on_error"
)

const (
	StaticKeys = iota
	JWKS
	MultiJWKS
	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. Optional.
	// If left unspecified, Application Default Credentials will be used.
	ServiceAccount string `mapstructure:"gsuite_service_account"`

	// Email address of a Google Workspace user that has access to read users
	// and groups for the organization in the Google Workspace Directory API.
	// Required if accessing the Google Workspace Directory API through
	// domain-wide delegation of authority.
	AdminImpersonateEmail string `mapstructure:"gsuite_admin_impersonate"`

	// Service account email that has been granted domain-wide delegation of
	// authority in Google Workspace. Required if accessing the Google
	// Workspace Directory API through domain-wide delegation of authority,
	// without using a service account key. The service account vault is
	// running under must be granted the `iam.serviceAccounts.signJwt`
	// permission on this service account. If AdminImpersonateEmail is
	// specifed, that Workspace user will be impersonated.
	ImpersonatePrincipal string `mapstructure:"impersonate_principal"`

	// If set to true, groups will be fetched from the Google Workspace
	// Directory API.
	FetchGroups bool `mapstructure:"fetch_groups"`

	// If set to true, user info will be fetched from the Google Workspace
	// Directory API 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"`

	// The domain to get groups from. Set this if your workspace is
	// configured with more than one domain.
	Domain string `mapstructure:"domain"`
}

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 IBMISAMProvider

type IBMISAMProvider struct{}

IBMISAMProvider is used for IBMISAM-specific configuration

func (*IBMISAMProvider) FetchGroups

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

FetchGroups - custom groups fetching for ibmisam - satisfying GroupsFetcher interface IBMISAM by default will return groups not as a json list but as a list of space seperated strings We need to convert this to a json list

func (*IBMISAMProvider) Initialize

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

Initialize anything in the IBMISAMProvider struct - satisfying the CustomProvider interface

func (*IBMISAMProvider) SensitiveKeys

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

SensitiveKeys - satisfying the CustomProvider interface

type JWKSPair

type JWKSPair struct {
	JWKSUrl   string `mapstructure:"jwks_url"`
	JWKSCAPEM string `mapstructure:"jwks_ca_pem"`
}

func Initialize

func Initialize(jp map[string]interface{}) (*JWKSPair, error)

func NewJWKSPairsConfig

func NewJWKSPairsConfig(jc *jwtConfig) ([]*JWKSPair, error)

type SecureAuthProvider

type SecureAuthProvider struct{}

SecureAuthProvider is used for SecureAuth-specific configuration

func (*SecureAuthProvider) FetchGroups

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

FetchGroups - custom groups fetching for secureauth - satisfying GroupsFetcher interface SecureAuth by default will return groups not as a json list but as a list of comma seperated strings We need to convert this to a json list

func (*SecureAuthProvider) Initialize

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

Initialize anything in the SecureAuthProvider struct - satisfying the CustomProvider interface

func (*SecureAuthProvider) SensitiveKeys

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

SensitiveKeys - satisfying the CustomProvider interface

type UserInfoFetcher

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

UserInfoFetcher - Optional support for custom user info handling