# Authorization

{% hint style="danger" %}

### <mark style="color:red;">**The BastionZero product is maintained for existing BastionZero customers only.**</mark>&#x20;

Moving forward, we are natively rebuilding BastionZero’s technology as Cloudflare’s [Access for Infrastructure](https://developers.cloudflare.com/cloudflare-one/applications/non-http/infrastructure-apps/) service.
{% endhint %}

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.

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:purple;"><strong>Policy Management</strong></mark></td><td>Manage who and what can access your targets</td><td></td><td><a href="#policy-management">#policy-management</a></td></tr><tr><td><mark style="color:purple;"><strong>API Authorization</strong></mark></td><td>Learn how to use an API key to interact with the BastionZero API</td><td></td><td><a href="#using-an-api-key">#using-an-api-key</a></td></tr><tr><td><mark style="color:purple;"><strong>Create an API Key</strong></mark></td><td>Create an API key for use with the BastionZero API or for target registration</td><td></td><td><a href="#creating-an-api-key">#creating-an-api-key</a></td></tr></tbody></table>

## Policy Management

BastionZero implements policy-based access controls using the [Open Policy Agent](https://www.openpolicyagent.org) (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.

{% hint style="info" %}
[View your policies on the web app](https://cloud.bastionzero.com/admin/policies/overview)
{% endhint %}

## Policy Types

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:purple;"><strong>Target access policy</strong></mark></td><td>Configure access to</td><td>Linux hosts</td><td><a href="#target-access">#target-access</a></td></tr><tr><td><mark style="color:purple;"><strong>Kubernetes policy</strong></mark></td><td>Configure access to</td><td>Kubernetes clusters</td><td><a href="#kubernetes">#kubernetes</a></td></tr><tr><td><mark style="color:purple;"><strong>Proxy policy</strong></mark></td><td>Configure access to virtual</td><td>targets (database, web)</td><td><a href="#proxy">#proxy</a></td></tr><tr><td><mark style="color:purple;"><strong>Session recording policy</strong></mark></td><td>Configure recordings of</td><td>shell sessions</td><td><a href="#session-recording">#session-recording</a></td></tr><tr><td><mark style="color:purple;"><strong>Just-in-time policy</strong></mark></td><td>Configure ephemeral</td><td>access to any target type</td><td><a href="#just-in-time">#just-in-time</a></td></tr></tbody></table>

### 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](https://cloud.bastionzero.com/api).

![Target access policy in the web app](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2Fgit-blob-9d6a7e32f5ff7f6eaa200bd921661672bc7a744d%2Ftap.png?alt=media)

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.

{% hint style="info" %}
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.
  {% endhint %}

### 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.

![Kubernetes policy in the web app](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2Fc5sGiuS7uvDWh9MyJbEM%2Fk8s.png?alt=media\&token=1428428c-fdb8-4a27-852c-47c7fb1160fa)

### 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.

![Proxy policy in the web app](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2Fr5IVnJfVyP8SVi8knwId%2Fproxy.png?alt=media\&token=9163563f-6eb0-43fd-a762-df3a27d4fe31)

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.

![Session recording policy in the web app](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2FsMWFxHuszCeNf6RI9kn7%2Fsr.png?alt=media\&token=f85b1db3-dfc6-4c35-8e8b-b7e9f14f75ee)

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](https://asciinema.org) as its session recorder. These recordings may be downloaded, searched, and are displayed in fast intervals as opposed to the experienced user time.

{% hint style="info" %}
[View available session recordings in your organization](https://cloud.bastionzero.com/admin/session-recordings)
{% endhint %}

### Just-in-time

{% hint style="warning" %}
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](https://docs.bastionzero.com/docs/automation-and-integrations/slack).
{% endhint %}

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:

1. Through manual approval via BastionZero app for Slack by an administrator in your BastionZero organization.
2. 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.

<figure><img src="https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2F8FLXikRO2hoWIg3A4CAp%2Fspaces_oMfD0EzU2IyYSm8Bdt30_uploads_BO4VR2rRZ7yy38S6zbsK_image.webp?alt=media&#x26;token=0c89a7a1-1a63-4fca-8d62-f790b7562787" alt=""><figcaption><p>Example of a just-in-time policy in the web app</p></figcaption></figure>

{% hint style="info" %} <mark style="background-color:purple;">**POLICY PRECEDENCE**</mark>

**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:

1. Manual policy with access duration of 5 mins
2. Manual policy with access duration of 10 mins
3. Auto policy with access duration of 5 mins
4. Auto policy with access duration of 10 mins
   {% endhint %}

## API Keys

API keys in BastionZero serve two purposes:

1. As access keys to authenticate API requests.
2. 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](https://cloud.bastionzero.com/admin/apikeys).

![View of an organization's keys in the BastionZero web app](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2FpewSrFFSBvEQgWThrzk6%2Fapi%20key%20replacement%20image.png?alt=media\&token=8b522e95-73dd-4e22-ae7d-29b1bb07eeb1)

{% hint style="danger" %}
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.
{% endhint %}

### Registration API Keys

{% hint style="info" %}
**NOTE**: Registration API keys are reusable. There is no need to generate a new key for each target registration.
{% endhint %}

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

{% hint style="info" %}

## For use with Postman, curl, or your own business logic

Pass your API key using the **`X-API-KEY` header**.
{% endhint %}

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.

![cloud.bastionzero.com main page](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2FaGB8mfA6HME3wp1MEvJE%2Fapi%20key%20menu.png?alt=media\&token=1c149b44-83cb-4bec-ab08-080124131982)

* 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.

![For demonstration purposes: a newly generated Registration API key](https://2296692744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB1x0ofz14evTHlwIRKaW%2Fuploads%2F8tdUKnCzsU4nASYMT61y%2Fgenerate%20api%20key.png?alt=media\&token=69e4c63c-8e22-4d41-98f7-aa049dfe05cc)

{% hint style="danger" %}
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.
{% endhint %}