authorizerd

README

Athenz authorizer

• Athenz authorizer
  • What is Athenz authorizer
  • Usage
  • How it works
    • Athenz public key daemon
    • Athenz policy daemon
  • Configuration
  • License
  • Contributor License Agreement
  • About releases
  • Authors

What is Athenz authorizer

Athenz authorizer is a library to cache the policies of Athenz to authorizer authentication and authorization check of user request.

Usage

To initialize authorizer.

// Initialize authorizerd
daemon, err := authorizerd.New(
    authorizerd.WithAthenzURL("www.athenz.io"), // set athenz URL
    authorizerd.WithAthenzDomains("domain1", "domain2" ... "domain N"), // set athenz domains
    authorizerd.WithPubkeyRefreshDuration(time.Hour * 24), // set athenz public key refresh duration
    authorizerd.WithPolicyRefreshDuration(time.Hour), // set policy refresh duration
)
if err != nil {
   // cannot initialize authorizer daemon
}

// Start authorizer daemon
ctx := context.Background() // user can control authorizer daemon lifetime using this context
errs := daemon.Start(ctx)
go func() {
    err := <-errs
    // user should handle errors return from the daemon
}()

// Verify role token
if err := daemon.VerifyRoleToken(ctx, roleTok, act, res); err != nil {
    // token not authorized
}

How it works

To do the authentication and authorization check, the user needs to specify which domain data to be cache. The authorizer will periodically refresh the policies and Athenz public key data to verify and decode the domain data. The verified domain data will cache into the memory, and use for authentication and authorization check.

The authorizer contains two sub-module, Athenz public key daemon (pubkeyd) and Athenz policy daemon (policyd).

Athenz public key daemon

Athenz public key daemon (pubkeyd) is responsible for periodically update the Athenz public key data from Athenz server to verify the policy data received from Athenz policy daemon and verify the role token.

Athenz policy daemon

Athenz policy daemon (policyd) is responsible for periodically update the policy data of specified Athenz domain from Athenz server. The received policy data will be verified using the public key got from pubkeyd, and cache into memory. Whenever user requesting for the access check, the verification check will be used instead of asking Athenz server every time.

Configuration

The authorizer uses functional options pattern to initialize the instance. All the options are defined here.

Option name	Description	Default Value	Required	Example
AthenzURL	The Athenz server URL	"athenz.io/zts/v1"	No
AthenzDomains	Athenz domain name of Policy cache		Yes	"domName1", "domName2"
Transport	The HTTP transport for getting policy data and Athenz public key data	nil	No
CacheExp	The TTL of the success cache	1 Minute	No
PubkeyRefreshDuration	The refresh duration to update the Athenz public key data	24 Hours	No
PubkeySysAuthDomain	System authority domain name to retrieve Athenz public key data	sys.auth	No
PubkeyEtagExpTime	ETag cache TTL of Athenz public key data	168 Hours (1 Week)	No
PubkeyEtagFlushDur	ETag cache purge duration	84 Hours	No
PolicyRefreshDuration	The refresh duration to update Athenz policy data	30 Minutes	No
PolicyExpireMargin	The expire margin to update the policy data. It forces update the policy data before the policy expiration margin.	3 Hours	No
AccessTokenParam	Use access token verification. See here for details of the options that can be specified.	enable true verifyCertThumbprint true verifyClientID false authorizedClientIDs nil certBackdateDur 1 hours certOffsetDur 1 hours	No
EnableRoleToken	Use role token verification	true	No	true
EnableRoleCert	Use role cert verification	true	No	true

License

Copyright (C) 2018 Yahoo Japan Corporation Athenz team.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Contributor License Agreement

This project requires contributors to agree to a Contributor License Agreement (CLA).

Note that only for contributions to the athenz-authorizer repository on the GitHub, the contributors of them shall be deemed to have agreed to the CLA without individual written agreements.

About releases

• Releases
  • 

Authors

• kpango
• kevindiu
• TakuyaMatsu
• tatyano
• WindzCUHK

Documentation

Overview

Package authorizerd represents the policy updater daemon.

Index

• Variables
• type AccessTokenParam
  • func NewAccessTokenParam(enable bool, verifyCertThumbprint bool, certBackdateDur, certOffsetDur string, ...) AccessTokenParam
• type Authorizerd
  • func New(opts ...Option) (Authorizerd, error)
• type Option
  • func WithAccessTokenParam(accessTokenParam AccessTokenParam) Option
  • func WithAthenzDomains(domains ...string) Option
  • func WithAthenzURL(url string) Option
  • func WithCacheExp(exp time.Duration) Option
  • func WithDisableJwkd() Option
  • func WithDisablePolicyd() Option
  • func WithDisablePubkeyd() Option
  • func WithDisableRoleCert() Option
  • func WithDisableRoleToken() Option
  • func WithEnableJwkd() Option
  • func WithEnablePolicyd() Option
  • func WithEnablePubkeyd() Option
  • func WithEnableRoleCert() Option
  • func WithEnableRoleToken() Option
  • func WithJwkErrRetryInterval(i string) Option
  • func WithJwkRefreshDuration(t string) Option
  • func WithPolicyErrRetryInterval(i string) Option
  • func WithPolicyExpireMargin(t string) Option
  • func WithPolicyRefreshDuration(t string) Option
  • func WithPolicyRetryAttempts(c int) Option
  • func WithPubkeyErrRetryInterval(i string) Option
  • func WithPubkeyEtagExpTime(t string) Option
  • func WithPubkeyEtagFlushDuration(t string) Option
  • func WithPubkeyRefreshDuration(t string) Option
  • func WithPubkeySysAuthDomain(domain string) Option
  • func WithRoleAuthHeader(h string) Option
  • func WithRoleCertURIPrefix(t string) Option
  • func WithTransport(t *http.Transport) Option

Variables

var (
	// ErrRoleTokenInvalid "Access denied due to invalid RoleToken"
	ErrRoleTokenInvalid = role.ErrRoleTokenInvalid
	// ErrRoleTokenExpired "Access denied due to expired RoleToken"
	ErrRoleTokenExpired = role.ErrRoleTokenExpired

	// ErrDomainMismatch "Access denied due to domain mismatch between Resource and RoleToken"
	ErrDomainMismatch = policy.ErrDomainMismatch
	// ErrDomainNotFound "Access denied due to domain not found in library cache"
	ErrDomainNotFound = policy.ErrDomainNotFound
	// ErrDomainExpired "Access denied due to expired domain policy file"
	ErrDomainExpired = policy.ErrDomainExpired
	// ErrNoMatch "Access denied due to no match to any of the assertions defined in domain policy file"
	ErrNoMatch = policy.ErrNoMatch
	// ErrInvalidPolicyResource "Access denied due to invalid/empty policy resources"
	ErrInvalidPolicyResource = policy.ErrInvalidPolicyResource
	// ErrDenyByPolicy "Access Check was explicitly denied"
	ErrDenyByPolicy = policy.ErrDenyByPolicy
	// ErrFetchPolicy "Error fetching athenz policy"
	ErrFetchPolicy = policy.ErrFetchPolicy

	// ErrInvalidParameters "Access denied due to invalid/empty action/resource values"
	ErrInvalidParameters = errors.New("Access denied due to invalid/empty action/resource values")

	// ErrInvalidCredentials "Access denied due to invalid credentials"
	ErrInvalidCredentials = errors.New("Access denied due to invalid credentials")
)

Types

type AccessTokenParam

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

func NewAccessTokenParam

func NewAccessTokenParam(enable bool, verifyCertThumbprint bool, certBackdateDur, certOffsetDur string, verifyClientID bool, authorizedClientIDs map[string][]string) AccessTokenParam

NewAccessTokenParam returns a new access token parameter

type Authorizerd

type Authorizerd interface {
	Init(ctx context.Context) error
	Start(ctx context.Context) <-chan error
	Verify(r *http.Request, act, res string) error
	VerifyAccessToken(ctx context.Context, tok, act, res string, cert *x509.Certificate) error
	VerifyRoleToken(ctx context.Context, tok, act, res string) error
	VerifyRoleJWT(ctx context.Context, tok, act, res string) error
	VerifyRoleCert(ctx context.Context, peerCerts []*x509.Certificate, act, res string) error
	GetPolicyCache(ctx context.Context) map[string]interface{}
}

Authorizerd represents a daemon for user to verify the role token

func New

func New(opts ...Option) (Authorizerd, error)

New return Authorizerd This function will initialize the Authorizerd object with the options

type Option

type Option func(*authorizer) error

Option represents a functional option

func WithAccessTokenParam

func WithAccessTokenParam(accessTokenParam AccessTokenParam) Option

WithAccessTokenParam returns a functional option that new access token parameter

func WithAthenzDomains

func WithAthenzDomains(domains ...string) Option

WithAthenzDomains returns an AthenzDomains functional option

func WithAthenzURL

func WithAthenzURL(url string) Option

WithAthenzURL returns an AthenzURL functional option

func WithCacheExp

func WithCacheExp(exp time.Duration) Option

WithCacheExp returns a CacheExp functional option

func WithDisableJwkd

func WithDisableJwkd() Option

WithDisableJwkd returns a DisableJwkd functional option

func WithDisablePolicyd

func WithDisablePolicyd() Option

WithDisablePolicyd returns a DisablePolicyd functional option

func WithDisablePubkeyd

func WithDisablePubkeyd() Option

WithDisablePubkeyd returns a DisablePubkey functional option

func WithDisableRoleCert

func WithDisableRoleCert() Option

WithDisableRoleCert returns a disable rolecert functional option

func WithDisableRoleToken

func WithDisableRoleToken() Option

WithDisableRoleToken returns a disable roletoken functional option

func WithEnableJwkd

func WithEnableJwkd() Option

WithEnableJwkd returns an EnableJwkd functional option

func WithEnablePolicyd

func WithEnablePolicyd() Option

WithEnablePolicyd returns an EnablePolicyd functional option

func WithEnablePubkeyd

func WithEnablePubkeyd() Option

WithEnablePubkeyd returns an EnablePubkey functional option

func WithEnableRoleCert

func WithEnableRoleCert() Option

WithEnableRoleCert returns a enable rolecert functional option

func WithEnableRoleToken

func WithEnableRoleToken() Option

WithEnableRoleToken returns a enable roletoken functional option

func WithJwkErrRetryInterval

func WithJwkErrRetryInterval(i string) Option

WithJwkErrRetryInterval returns a JwkErrRetryInterval functional option

func WithJwkRefreshDuration

func WithJwkRefreshDuration(t string) Option

WithJwkRefreshDuration returns a JwkRefreshDuration functional option

func WithPolicyErrRetryInterval

func WithPolicyErrRetryInterval(i string) Option

WithPolicyErrRetryInterval returns a PolicyErrRetryInterval functional option

func WithPolicyExpireMargin

func WithPolicyExpireMargin(t string) Option

WithPolicyExpireMargin returns a PolicyExpireMargin functional option

func WithPolicyRefreshDuration

func WithPolicyRefreshDuration(t string) Option

WithPolicyRefreshDuration returns a PolicyRefreshDuration functional option

func WithPolicyRetryAttempts

func WithPolicyRetryAttempts(c int) Option

WithPolicyRetryAttempts returns a PolicyRetryAttempts functional option

func WithPubkeyErrRetryInterval

func WithPubkeyErrRetryInterval(i string) Option

WithPubkeyErrRetryInterval returns a PubkeyErrRetryInterval functional option

func WithPubkeyEtagExpTime

func WithPubkeyEtagExpTime(t string) Option

WithPubkeyEtagExpTime returns a PubkeyEtagExpTime functional option

func WithPubkeyEtagFlushDuration

func WithPubkeyEtagFlushDuration(t string) Option

WithPubkeyEtagFlushDuration returns a PubkeyEtagFlushDur functional option

func WithPubkeyRefreshDuration

func WithPubkeyRefreshDuration(t string) Option

WithPubkeyRefreshDuration returns a PubkeyRefreshDuration functional option

func WithPubkeySysAuthDomain

func WithPubkeySysAuthDomain(domain string) Option

WithPubkeySysAuthDomain returns a PubkeySysAuthDomain functional option

func WithRoleAuthHeader

func WithRoleAuthHeader(h string) Option

WithRoleAuthHeader returns a RoleAuthHeader functional option

func WithRoleCertURIPrefix

func WithRoleCertURIPrefix(t string) Option

WithRoleCertURIPrefix returns a RoleCertURIPrefix functional option

func WithTransport

func WithTransport(t *http.Transport) Option

WithTransport returns a Transport functional option