jwtauth

package module
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2024 License: MPL-2.0 Imports: 48 Imported by: 26

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.

- 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
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

View Source 
const (
	FieldCallbackHost   = "callbackhost"
	FieldCallbackMethod = "callbackmethod"
	FieldListenAddress  = "listenaddress"
	FieldPort           = "port"
	FieldCallbackPort   = "callbackport"
	FieldSkipBrowser    = "skip_browser"
	FieldAbortOnError   = "abort_on_error"
)
View Source 
const (
	StaticKeys = iota
	JWKS
	MultiJWKS
	OIDCDiscovery
	OIDCFlow
)

Variables

This section is empty.

Functions

func Factory 

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

Factory is used by framework

func ProviderMap added in v0.7.0 

func ProviderMap() map[string]CustomProvider

ProviderMap returns a map of provider names to custom types

Types

type AzureProvider added in v0.7.0 

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

AzureProvider is used for Azure-specific configuration

func (*AzureProvider) FetchGroups added in v0.7.0 

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 added in v0.7.0 

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

Initialize anything in the AzureProvider struct - satisfying the CustomProvider interface

func (*AzureProvider) SensitiveKeys added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.1 

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

GSuiteProvider provides G Suite-specific configuration and behavior.

func (*GSuiteProvider) FetchGroups added in v0.7.1 

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 added in v0.7.1 

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 added in v0.7.1 

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

Initialize initializes the GSuiteProvider by validating and creating configuration.

func (*GSuiteProvider) SensitiveKeys added in v0.7.1 

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

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

type GSuiteProviderConfig added in v0.7.1 

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 added in v0.7.0 

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 added in v0.16.0 

type IBMISAMProvider struct{}

IBMISAMProvider is used for IBMISAM-specific configuration

func (*IBMISAMProvider) FetchGroups added in v0.16.0 

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 added in v0.16.0 

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

Initialize anything in the IBMISAMProvider struct - satisfying the CustomProvider interface

func (*IBMISAMProvider) SensitiveKeys added in v0.16.0 

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

SensitiveKeys - satisfying the CustomProvider interface

type JWKSPair added in v0.20.0 

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

func Initialize added in v0.20.0 

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

func NewJWKSPairsConfig added in v0.20.0 

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

type SecureAuthProvider added in v0.13.1 

type SecureAuthProvider struct{}

SecureAuthProvider is used for SecureAuth-specific configuration

func (*SecureAuthProvider) FetchGroups added in v0.13.1 

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 added in v0.13.1 

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

Initialize anything in the SecureAuthProvider struct - satisfying the CustomProvider interface

func (*SecureAuthProvider) SensitiveKeys added in v0.13.1 

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

SensitiveKeys - satisfying the CustomProvider interface

type UserInfoFetcher added in v0.7.1 

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

UserInfoFetcher - Optional support for custom user info handling

Source Files

View all Source files

Directories

Path Synopsis
cmd
vault-plugin-auth-jwt

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.