
Teleport
Database Access with Azure Cache for Redis
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
Teleport can provide secure access to Azure Cache for Redis via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.
In this guide, you will:
- Configure an Azure Cache for Redis with IAM authentication.
- Join the Azure Cache for Redis database to your Teleport cluster.
- Connect to the Azure Cache for Redis database via the Teleport Database Service.
Please use the latest version of Teleport Enterprise documentation.
Prerequisites
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
- Deployed Azure Redis server or Azure Redis Enterprise cluster.
- Azure administrative privileges to manage service principals and access controls.
- A host, e.g., an Azure VM instance, where you will run the Teleport Database Service.
redis-cli
version6.2
or newer installed and added to your system'sPATH
environment variable.- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/5. Create a Teleport user
To modify an existing user to provide access to the Database Service, see Database Access Access Controls
Create a local Teleport user with the built-in access
role:
tctl users add \ --roles=access \ --db-users=\* \ --db-names=\* \ alice
Create a local Teleport user with the built-in access
and requester
roles:
tctl users add \ --roles=access,requester \ --db-users=\* \ --db-names=\* \ alice
Flag | Description |
---|---|
--roles | List of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport. |
--db-users | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user. |
--db-names | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. |
Database names are only enforced for PostgreSQL and MongoDB databases.
For more detailed information about database access controls and how to restrict access see RBAC documentation.
Step 2/5. Create a Database Service configuration
Install Teleport on the host where you will run the Teleport Database Service:
Select an edition, then follow the instructions for that edition to install Teleport.
Teleport Edition
- Teleport Team
- Open Source
- Enterprise
- Enterprise Cloud
curl https://goteleport.com/static/install.sh | bash -s 13.3.9
Before installing a teleport
binary with a version besides
v13, read our compatibility rules to ensure that the
binary is compatible with Teleport Cloud.
When running multiple teleport
binaries within a cluster, the following rules
apply:
- Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
- Servers support clients that are 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first. - Proxy Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
curl https://goteleport.com/static/install.sh | bash -s 14.0.0
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo apt-get install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo dnf install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo zypper install teleport-ent-fips
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Please use the latest version of Teleport Enterprise documentation.
Create the Database Service configuration, specifying a region like this:
sudo teleport db configure create \ -o file \ --proxy=tele.example.com:443 \ --token=/tmp/token \ --azure-redis-discovery=eastus
Please use the latest version of Teleport Enterprise documentation.
The command will generate a Database Service configuration with Azure Cache for
Redis auto-discovery enabled in the eastus
region and place it at the
/etc/teleport.yaml
location.
Use --azure-redis-discovery=*
to discover databases in all regions. In
addition to the region, you can optionally specify
--azure-resource-group=<resource-group-name>
,
--azure-subscription=<subscription-id>
, or --labels=<key>=<value>
to
further customize the scopes of the auto-discovery.
Step 3/5. Configure IAM permissions for Teleport
The Teleport Database Service needs Azure IAM permissions to:
- Discover and register Azure Cache for Redis databases.
- Retrieve Redis access keys to authenticate with the databases.
Configure an Azure service principal
There are a couple of ways for the Teleport Database Service to access Azure resources:
- The Database Service can run on an Azure VM with attached managed identity. This is the recommended way of deploying the Database Service in production since it eliminates the need to manage Azure credentials.
- The Database Service can be registered as an Azure AD application (via AD's "App registrations") and configured with its credentials. This is only recommended for development and testing purposes since it requires Azure credentials to be present in the Database Service's environment.
Go to the Managed Identities page in your Azure portal and click Create to create a new user-assigned managed identity:

Pick a name and resource group for the new identity and create it:
Take note of the created identity's Client ID:
Next, navigate to the Azure VM that will run your Database Service instance and add the identity you've just created to it:

Attach this identity to all Azure VMs that will be running the Database Service.
Registering the Database Service as Azure AD application is suitable for test and development scenarios, or if your Database Service does not run on an Azure VM. For production scenarios prefer to use the managed identity approach.
Go the the App registrations page of your Azure Active Directory and click on New registration:

Pick a name (e.g. DatabaseService) and register a new application. Once the app has been created, take note of its Application (client) ID and click on Add a certificate or secret:
Create a new client secret that the Database Service agent will use to authenticate with the Azure API:

The Teleport Database Service uses Azure SDK's default credential provider chain to look for credentials. Refer to Azure SDK Authorization to pick a method suitable for your use-case. For example, to use environment-based authentication with a client secret, the Database Service should have the following environment variables set:
export AZURE_TENANT_ID=export AZURE_CLIENT_ID=export AZURE_CLIENT_SECRET=
Create a custom role
Teleport requires <resource-type>/read
permissions for discovery and
<resource-type>/listKeys/action
permissions for authentication with the
Redis servers, but Teleport only needs permissions for the resource types
you have.
Here is a sample role definition allowing Teleport to read and list keys for both Azure Redis and Azure Redis Enterprise:
{
"properties": {
"roleName": "TeleportDiscovery",
"description": "Allows Teleport to discover Azure Cache For Redis databases and list keys",
"assignableScopes": [
"/subscriptions/11111111-2222-3333-4444-555555555555"
],
"permissions": [
{
"actions": [
"Microsoft.Cache/redis/read",
"Microsoft.Cache/redis/listKeys/action",
"Microsoft.Cache/redisEnterprise/read",
"Microsoft.Cache/redisEnterprise/databases/read",
"Microsoft.Cache/redisEnterprise/databases/listKeys/action"
],
"notActions": [],
"dataActions": [],
"notDataActions": []
}
]
}
}
The assignableScopes
field above includes a subscription
/subscriptions/<subscription>
, allowing the role to be assigned at any
resource scope within that subscription or the subscription scope itself. If
you want to further limit the assignableScopes
, you can use a resource group
/subscriptions/<subscription>/resourceGroups/<group>
or a management group
/providers/Microsoft.Management/managementGroups/<group>
instead.
Now go to the Subscriptions page and select a subscription.
Click on Access control (IAM) in the subscription and select Add > Add custom role:

In the custom role creation page, click the JSON tab and click Edit, then paste the JSON example
and replace the subscription in assignableScopes
with your own subscription id:
Create a role assignment for the Teleport Database Service principal
To grant Teleport permissions, the custom role you created must be assigned to the Teleport service principal - either the managed identity or the app registration you created earlier.
Navigate to the resource scope where you want to make the role assignment. Click Access control (IAM) and select Add > Add role assignment. Choose the custom role you created as the role and the Teleport service principal as a member.

The role assignment should be at a high enough scope to allow the Teleport Database Service to discover all matching databases. See Identify the needed scope for more information about Azure scopes and creating role assignments.
Step 4/5. Start the Database Service
Configure the Teleport Database Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Database Service.
On the host where you will run the Teleport Database Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run the Teleport Database Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleport
You can check the status of the Teleport Database Service with systemctl status teleport
and view its logs with journalctl -fu teleport
.
Step 5/5. Connect
Log in to your Teleport cluster. Your Azure Cache for Redis databases should appear in the list of available databases:
tsh login --proxy=teleport.example.com --user=alicetsh db lsName Description Allowed Users Labels Connect ------------------------- ---------------------------------------- ------------- ------- ------- my-azure-redis Azure Redis server in East US [*] ...my-azure-redis-enterprise Azure Redis Enterprise server in East US [*] ...
Please use the latest version of Teleport Enterprise documentation.
By default, Teleport uses the name of the Azure Cache for Redis resource as the
database name. You can override the database name by applying the
TeleportDatabaseName
Azure tag to the resource. The value of the tag will be
used as the database name.
To retrieve credentials for a database and connect to it:
tsh db connect my-azure-redis
Note that the Teleport Database Service will retrieve the access key and
authenticate with the Redis server on the backend automatically. Therefore,
the AUTH <access-key>
command is not required here once connected.
To log out of the database and remove credentials:
tsh db logout my-azure-redis
Troubleshooting
No credential providers error
If you see the error DefaultAzureCredential: failed to acquire a token.
in Database Service logs then Teleport
is not detecting the required credentials to connect to the Azure SDK. Check whether
the credentials have been applied in the machine running the Teleport Database Service and restart
the Teleport Database Service.
Refer to Azure SDK Authorization
for more information.
Timeout errors
The Teleport Database Service needs connectivity to your database endpoints. That may require
enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the nc
program you can verify connections to databases:
nc -zv server-name.postgres.database.azure.com 5432Connection to server-name.postgres.database.azure.com 5432 port [tcp/postgresql] succeeded!
Next steps
- Learn how to restrict access to certain users and databases.
- Learn more about dynamic database registration.
- View the High Availability (HA) guide.
- See the YAML configuration reference for updating dynamic resource matchers or static database definitions.
- Take a look at the full CLI reference.