go get

athenz policy management library for golang

by yahoojapan

v0.0.0-20190604014625-4708e32e38dd (see all)License:Apache-2.0
go get

Athenz authorizer

License: Apache GitHub release (latest by date) CircleCI codecov Go Report Card GolangCI Codacy Badge GoDoc Contributor Covenant

What is Athenz authorizer

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



To initialize authorizer.

package main

import (

    authorizerd ""

func main() {
    // Initialize authorizerd
    daemon, err := authorizerd.New(
        authorizerd.WithAthenzURL(""), // set athenz URL
        authorizerd.WithAthenzDomains("domain1", "domain2", "domain N"), // set athenz domains
        authorizerd.WithPubkeyRefreshPeriod("12h"), // optional, default: 24h
        authorizerd.WithPolicyRefreshPeriod("1h"), // optional, default: 30m
    if err != nil {
        // cannot initialize authorizer daemon
        log.Fatalf("daemon new error: %v", err)

    // Start authorizer daemon
    ctx := context.Background() // user can control authorizer daemon lifetime using this context
    if err = daemon.Init(ctx); err != nil { // initialize internal daemons in dependency order (e.g. public keys before signed policies)
        // cannot initialize internal daemons inside authorizer
        log.Fatalf("daemon init error: %v", err)
    errs := daemon.Start(ctx)
    go func() {
        for err := range errs {
            // user should handle errors return from the daemon
            log.Printf("daemon start error: %v", err)

    act := "action"
    res := "resource"

    // Authorize with access token
    at := "<certificate bound access token>"
    certPEM := "<binding certificate>"
    block, _ := pem.Decode([]byte(certPEM))
    if block == nil {
        log.Fatalln("failed to parse certificate PEM")
    cert, err := x509.ParseCertificate(block.Bytes)
    if err != nil {
        log.Fatalf("invalid x509 certificate: %v", err)
    atp, err := daemon.AuthorizeAccessToken(ctx, at, act, res, cert)
    if err != nil {
        // NOT authorized, please take appropriate action
        log.Fatalf("access token not authorized: %v", err)
    log.Printf("authorized principal in access token: %#v", atp)

    // Authorize with role token
    rt := "<role token>"
    rtp, err := daemon.AuthorizeRoleToken(ctx, rt, act, res)
    if err != nil {
        // NOT authorized, please take appropriate action
        log.Fatalf("role token not authorized: %v", err)
    log.Printf("authorized principal in role token: %#v", rtp)

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.


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

Option nameDescriptionDefault ValueRequiredExample
AthenzURLThe Athenz server""
AthenzDomainsAthenz domain names that contain the RBAC policies[]Yes"domName1", "domName2"
HTTPClientThe HTTP client for connecting to Athenz serverhttp.Client{ Timeout: 30 * time.Second }Nohttp.DefaultClient
CacheExpThe TTL of the success cache1 MinuteNo1 * time.Minute
Enable/DisablePubkeydRun public key daemon or nottrueNo
PubkeySysAuthDomainSystem authority domain name to retrieve Athenz public key datasys.authNo"sys.auth"
PubkeyRefreshPeriodPeriod to refresh the Athenz public key data24 HoursNo"24h"
PubkeyETagExpiryETag cache TTL of Athenz public key data168 Hours (1 Week)No"168h"
PubkeyETagPurgePeriodETag cache purge duration84 HoursNo"84h"
PubkeyRetryDelayDelay of next retry on request failed1 MinuteNo"1m"
Enable/DisablePolicydRun policy daemon or nottrueNo
PolicyExpiryMarginUpdate the policy by a margin duration before the policy actually expires3 HoursNo"3h"
PolicyRefreshPeriodPeriod to refresh the Athenz policies30 MinutesNo"30m"
PolicyPurgePeriodPolicy cache purge duration1 HoursNo"1h"
PolicyRetryDelayDelay of next retry on request fail1 MinuteNo"1m"
PolicyRetryAttemptsMaximum retry attempts on request fail2No2
Enable/DisableJwkdRun JWK daemon or nottrueNo
JwkRefreshPeriodPeriod to refresh the Athenz JWK24 HoursNo"24h"
JwkRetryDelayDelay of next retry on request fail1 MinuteNo"1m"
jwkURLsURL to get jwk other than AthenzURL[]No"http://domain1/jwks", "http://domain2/jwks"
AccessTokenParamUse access token verification, details: AccessTokenParamSame as AccessTokenParamNo{}
Enable/DisableRoleTokenUse role token verification or nottrueNo
RoleAuthHeaderThe HTTP header to extract role tokenAthenz-Role-AuthNo"Athenz-Role-Auth"
Enable/DisableRoleCertUse role certificate verification or nottrueNo
RoleCertURIPrefixExtract role from role certificateathenz://role/No"athenz://role/"


Option nameDescriptionDefault ValueRequiredExample
enableUse access token verification or nottrueNotrue
verifyCertThumbprintUse certificate bound access token verificationtrueNotrue
certBackdateDurBackdate duration of the issue time of the certificate1 HourNo"1h"
certOffsetDurOffset window to accept access token with a mismatching certificate thumbprint1 HourNo"1h"
verifyClientIDUse authorized client ID verificationfalseNofalse
authorizedClientIDsAuthorized client ID to certificate common name mapnilNo{ "atClientID": { "certCN1", "certCN2" } }


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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
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
    • GitHub release (latest by date)


GitHub Stars



9mos ago








8mos ago
3yrs ago
No alternatives found
No tutorials found
Add a tutorial