Skip to main content

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.

Important

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

  • Oracle

  • Microsoft SQL Server

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

1. Create Secret Source Objects

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.

      Example: th1sIsaP@ssword

    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.

      Example: prod-user-admin

    2. Enter a plaintext Secret value, which is the password for the secret name.

      Example: th1sIsaP@ssword

    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

2. Grant the Sidecar Server Access Management Privileges to Secrets

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

AWS Secrets Manager

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

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 Security → Identity in the Navigation menu.

  4. Under System assigned, select On for Status.

  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.

3. Register the Database as a Repository

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

4. Register Database Credentials as a Repository User

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:

5. Generate an RSA Key Pair

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.

6. Register the Sidecar in ALTR

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

7. Install the Sidecar

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. The following is a Docker command for reference. Replace each environment variable with the required information. Ensure that the private key is properly mounted to the sidecar container.

    AWS Secrets Manager

    docker run -e  
  -e "SIDECAR_DATAPLANE_BASE_URL=[DATA_PLANE_URL]" \  
  -e "SIDECAR_ID=[SIDECAR_ID]" \  
  -e "SIDECAR_ORG_ID=[CLIENT_ID]" \
  -e "AWS_DEFAULT_REGION=[AWS_REGION]" \  
  -e "AWS_REGION=[AWS_REGION]" \  
  -v [FULL_KEY_FILE_PATH]:/app/private.pem \  
  -p [PORT_NUMBER] -d \ 
  [IMAGE_URI]

    Azure Key Vault

    docker run -e  
  -e "SIDECAR_DATAPLANE_BASE_URL=[DATA_PLANE_URL]" \  
  -e "SIDECAR_ID=[SIDECAR_ID]" \  
  -e "SIDECAR_ORG_ID=[CLIENT_ID]" \  
  -v [FULL_KEY_FILE_PATH]:/app/private.pem \  
  -p [PORT_NUMBER] -d \  
  [IMAGE_URI] 

  2. Confirm that the sidecar is running and the specified port is open.

8. Register Sidecar Listener Ports

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

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.

9. Bind Sidecar Listener Ports to the Repository

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

10. Define an Impersonation Policy

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

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

11. Connect to the Repository Using Impersonation

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.

    1. Instead of the database hostname, provide the sidecar hostname obtained in ALTR.

    2. Instead of the database port, provide the sidecar listener port obtained in ALTR.

    3. Instead of the database username, provide the username obtained in ALTR.

    4. Instead of the database password, provide the access token.

    5. Connect to the database (through the sidecar).

In this section: