providerd

README

Athenz policy updater

What is Athenz policy updater

Athenz policy updater is a library to cache the policies of Athenz to provider authenication and authorization check of user request.

Usage

To initialize policy updater.

// Initialize providerd
daemon, err := providerd.New(
    providerd.AthenzURL("www.athenz.io"), // set athenz URL
    providerd.AthenzDomains("domain1", "domain2" ... "domain N"), // set athenz domains
    providerd.PubkeyRefreshDuration(time.Hour * 24), // set athenz public key refresh duration
    providerd.PolicyRefreshDuration(time.Hour), // set policy refresh duration
)
if err != nil {
   // cannot initialize policy updater daemon
}

// Start policy updater daemon
ctx := context.Background() // user can control policy updator daemon lifetime using this context
errs := daemon.StartProviderd(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 authorizated
}

How it works

To do the authentication and authorization check, the user needs to specify which domain data to be cache. The policy updater 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 policy updater contains two sub-module, Athenz pubkey daemon (pubkeyd) and Athenz policy daemon (policyd).

Athenz pubkey daemon

Athenz pubkey 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 everytime.

Configuratrion

The policy updater 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	"www.athenz.com/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
PolicyEtagExpTime	ETag cache TTL of policy data	24 Hours	No
PolicyEtagFlushDur	Policy data cache purge duration	12 Hours	No

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 garm repository on the GitHub, the contributors of them shall be deemed to have agreed to the CLA without individual written agreements.

Authors

• kpango
• kevindiu
• TakuyaMatsu
• tatyano

Documentation

Overview

Package providerd represents the policy updater daemon.

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.

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.

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.

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.

Index

• Variables
• type Option
  • func AthenzDomains(domains ...string) Option
  • func AthenzURL(url string) Option
  • func CacheExp(exp time.Duration) Option
  • func PolicyEtagExpTime(t string) Option
  • func PolicyEtagFlushDur(t string) Option
  • func PolicyExpireMargin(t string) Option
  • func PolicyRefreshDuration(t string) Option
  • func PubkeyEtagExpTime(t string) Option
  • func PubkeyEtagFlushDur(t string) Option
  • func PubkeyRefreshDuration(t string) Option
  • func PubkeySysAuthDomain(domain string) Option
  • func Transport(t *http.Transport) Option
• type Providerd
  • func New(opts ...Option) (Providerd, error)

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 invalie/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")
)

Types

type Option

type Option func(*provider) error

Option represents a functional options pattern interface

func AthenzDomains

func AthenzDomains(domains ...string) Option

AthenzDomains represents a AthenzDomains functional option

func AthenzURL

func AthenzURL(url string) Option

AthenzURL represents a AthenzURL functional option

func CacheExp

func CacheExp(exp time.Duration) Option

CacheExp represents the cache expiration time

func PolicyEtagExpTime

func PolicyEtagExpTime(t string) Option

PolicyEtagExpTime represents a PolicyEtagExpTime functional option

func PolicyEtagFlushDur

func PolicyEtagFlushDur(t string) Option

PolicyEtagFlushDur represents a PolicyEtagFlushDur functional option

func PolicyExpireMargin

func PolicyExpireMargin(t string) Option

PolicyExpireMargin represents a PolicyExpireMargin functional option

func PolicyRefreshDuration

func PolicyRefreshDuration(t string) Option

PolicyRefreshDuration represents a PolicyRefreshDuration functional option

func PubkeyEtagExpTime

func PubkeyEtagExpTime(t string) Option

PubkeyEtagExpTime represents a PubkeyEtagExpTime functional option

func PubkeyEtagFlushDur

func PubkeyEtagFlushDur(t string) Option

PubkeyEtagFlushDur represents a PubkeyEtagFlushDur functional option

func PubkeyRefreshDuration

func PubkeyRefreshDuration(t string) Option

PubkeyRefreshDuration represents a PubkeyRefreshDuration functional option

func PubkeySysAuthDomain

func PubkeySysAuthDomain(domain string) Option

PubkeySysAuthDomain represents a PubkeySysAuthDomain functional option

func Transport

func Transport(t *http.Transport) Option

Transport represents a Transport functional option

type Providerd

type Providerd interface {
	StartProviderd(context.Context) <-chan error
	VerifyRoleToken(ctx context.Context, tok, act, res string) error
}

Providerd represents a daemon for user to verify the role token

func New

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

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