PolicySync: Attribute-Based Access Control

This is an Early Access feature. To enable it, contact Okta Support.

Advanced Server Access admins often assign resources to projects that are grouped by product or team. For example, you might have separate projects for your accounting, marketing, and engineering teams. The standard method used to grant users access to a server in Advanced Server Access is to enroll the server in a project, assign the users to a group, and then add that group to the project. This grants the members of the group access to all of the servers that are enrolled in the project.

There is often a need to grant users access to a subset of servers in a project. For example, you might have a team of database administrators (DBAs) that need access to all of the database servers, regardless of which project a server is enrolled in. However, creating a separate project that only contains database servers would break the model of grouping resources by teams.

Okta PolicySync enables Advanced Server Access administrators to apply attribute-based access controls (ABAC) to user groups, which can be used to provide role-based access to resources. This is accomplished by applying labels to servers and selectors to groups, similar to how clients use label selectors to identify objects in Kubernetes.

Main concepts of PolicySync

There are three main concepts used with PolicySync: authorized principals files, labels, and selectors. The following sections detail each of these concepts.

Authorized principals file

Okta PolicySync uses the OpenSSH daemon (sshd) AuthorizedPrincipalsFile configuration option. See sshd_config for more information on AuthorizedPrincipalsFile.

When PolicySync is enabled, the Advanced Server Access server agent creates the file .asa_authorized_principals in the home directory of each user, on each server that they have access to. You can change where this file is created by setting the AuthorizedPrincipalsFile option in your Advanced Server Access server agent's sftd.yaml configuration file. To configure the location, you must use one of the supported per-user tokens: 

  • %h: This expands to the user's home directory path.
  • %u: This expands to the user's username.
  • %U: This expands to the user's UID.

For example, to configure Advanced Server Access to create the authorized principals file in the user's home directory, add the following to a server's sftd.yaml configuration file:

AuthorizedPrincipalsFile: "%h/.asa_authorized_principals"

The Advanced Server Access server agent also updates the server's sshd_config file with the AuthorizedPrincipalsFile directive as defined in sftd.yaml.


While the Advanced Server Access server agent, sftd, modifies sshd_config, it's highly recommended that you do not modify it, either manually or through automation. Modifying the contents of sshd_config can lead to unsupported or broken configurations.


Because labels can come from multiple sources, each label is automatically prefixed with its source. For example, if the label build:trunk originates from Amazon Web Services (AWS), then it's prefixed with aws to appear as aws.build:trunk. This avoids having issues when multiple sources use the same key (for example, the same label is used both by AWS and in an Advanced Server Access server agent configuration file (sftd.yaml)).

Server selectors

Server selectors on project groups have the following characteristics:

  • Users in a group with selectors only have access to servers that meet all of the requirements of that selector.

  • Users who belong to multiple groups have access to servers that belong to the union of the selectors of those groups.

  • Selector keys can optionally specify the label's source.

    • If the source is included, then only servers that include that label from that source will match. For example, if you use the selector sftd.role=db, then only servers whose sftd.yaml configuration file contains the label role: db will match.

    • If the source is omitted, then any server that contains the specified label will match. For example, if you use the selector role=db, then any servers with the label aws.role: db or sftd.role: db will match.


Carefully consider the configuration of your labels and selectors. You must ensure that your users have access to bastions in their projects to ensure that they can connect to the servers.

Use labels and selectors for granular server access


To use labels and selectors in your Advanced Server Access project, the following must be true:

  • OktaPolicySync must be enabled for your team. To enable it, contact Okta Support.

  • The servers in the project must be running Advanced Server Access server agent version 1.52.1 or later.

Add a label to a server

You can add labels to an Advanced Server Access server in its configuration file. This is done by creating a Labels section in the server's sftd.yaml file and adding each label to that section. For example, the following section demonstrates how to define the labels role: db and env: prod in sftd.yaml:


        role: db

        env: prod

Add a selector to a project group

You assign selectors at the project group level. To assign a selector:

  1. Click Projects.
  2. Click the gear gear icon beside the project and select Edit.
  3. Ensure that Specific Servers is selected in the Server Access section.
  4. Enter one or more server selectors in the Server Selector Tags section, pressing Enter after entering each selector.
  5. Click Submit.

Related topics

Configure and use the Advanced Server Access server agent