Install the ALTR Sidecar

ALTR’s sidecar can be installed in any environment, including on-premises and in cloud environments, such as Amazon Web Services (AWS). ALTR’s sidecar is available as a docker image, containing all of the necessary dependencies to run the sidecar software. Sidecar images can be found on ALTR’s Amazon Container Registry listing .

Caution

ALTR recommends installing the sidecar near the repository for optimal performance.

Installing an ALTR sidecar requires certain information and environment variables be set so that the sidecar can properly communicate with the ALTR SaaS platform for telemetry, policy information and database activity monitoring. ALTR’s sidecar must be properly networked so that data consumers can access the sidecar, and so that the ALTR sidecar can access relevant database(s).

This guide walks you through installing the ALTR sidecar on a Linux server using Docker, configuring that sidecar to connect to an OLTP database and defining impersonation policies to allow secure connections to the database using single-sign on (SSO). For help with other installment methods, contact ALTR Support .

Supported Databases

• Microsoft SQL Server versions 2019 - 15.x.x.x.x
• MySQL 8.0
• Oracle versions 19.3 -23.3
• PostgreSQL version 17.6

Supported Secret Sources

• AWS Secrets Manager
• Azure Key Vault

Prerequisites

• Single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) are enabled in ALTR
• At least one user is present in ALTR as the DATA_CONSUMER role. This can be done by assigning a user or their identity provider (IdP) group to the ALTR application
• A database is deployed that the sidecar will connect to
• A system that can run a container
• A location to run the container

ALTR’s sidecar securely accesses database credentials using a secret source.

Required Information

Database credentials (username/password)

AWS Secrets Manager

To create AWS secrets objects:

1. Log into AWS.
2. Navigate to AWS Secrets Manager.
3. Create a new secret.
   1. Specify the type as other .
   2. Select Plaintext under Key/value Pairs.
   3. Provide the password for the database credential as plaintext.
   4. Save the secret.
4. Record the credential username for later. This is the credential username not the secret name in Secrets Manager. Example: admin_user
5. Record the secret ARN for later. Example: arn:aws:secretsmanager:us-east-2:111111111111:secret:username-KkAAcC
6. Record the current AWS region for later. Example: us-east-2

Azure Key Vault

To create Azure secrets objects:

1. Log into Azure.
2. Navigate to Azure Key Vault.
3. Create a Key vault. When configuring access, ALTR expects the permission model to be Azure role-based access control , which is the default and recommended Azure setting.
4. Create a new secret.
   1. Enter a Name , which is the secret name. This is used to register the repository user in ALTR.
   2. Enter a plaintext Secret value , which is the password for the secret name.
   3. Verify Enabled is set to Yes .
   4. Save the secret.
5. Record the Vault URI for later. Example: https://123sidecar456.vaultazure.net/
6. Record the secret’s Name for later. Example: prod-user-admin

Grant the sidecar server access manager privileges via a secret source.

AWS Secrets Manager Access

The sidecar must have IAM access to the AWS secret objects for repository users.

Required Information

IAM Secret ARN Example: arn:aws:secretsmanager:us-east-2:111111111111:secret:username-KkAAcC

To grant the sidecar IAM privileges to the AWS secrets objects:

1. Create a new AWS IAM policy.
2. Specify the GetSecretValue permission in the IAM policy for each secret ARN.
3. Save the IAM policy. Record the policy name.
4. If the instance already has an IAM role attached, attach the IAM policy from step 3 to that role. If no role is attached, create a new IAM role for the instance, attach the policy and assign the role to the instance.
5. Assign the IAM policy to the new IAM role.

Example IAM Policy:

{
  "Version": "2012-10-17",
  "Statement": [
       {
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "arn:aws:secretsmanager:us-east-2:111111111111:secret:username-KkAAcC"
        }
    ]
}

Azure Key Vault Access

Enable system identity , then grant permissions to the secret .

Required Information

• Secret Name Example: prod-user-admin
• Azure role—create a new role with the desired permissions or select a built-in role Example: Key Vault Secrets User

Enable System Identity

Enable system identity so your virtual machine can use Azure Key Vault. Make sure the sidecar is running in Azure, has identity available to it, can authenticate to the key vault and has access to the secret.

Note

This documentation outlines how to set up a system-assigned managed identity . This option assigns identity to the host so that it can be used for authentication and management. This identity is used by the host to be able to read the vault out of Azure Key Vault. Another option is to manually define and assign the identity. Refer to Azure documentation for details on manually defining the identity.

To enable system-assigned managed identity while creating a virtual machine:

1. Log into Azure.
2. Click the Management tab.
3. Click the Identity check box to enable system-assigned management identity.

To enable system-assigned managed identity on an existing virtual machine:

1. Log into Azure.
2. Navigate to your virtual machine.
3. Select SecurityIdentity in the Navigation menu.
4. Under System assigned , select On for Sta t us.
5. Click Save .

For more details on configuring managed identities on Azure virtual machines, refer to Azure’s documentation .

Grant Permissions

If you grant permissions at the vault level and not the individual secret level, the role can be assigned prior to creating the secret.

To grant permissions to the secret:

1. Assign a role to the secret. Ensure that you assign the sidecar enough permissions to read the secret. An example built-in role is Key Vault Secrets User.
2. Add members to the role assignment. When assigning members, assign access to Managed identity .

The database must be a registered repository in ALTR’s control plane so that the sidecar has the necessary information to forward connections from data consumers.

Required Information

• Hostname of database Example: 123.dbhost.com
• The port that your data is listening on must be open on the database and available to the sidecar server Example: 1521

To register the database as a repository:

1. Log into ALTR via Okta.
2. Select Data ConfigurationData Sources in the Navigation menu.
3. Click Add Data Source .
4. Locate the data source card and click Select .
5. Enter a Repository Name to identify the repository in ALTR’s control plane. The repository name must be unique, use only lowercase letters and contain no spaces.
6. Enter the Hostname . The hostname must be in RFC 1123 format, which is a URL without http:// . Example: 123.dbhost.com
7. Enter the Port number of its configured listening port. This port is leveraged when ALTR’s sidecar connects to the repository. Example: 1521
8. Click Save .

Repository users represent database credentials. Registered repository users enable you to configure impersonation policies , which allow authenticated data consumers to securely connect to repositories using single sign-on. ALTR’s sidecar also uses information in registered repository users to locate and obtain underlying database credentials.

Required Information

• Database credential Username. This the database username, not the secrets source object name. Example: admin_user
• If using AWS, you’ll need the Secret ARN Example: arn:aws:secretsmanager:us-east-2:111111111111:secret:username-KkAAcC
• If using Azure, you’ll need
  • Secret ARN Example: prod-user-admin
  • Vault URI Example: https://123sidecar456.vaultazure.net/

To register the database credentials as a repository user:

1. Log into ALTR via Okta.
2. Select Data ConfigurationData Sources in the Navigation menu.
3. Select Repositories from the Type dropdown.
4. Click the repository.
5. Click the Users tab.
6. Click Register Repository User .
7. Enter the repository username in Username . This is the username for the relevant database credential.
8. Select the Secret Source . Options are:

• AWS Secrets Manager
• Azure Key Vault

1. Populate applicable fields. These are copied directly from the secret source:
   1. AWS Secrets Manager: Enter the Amazon Resource Name (ARN)
   2. Azure Key Vault: Enter the Secret Name and the Vault URI
2. Click Register User .

Danger

Installed sidecars

• using AWS Secrets Manager must have IAM access to the AWS secrets.
• using Azure Key Vault must have identity available to it, can authenticate to the key vault and have access to the secret. Contact ALTR Support if you need assistance.

Sidecars use key-pair authentication to authenticate to ALTR’s SaaS control plane. Learn more about ALTR’s RSA key requirements.

To generate an RSA key pair:

1. Sign into the server.

2. Generate an RSA key pair. Use the following example console commands to generate an RSA key pair and access the public key:

   openssl genpkey -out private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
   openssl rsa -in private.pem -pubout -out public.pem
   less public.pem

3. Record the public key value for later. Example:

   -----BEGIN PUBLIC KEY-----
   pUbLic12...Key34
   -----END PUBLIC KEY-----

4. Record the private key location for later.

Registering the sidecar in ALTR generates the necessary information for a sidecar to connect to ALTR’s SaaS control plane.

Required Information

• Sidecar server hostname
• RSA public key

To register a sidecar in ALTR:

1. Log into ALTR via Okta.
2. Select SettingsSidecars in the Navigation menu.
3. Click Register Sidecar .
4. Enter a Display Name . This is a user-friendly name to identify your sidecar.
5. Enter Hostname of the sidecar in RFC 1123 specification, which is a URL without http:// . This is the DNS name of the network load balancer.
6. Enter Public Key of the sidecar. This is the public key from your RSA private-public key pair.
7. (Optional) Expand Advanced Settings and enable Allow unsupported queries if you want queries that can’t be parsed to run instead of fail, which may result in unauthorized data access. This setting applies only to access management policies, not impersonation policies.
8. Click Register . If Allow unsupported queries is enabled, a modal displays to confirm.
9. Note the Sidecar ID , the Data Plane URL and the ALTR Organization ID for later. These are used to install the sidecar to your environment. Once a sidecar is registered, ALTR displays information for all instances of that sidecar that have connected to ALTR. A single configured sidecar can have multiple installed instances.

When installing the ALTR sidecar, the default configuration chain is used, regardless if you’re using AWS Secrets Manager or Azure Key Vault.

Install the sidecar on your server to run the sidecar software.

Required Information

• Sidecar Image URI. The latest image can be found on ALTR’s Amazon Elastic Container Registry
• RSA private key location
• Sidecar ID
• ALTR Organization ID (also referred to as the Client ID )
• If using AWS Secrets Manager, AWS Region for stored secrets
• Open port number on the sidecar server

To install the ALTR sidecar:

1. Launch an instance of the ALTR sidecar on the server.
   1. Option 1: Docker (recommended)
   2. Option 2: RPM package
2. Confirm that the sidecar is running and the specified port is open.

Register sidecar listener ports in ALTR so that data consumers can connect to the sidecar.

Required Information

• Sidecar listener port number Example: 1521
• Database version Example: 19c

To register a listener port for a sidecar:

1. Log into ALTR via Okta.
2. Select SettingsSidecars in the Navigation menu.
3. Select the sidecar.
4. Click the Listener Ports tab.
5. Click Register Port .
6. Enter an open Port Number of the sidecar.
7. Select the Database Type that will be associated with this port.
8. Enter the Database Version that will be associated with this port.
9. Click Register Port .

The sidecar server will present over the specified port as the indicated database version. For installments where a sidecar is only connecting to one repository, ALTR recommends this be repository’s underlying database version.

Binding a sidecar port to a repository instructs sidecars on how to forward connections from data consumers to repositories.

To bind the sidecar listener ports to the repository:

1. Log into ALTR via Okta.
2. Verify you have one repository registered to ALTR and at least one sidecar port registered with the same database version as the repository before creating a binding.
3. Select SettingsSidecars in the Navigation menu.
4. Click the sidecar to view details.
5. Click the Bindings tab.
6. Click Create Binding .
7. Select a Sidecar Listener Port .
8. Select a Repository .
9. Click Create Binding .

Impersonation policies allow data consumers to impersonate repository users when connecting to the repository through ALTR’s sidecar.

Required Information

• Repository name for the repository whose user is being impersonated. This is the repository name you set in ALTR. Example: repository_name
• IdP username or group name to be granted impersonation. Example: username@company.com
• Repository user username to be impersonated. Example: admin_user

To create an impersonation policy:

1. Log into ALTR via Okta.
2. Click Policy in the Navigation menu.
3. Click Create Policy .
4. Locate the Impersonation Policy card.
5. Click Create Policy .
6. Locate the card for your database.
7. Click Create Policy .
8. Enter a Display Name . This is a user-friendly name to identify the policy.
9. Select a Data Source . This is the repository name as it appears in your database.
10. Click Next .
11. Define the rule statement by selecting the following options:
12. a user or group and entering the Name . This is either an individual user or a group, such as Marketing team, as configured in Okta.
13. a Repository User that the IdP user/group will impersonate.
14. (Optional) Expand IdP User/Group to add additional user/groups to the rule statement.
15. Click Save .

Note the IdP user (or user in IdP group who was granted access).

Data consumers can access repositories by signing into ALTR using single sign-on (SSO) and obtaining temporary connection information for an installed sidecar. The sidecar uses this connection information, and any configured security policies, to forward connections to relevant repositories using registered repository user credentials.

To connect to the repository using impersonation:

1. Sign into ALTR as data consumer who was granted impersonation access to a repository.
2. Click New Access Token .
3. Specify an expiration time for the access token. Users must connect to the repository before this token is expired.
4. Click Generate Token .
5. Record the token for later.
6. Identify and expand the drawer for the repository to be accessed.
7. Click the Users tab.
8. Expand the selection for the relevant repository user.
9. Record the Username .
10. Record the Sidecar Hostname .
11. Record the Sidecar Listener Port .
12. Open a SQL Client.
13. Generate a new database connection in the SQL client.
14. Instead of the database hostname, provide the sidecar hostname obtained in ALTR.
15. Instead of the database port, provide the sidecar listener port obtained in ALTR.
16. Instead of the database username, provide the username obtained in ALTR.
17. Instead of the database password, provide the access token.
18. Connect to the database (through the sidecar).