Authorization
Administrators' guide to managing authorization in BastionZero
There are two main components of authorization in BastionZero: policy and API keys. Use the shortcuts below to navigate to the section of your choosing.
Policy Management
BastionZero implements policy-based access controls using the Open Policy Agent (OPA). On top of OPA, BastionZero provides its own abstraction layer for all policy types provided to the administrator. These policies are designed to be simple to implement and manage over time.
BastionZero employs a straightforward policy model involving subjects, actions, and resources. Subjects are entitled to perform an action based on the successful evaluation on a policy. All policies are therefore permissive in nature.
Policy Types
Target Access
The target access policy provides users, service accounts, and groups the ability to shell, tunnel, and/or copy, from a specific target or an environment (a group of targets). Each of these parameters can be enabled independent of or with each other. The policy can be specified through the web app or directly using the BastionZero API.
In addition, the target access policy has the ability for the administrator to specify one or more Linux users available to the subjects of the policy. For example, if writing a target access policy to an AWS EC2 instance, the administrator can specify the ec2-user as an allowed target user. Through the BastionZero command logs, the administrator can then identify which SSO user entered what command as the ec2-user on a particular target.
When an SSO user appears in more than one policy for the same target, as in the case where that user may have access to both a read-only and privileged target user, the SSO user must select which target user to use for that connection.
BastionZero supports using substitution parameters for target users in target connect policies. To use a substitution parameter, surround a supported parameter with curly brackets, i.e., {username}. An example of this is shown in the image above. We support the following parameters for substitution:
username: Allows a user to connect to Linux targets via shell and ssh using their IdP username as the target user. This IdP username is what preceeds the@in the email the user uses to authenticate with their SSO. Note: BastionZero will not create a user that does not already exist. The administrator must ensure users and permissions are created on the Linux machines prior to connecting through BastionZero.
Kubernetes
The Kubernetes policy provides users and service accounts the ability to perform kubectl actions, including shell exec, against the cluster. An BastionZero user may assume a particular cluster role, based on policy. This role can be defined as a particular target user or target group depending on whether a user or group was specified when the k8s role bindings were made. BastionZero is very flexible in this regard, and the k8s command logs will disambiguate which BastionZero user executed which kubectl command within a particular target user or target group to role binding.
Proxy
The proxy policy in BastionZero provides users and groups the ability to access databases or webservers from a specific target or environment. Each of these parameters can be enabled independent of or with each other. The policy can be specified through the web app or directly using the BastionZero API.
Similarly to the target access policy, proxy policies have the ability for the administrator to specify one or more target users available to the subjects of the policy. For example, if writing a proxy policy to a Postgres database, the administrator can specify the default postgres as the allowed target user.
When an SSO user appears in more than one policy for the same target, as in the case where that user may have access to both a read-only and privileged target user, the SSO user must select which target user they will use for that connection.
Session Recording
The session recording policy provides administrators the ability to record a user, service account, and group shell sessions. By default, BastionZero records stdout. However, the administrator has the option to also record stdin. This can be configured via the policy action field.
BastionZero shell recordings are live; at any time, an administrator may view, download, or even delete, a recording in progress. BastionZero will keep recording the subject's shell session until the subject is removed from the policy or the policy is removed from the system.
BastionZero uses ascinema as its session recorder. These recordings may be downloaded, searched, and are displayed in fast intervals as opposed to the experienced user time.
Just-in-time
To be able to author just-in-time (JIT) policy, you must first enable the BastionZero app for Slack from Settings -> App Integrations -> Slack. Learn more about that here.
The just-in-time policy gives administrators the ability to grant temporary access to any BastionZero target for users within their organization. This is done by leveraging pre-existing policies and creating a superset of the targets, actions, and target users included in those policies. Like other policy types, administrators can configure which SSO users and/or groups the JIT policy applies to.
Granting temporary access can be done in two ways:
Through manual approval via BastionZero app for Slack by an administrator in your BastionZero organization.
Through auto-approval.
This setting can be modified after policy creation; simply edit the policy within the web app to do so.
The duration a user can access a target for is also configurable in increments of hours or minutes.
When a user requests access to a target and has a valid JIT policy in place, BastionZero will create a new policy that governs that user's access explicitly. It will have the prefix "JIT-" followed by a random 8 character string. This policy will automatically delete itself at the time the user's access expires.
POLICY PRECEDENCE
Just-in-time policy vs. other policy types
If a user already has access to a target through another policy type, a just-in-time policy will not override that allowed access.
To ensure your just-in-time setup works as intended, the users and groups configured in a just-in-time policy must not have access to the target(s) through any other policies.
Just-in-time policy vs. just-in-time policy
If two or more just-in-time policies apply to the same user and target:
The policy that requires manual approval will always supersede a policy that grants automatic access.
For policies of the same grant type (i.e., both automatic or both manual), the policy with the smallest target access duration will supersede the other.
For example, below is the order of precedence for 4 just-in-time policies that all apply to the same target and user:
Manual policy with access duration of 5 mins
Manual policy with access duration of 10 mins
Auto policy with access duration of 5 mins
Auto policy with access duration of 10 mins
API Keys
API keys in BastionZero serve two purposes:
As access keys to authenticate API requests.
As registration keys to register targets to your organization.
Even with a valid API key, all API requests are subject to a policy check before they are permitted to execute. All active API and Registration API keys are shown in the organization key dashboard.
Once an API key pair is created, the key ID and secret are displayed to the administrator. This is the only time the secret is available. Once saved, the secret cannot be retrieved by an admin. We strongly recommend storing your API secrets in a vault or other secure storage. Avoid storing keys in files, code, or anywhere public.
Registration API Keys
NOTE: Registration API keys are reusable. There is no need to generate a new key for each target registration.
Registration keys can only be used to register targets. Any attempt to use a registration key for non-registration APIs will fail because the policy check will return Deny. Registration keys can be associated to an application, an end user, or an administrator in multiple ways within BastionZero.
The services will default to enforcing and using Global Registration Key Settings.
In this case:
All registration keys are created and assigned by the administrator.
The default registration key is used when autodiscovery scripts are requested from BastionZero by an administrator.
If the Global Registration Key Settings are disabled:
All administrators are provided their own unique registration key pair.
Administrators may create and assign additional registration keys.
The administrator's registration key is used when requesting autodiscovery scripts.
Using an API Key
All API requests are made over HTTPS.
Creating an API Key
Navigate to https://cloud.bastionzero.com.
Log in using the same credentials you use for your identity provider. Once complete, you’ll see the main page show below.
Select "Create" in the upper righthand corner and choose "API Key." For Registration keys, you MUST select the Registration key box below the name field. Clicking "Generate API Key" will then display the new API key ID and secret.
Once the API key pair is created, the key ID and secret are displayed. This is the only time the secret is available. Once saved, the secret cannot be retrieved by an admin. We strongly recommend storing your API secrets in a vault or other secure storage. Avoid storing keys in files, code, or anywhere public.
Last updated
