athenz / athenz

Open source platform for X.509 certificate based service authentication and fine grained access control in dynamic infrastructures. Athenz supports provisioning and configuration (centralized authorization) use cases as well as serving/runtime (decentralized authorization) use cases.

Athenz

Athenz is an open source platform for X.509 certificate based service authentication and fine-grained access control in dynamic infrastructures. It supports provisioning and configuration (centralized authorization) use cases as well as serving/runtime (decentralized authorization) use cases. Athenz authorization system utilizes x.509 certificates and industry standard mutual TLS bound oauth2 access tokens. The name “Athenz” is derived from “AuthNZ” (N for authentication and Z for authorization).

Table of Contents

• Background
• Install
• Usage
• Contribute
• License

Background

Athenz is an open source platform for X.509 certificate based service authentication and fine-grained role based access control in dynamic infrastructures. It provides support for the following three major functional areas.

Service Authentication

Athenz provides secure identity in the form of short lived X.509 certificate for every workload or service deployed in private (e.g. Openstack, K8S, Screwdriver) or public cloud (e.g. AWS EC2, ECS, Fargate, Lambda). Using these X.509 certificates clients and services establish secure connections and through mutual TLS authentication verify each other's identity. The service identity certificates are valid for 30 days only, and the service identity agents (SIA) part of those frameworks automatically refresh them daily. The term service within Athenz is more generic than a traditional service. A service identity could represent a command, job, daemon, workflow, as well as both an application client, and an application service.

Since Athenz service authentication is based on X.509 certificates, it is important that you have a good understanding of what X.509 certificates are and how they're used to establish secure connections in Internet protocols such as TLS.

Role-Based Authorization (RBAC)

Once the client is authenticated with its x.509 certificate, the service can then check if the given client is authorized to carry out the requested action. Athenz provides fine-grained role-based access control (RBAC) support for a centralized management system with support for control-plane access control decisions and a decentralized enforcement mechanism suitable for data-plane access control decisions. It also provides a delegated management model that supports multi-tenant and self-service concepts.

AWS Temporary Credentials Support

When working with AWS, Athenz provides support to access AWS services from on-prem services with using AWS temporary credentials rather than static credentials. Athenz ZTS server can be used to request AWS temporary credentials for configured AWS IAM roles.

Install

• Development Environment
• Local/Development/Production Environment Setup
  • ZMS Server
  • ZTS Server
  • UI Server
• AWS Production Environment Setup
  • Introduction

Usage

• Architecture
  • Data Model
  • System View
  • Authorization Flow
• Features
  • Service Identity X.509 Certificates - Copper Argos
• Developer Guide
  • Centralized Access Control
    • Java Client/Servlet Example
    • Go Client/Server Example
  • Decentralized Access Control
    • Java Client/Servlet Example
• Customizing Athenz
  • Principal Authentication
  • Private Key Store
  • Certificate Signer
  • Service Identity X.509 Certificate Support Requirements - Copper Argos
  • OIDC Authentication Provider Support for AWS EKS
• User Guide
  • ZMS Client Utility
  • ZPU Utility
  • Registering ZMS Service Identity
  • ZMS API
  • ZTS API

Contribute

Please refer to the contributing file for information about how to get involved. We welcome issues, questions, and pull requests.

You can also contact us for any user and development discussions through our groups:

• Athenz-Dev for development discussions
• Athenz-Users for users questions

The sourcespy dashboard provides a high level overview of the repository including module dependencies, module hierarchy, external libraries, web services, and other components of the system.

License

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

athenz's Issues

remove rdl-java from zms-java-client uber jar

when rdl-java jar is shaded into zms-java-client without relocating, we end up having multiple copies for rdl-java in server webapp war files and since there is a custom jackson [de]serializer defined for Timestamp class, in some instances we end up with empty json documents {} for timestamp fields.

Include support for ECDSAWithSHA256 keys in zts-svccert

Current zts-svccert is supporting only SHA256WithRSA.

Introduce support for ECDSAWithSHA256

provide rate limiter filter with default no-op implementation

athenz should provide a rate limiter filter such that properties using Athenz can write their own implementation and protect their services.

refresh instance request missing required attributes

The instance identity object returned by the post refresh request should have provider and instance id as required attributes but they're missing

update dependent packages

run mvn versions:display-dependency-updates to get the updated list of packages, review and make sure the latest versions are used.

remove shading from zms java client

shading of jersey and jackson libraries is causing issues when zms java client is being used within an application that itself uses rdl-java library. since rdl-java uses a custom serializer/deserializer when the jackson libraries are shaded, timestamp objects are not being properly processed.

extend SimpleServiceIdentityProvider to allow the caller specify Authority

rather than hard coding PrincipalAuthority in the SimpleServiceIdentityProvider class, it should be extended to have a constructor where the caller can specify the Authority class to be used by the provider.

zpu go version must use zts client to get public keys

zpu cannot use the zms client to get public keys since that api requires authentication. instead zts server is the one exposing a public interface to access public keys.

update to the latest jetty release - jetty-9.4.6.v20170531

utility to request zts role certificates using service identity certificates

provide a utility that a principal already having access to its service certificate can request from ZTS Server.

new deleteUser api has no role audit log history

while the new deleteUser api automatically deletes all invalid user principals, it does not generate any audit log entries for roles. So as a domain admin, when looking at the role audit log history, they don't know how/when the user principal was removed.

Instead of relying on the datastore to automatically cleanup all references to the user, it should use standard delete role member api so audit log records are generated for each one. more expensive on server side but more admin friendly

improve get signed domains api to avoid domain list if specific domain is asked

when the getSignedDomains api is called with specific domain name, the server still does a domain list first before filtering the response for the given domain name. this is unnecessary and can be avoided.

improve handling for user principals that include . in their names

Since it's possible for the user to have . in their names (e.g. company id format is first.last), this will cause issues when the user is identified as user.joe.smith. So is this user principal user.joe.smith or service smith in user.joe domain?

We should provide the capability to separate and user and home domain namespaces. The user namespace will still be name while the home namespace will default to user but can be changed to be, for example, home. Then the authority can provide a mapping to replace the . in the user names to another character. Then we'll end up:

user.joe.smith as user principal joe.smith
home.joe-smith is the home domain for user.joe.smith (the user authority will automatically replace joe.smith with joe-smith based on admin implementation).

zts client prefetcher task closes the client instance

The prefetcher task is closing the client that was passed in thus would not allow any other operation to be completed by that client.

zms java client json/jackson serialize issue with timestamp

zms java client shades and relocations jackson classes. however, this seems like to cause problems when serializing object that include Timestamp fields which has its own custom serializer. the fix seems to be for zms java client not to shade com.fasterxml.jackson.core and not to relocate the other jackson classes it shades (e.g com.fasterxml.jackson.jaxrs)

Docker Image is not documented

https://hub.docker.com/r/athenz/athenz/ has no documentation. Can you please populate it with content from https://github.com/yahoo/athenz/blob/master/docs/setup_docker.md

Provide a CloudFormation Template instead of screenshot to launch a new instance

For example
https://aws.amazon.com/quickstart/
https://docs.aws.amazon.com/quickstart/latest/linux-bastion/welcome.html

quota support for domain objects

implement per-domain quota support to restrict each domain admin how many roles, role-members, policies, policy-assertions, services, service-hosts, service-public keys, entities and subdomains can be created.

The subdomain should be applied at the top level and the value specified at the subdomain level should be ignored.

Use a human readable time stamp as part of the ami name

Instead of using "Athenz 1491517496" as the AMI name, it would be better to use something like "Athenz-20170406152456"

This is so that it's consistent with some of the popular AMI name such as
amzn-ami-hvm-2017.03.0.20170417-x86_64-gp2 - ami-c58c1dd3
RHEL-7.3_HVM_GA-20161026-x86_64-1-Hourly2-GP2 - ami-b63769a1

update docker run command to specify exposed port numbers and hostname

With the latest UI since it needs to contact ZMS to get an authorized service token, the functionality for docker images is broken. We need to specify the exposed port numbers in our run command plus specify the ZMS and UI server names to avoid using container hostnames which are not resolvable when the user runs their web browser on their laptop.

Allow Service to be created without a public key, and add optional description

Currently, while doing putServiceIdentity, the api validates if at least one valid public key is provided in the input.

Decouple this. Allow service creation without passing public key. And public keys can be added through separate api calls.

Add optional 'description' to service.

remove Struct references from Crypto class

we're not longer using Structs for athenz objects so any helper api from the Crypto class should be removed to avoid any code that's not used anywhere in the system.

zms client handling of add credentials from authority with cookie headers

If the authority requires credentials to be passed with cookie headers, then the header is defined as "Cookie.". However, zms java client does not have support for this format. It needs to check if the header starts with "Cookie." and handle accordingly.

Use slave mysql servers for some of the read operations

ZMS currently only uses the master db for both read and write operations. Instead, it should provide the option to configure read-only databases that could be used for read-only operations. This presents read-after-write problem where if the replication is not fast enough after adding an entry, the subsequent read could be handled from a slave that hasn't received the update, however, the benefit of unloading the read operations to slaves is quite important.

zms java client is missing the putUserMeta method

zms java client is not exposing the putUserMeta method from the rdl generated class.

Identity response missing required attributes

postInstanceRegisterInformation api returns an Identity object where the provider and instance id fields are required according to the RDL but are not included in the response.

Docker Images for production deployment

If I wanted to deploy and scale Athenz to Docker Compose or K8s, we don't have independent images for each service or a way to only activate services independently.

What would be the best way to deploy Athenz to K8s in a way that allows us to scale each service independently. Do you have a docker-compose file as an example?

Adding zpu-go-client

Make the Athenz ami image available in other regions

Currently it seems the Athenz ami image is only available in the Oregon (us-west-2).

When I search for it under us-east-1 or us-west-1, the search return empty.

I think the image should be available in more than on region.

Using 0.0.0.0/0 in the security group for port 22 is a very bad idea

improve handling of included/excluded ciphers

Jetty 9.4 now defaults to strong ciphers forcing clients to use TLS 1.2. The jetty container only allows the list of excluded ciphers with default values which should not be specified since jetty is already using "^_(MD5|SHA|SHA1)$" for the exclusion list.

We should remove the default excluded cipher list and also provide a property for specifying included cipher list to give more flexibility to the system admin.

Change return type of getAWSCredentialProvider method to AWSCredentialsProvider

support for fields specified during api call when applying templates

Currently templates are static set of roles and policies - the only variable being the domain name. The requirement from MH2 is to allow dynamic variables defined in the template where the caller can specify what those values should be.

We currently have domain which is replaced with the actual domain name. Now, we can additional variables into the template - e.g:

{code}
"paas_assertions": {
"policies": [
{
"name": "domain:policy._app__deploy",
"modified": "1970-01-01T00:00:00.000Z",
"assertions": [
{
"resource": "domain:daemon.service",
"role": "domain:role._app__deployer",
"action": "update”
}
]
}
]
}
{code}

So in this template we have three variables:

domain - user has no control over this one
service - service name
app - application name

So then zms-cli (which also needs to be updated along with the RDL,etc) will execute the following command:

zms-cli -d sports.site add-template paas_assertions app=api service=storage

Requirements:

1. The rules/policies that the templates will generate will be unique - you can't get the same role/policy name from different templates

Request to add athens-jetty-container binary to the bintray repository

set temp directory for webapps

we should set the temp directory to jetty.home/temp instead of using /tmp

Add RoleToken support in Go libs

Add a ztsroletoken library

athenz use standard convention for artifact Ids and jar names

it generates files like auth_core.jar, server_common.jar which are too generic names. they should include athenz_ in front of them to distinguish and avoid collisions.

we should make consistent with standard naming conventions and use -'s in names as well.

getUserToken API should return the header name as well

When the user requests a principal token (ntoken) from ZMS, it needs to know what header to use for subsequent operations with those credentials. The user token api should have an optional header query attribute so that the client can ask for that header name.

zts java client should skip null fields when generating CSRs

when generating a csr, zts java client should check if csr dn and/or domain fields are null or not and if null, not include them otherwise csr create request will fail with invalid dn error.

Use 'ztsroletoken' as the package name instead of 'roletoken'

This is to match the naming convention used by zmssvctoken

zts-roletoken enhancments

1. allow the caller to specify the expiration time

2. allow ntoken to be specified in a file instead of command line

Docker Image is not tagged

There is only one tag on Docker Hub (latest). There are 21 releases on GitHub.

For teams that use automation for deploying Docker images, it's heavily recommended not to use latest to ensure consistency when scaling up nodes.

Can you please add tags for all releases?

strip out roles for proxy user requests instead of rejecting

when the request comes by a proxy user on behalf of the principal, ZTS verifies that the principal and proxy principal both have access to the role. However, if there is mismatch, it reject the requests. Rather than rejecting the request, it should automatically strip out any roles that both principals don't have access to since that avoids making multiple calls to get one role at a time.

Add support for HAProxy proxy protocol

Add config option to enable proxy protocol supported by HAProxy and Amazon Classic Load Balancer

Adding implementation of AWS Credentials Provider

The AWSTemporaryCredentials is not an implementation of AWSSessionCredentials. So client libraries need to wrap it in their own providers.
Adding implementation of AWSSessionCredentialsProvider as part of ZTS library

domain updates in ZTS should be logged with INFO level

when ZTS is updating domains from ZMS, they're only logged with DEBUG level so if the admin wants to know if the domain changes are being properly propagated to ZTS, the DEBUG level must be turned on. Instead we should use INFO level to indicate the number of domains being updated and which domains.

ZMS should not return Access-Control-Allow-Origin with * as fall through

If there is no Origin header value specified, the server returns Access-Control-Allow-Origin with * and it should not

Certificate Authority needs to store the role name

When CertificateAuthority is handling a TLS certificate that was issued for a role it needs to maintain both principal and role details. Right now it only looks at the principal details.

Request to add athens-jetty-container binary to the bintray repository

extend ZTS to support wildcard in role member names

ZMS already supports wildcars in role member names for centralized authorization checks -e.g. athenz.*, or *. Need to extend ZTS to support these formats for role token requests as well.