<p>By Mujib Wahab,  Henry Avetisyan and Lee Boynton<br/></p><h2>Data Model</h2><p>Having a firm grasp on some fundamental concepts in Athenz data model will help you understand the Athenz architecture, the request flow for both centralized and decentralized authorization in system view, and how to set up role-based authorization.</p><figure data-orig-width="889" data-orig-height="564" class="tmblr-full"><img src="https://66.media.tumblr.com/e4e5d1faf04fb7322e6f9ba8bcde2c84/tumblr_inline_oppgxzWA8K1r5qgp3_540.png" alt="image" data-orig-width="889" data-orig-height="564"/></figure><p><b>Domain:</b> Domains are namespaces, strictly partitioned, providing a context for authoritative statements to be made about entities it contains. Administrative tasks can be delegated to created sub-domains to avoid reliance on central “super user” administrative roles.</p><p><b>Resource/Action:</b> Resources and Actions aren’t explicitly modeled in Athenz, they are referred to by name. A resource is something that is “owned” and controlled in a specific domain while the operations one can perform against that resource are defined as actions. A resource could be a concrete object like a machine or an abstract object like a security policy. For example, if a domain media.finance product wants to authorize access to a database called “storage” that it owns, the resource name for the database may look like this: media.finance:db.storage and the supported actions on this resource would be insert, update and delete.</p><p><b>Policy:</b> To implement access control, we have policies in our domain that govern the use of our resources. A policy is a set of assertions (rules) about granting or denying an operation/action on a resource to all the members in the configured role.</p><p><b>Role:</b> A role can be thought of as a group; anyone in the group can assume the role that takes a particular action. Every policy assertion describes what can be done by a role. A role can also delegate the determination of membership to another trusted domain; for example, a netops role managed outside a property domain. This is how we can model tenant relations between a provider domain and tenant domains. Because roles are defined in domains, they can be partitioned by domain, unlike users, which are global. This allows the distributed operation to be more easily scaled.</p><p><b>Principal:</b> The actors in Athenz that can assume a role are called principals. These principals are authenticated and can be users (for example, authenticated by their Unix or Kerberos credentials). Principals can also be services that are authenticated by a service management system. Athenz currently provides service identity and authentication support.</p><p><b>User:</b> Users are actually defined in some external authority, e.g. Unix or Kerberos system. A special domain is reserved for the purpose of namespacing users; the name of that domain is “user,” so some example users are: user.john or user.joe. The credentials that the external system requires are exchanged for a NToken before operating on any data.</p><p><b>Service:</b> The concept of a Service Identity is introduced as the identity of independent agents of execution. Services have a simple way of naming them, e.g. media.finance.storage identifies a service called “storage” in domain media.finance. A Service may be used as a principal when specifying roles, just like a user. Athenz provides support for registering such a Service, in a domain, along with its public key that can be used to later verify a N-Token that is presented by the service.</p><h2>System View</h2><p>Let’s look at all the services and libraries that work together to provide support for Athenz authorization system.</p><figure data-orig-width="2000" data-orig-height="1200" class="tmblr-full"><img src="https://66.media.tumblr.com/ffe82716e194740d904c6455a6a7be10/tumblr_inline_opp8scGZMZ1rma199_540.png" alt="image" data-orig-width="2000" data-orig-height="1200"/></figure><p><b>ZMS (authZ Management System):</b> ZMS is the source of truth for domains, roles, and policies for centralized authorization. In addition to allowing CRUD operations on the basic entities, ZMS provides an API to replicate the entities, per domain, to ZTS. ZMS supports a centralized call to check if a principal has access to a resource both for internal management system checks, as well as a simple centralized deployment. Because ZMS supports service identities, ZMS can authenticate services. For centralized authorization, ZMS may be the only Athenz subsystem that you need to interact with.</p><p><b>ZTS (authZ Token System):</b> ZTS, the authentication token service, is only needed to support decentralized functionality. In many ways, ZTS is like a local replica of ZMS’s data to check a principal’s authentication and confirm membership in roles within a domain. The authentication is in the form of a signed ZToken that can be presented to any decentralized service that wants to authorize access efficiently. Multiple ZTS instances can be distributed to different locations as needed to scale for issuing tokens.</p><p><b>SIA (Service Identity Agent) Provider:</b> SIA Provider is part of the container, although likely built with Athenz libraries. As services are authenticated by their private keys, the job of the SIA Provider is to generate a NToken and sign it with the given private key so that the service can present that NToken to ZMS/ZTS as its identity credentials. The corresponding public key must be registered in ZMS so Athenz services can validate the signature.</p><p><b>ZPE (AuthZ Policy Engine):</b> Like ZTS, ZPE, the authorization policy engine is only needed to support decentralized authorization. ZPE is the subsystem of Athenz that evaluates policies for a set of roles to yield an allowed or a denied response. ZPE is a library that your service calls and only refers to a local policy cache for your services domain (a small amount of data).</p>