Project: Athenz (Provisioning / Key Management)
File: athenz_templates.md

Templates are a collection of predefined roles, policies and services that can be applied on a domain. Imagine in a real world scenario if you are creating a solution for any organization(Openstack, Kubernetes) and subsequently want to set up provisioning rules(a static set of roles and policies) for the solution, rather than requiring each domain admin to create each of these roles and policies manually, you can pre-bundle the roles and policies as a template and Athenz will automatically apply them for you while creating or updating a domain. All templates will be managed by the Athenz System Administrators. To create / update templates, the administrators should create a file named solution_templates.json and store it in their data repository. The file should follow the format below ``` { "<template_name>": { "metadata": {}, "roles": [<athenz-roles>], "policies": [<athenz-policies>], "services": [<athenz-services>] } } ``` A sample file can be found at `servers/zms/conf/solution_templates.json` A Template consists of metadata, services, roles and role metadata, policies with assertions. Please find the explanation for every entity below Metadata contains critical fields to represent vital characteristics of a template. Look at the sample structure below for one of the templates in use. ``` "metadata": { "latestVersion": 1, "timestamp": "2020-06-16T00:00:00.000Z", "description": "Description of template", "keywordsToReplace": "env,track", "autoUpdate": false } ``` A - Description - description of the template (restrict it to 140 characters if possible) B - latestVersion - to manage versioning. Everytime there is a change in the template including a template metadata change, Make sure to bump up the latestVersion field by 1. C - Timestamp - recorded timestamp when you update(including metadata change) a template. This is purely to help you time track template changes. D - keywordsToReplace - this field is a comma separated placeholder you can add to your role/policy name which will be auto replaced on the fly. for ex: keywordsToReplace will be set to env, track for a role name domain:role.some-role.env.track.track.emitters". You should leave keywordsToReplace field empty if you do not have any placeholders in your role or policy name. (for ex: "keywordsToReplace": "",) Note: domain is the only exception here. When applying a template to a domain, the server will automatically include the correct domain name in role/policy names by replacing the domain placeholder with the appropriate value so do not worry about adding it. Example structure of roles/policies which uses multiple placeholders: ``` "roles": [ { "name": "domain:role.some-role.env.track.track.emitters", "modified": "1970-01-01T00:00:00.000Z" } ], "policies": [ { "name": "domain:policy.some-policy.env.track.track.emitters", "modified": "1970-01-01T00:00:00.000Z", "assertions": [ { "resource": "some-resource.env:role.track.track.emitters", "role": "domain:role.some-role.env.track.track.emitters", "action": "assume_role" } ] } ] ``` Roles can have attributes like name, modified timestamp, Role Meta attributes (check the complete role meta attributes list below) and roleMembers. By default roles that are created by the template will not have any members unless the role members are hard-coded in the template (check the example structure below). The domain administrator will need to add members to those roles after the domain is created or the template has been applied to a domain. Now if you notice role members array in the image below, members can also have placeholders which have to be added to keywordsToReplace. Sample structure for Roles with role members: ``` "roles": [ { "name": "domain:role.awsinstancelaunch_provider", "modified": "1970-01-01T00:00:00.000Z", "roleMembers": [ { "memberName": "athens.aws.*" } ] }, { "name": "domain:role.aws.ssh_login", "modified": "1970-01-01T00:00:00.000Z" }, { "name": "domain:role.awssshcert_request", "modified":

"roleMembers": [ { "memberName": "domain.service" } ] } ] ``` Allowed Role Meta Attributes: ``` "selfServe": "false", "memberExpiryDays": 90, "tokenExpiryMins": 30, "certExpiryMins": 10, "serviceExpiryDays": 50, "memberReviewDays": 65, "serviceReviewDays": 15, "reviewEnabled": true ``` Array of policies with name, modified timestamp and array of assertions. Check the sample Json below. "policies": [ { "name": "domain:policy.awsinstancelaunch_provider", "modified": "1970-01-01T00:00:00.000Z", "assertions": [ { "resource": "domain:service.service", "role": "domain:role.awsinstancelaunch_provider", "action": "launch" } ] }, { "name": "domain:policy.aws.ssh_login", "modified": "1970-01-01T00:00:00.000Z", "assertions": [ { "resource": "domain:aws.service.*", "role": "domain:role.aws.ssh_login", "action": "ssh_login", "effect": "DENY" } ] } Templates can be applied via and via Athenz UI. let's take a look at a few examples on how to apply different types of templates. Templates with placeholders in role and policy names (aka comma separated values in keywordsToReplace under template metadata field) will have to pass the key value pair for all placeholders via CLI. However, Athenz UI will automatically detect the placeholders and prompt the user to enter those placeholder values without which you cannot apply a template ``` zms-cli -d some-domain set-domain-template some-template-name env=ecli track=clit ``` Templates with static role and policy names i.e. no placeholders ``` zms-cli -d some-domain set-domain-template other-template-name ``` The update button with blue background means there is a latest version of the template available to apply and the update button with white background means there is no new version but you can still apply if you accidentally deleted a policy or role which is part of the template and wanted to patch it up. Auto update flag in templates lets the zms server to patch up the changes made to roles and policies automatically. This way the template creator does not need to communicate the tenant domains to patch them up manually through Athenz UI or CLI. AutoUpdate runs on zms servers during application startup in an uninterrupted fashion and applies roles and policies for all eligible templates. This feature will work only for templates with no placeholders at the moment i.e. the metadata section in the template should have the following values keywordsToReplace="" and autoUpdate set to true. Note: it is important to bump up the latestVersion flag to apply any changes in the template including metadata changes like autoUpdate and keywordsToReplace. Auto update will not kick in if the server does not detect a version bump in the template. No. you can only update a template in the UI using the apply template button. You have to apply template for the first time via Cli If any of the template names is invalid, the request will be rejected with a Bad Request error message indicating the invalid template name. If the template is not found, then the request will be rejected with a Not Found error message indicating the template name thats not registered in ZMS. Current version is the template version already applied on your domain and the latest version is a new version that is available for you to apply. You will see a dark blue button in the UI when there is a latest version. Go to the UI and click on the update button(with white background if the template already has the latest version) and the roles and policies will be recreated. One has to manually clean it up. ``` Template commands: list-server-template list-domain-template show-server-template template set-domain-template template [template ...] [param-key=param-value ...] delete-domain-template template ```