> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # Teleport > Connect your Teleport cluster to Oleria to discover users, roles, access lists, Machine ID bots, join tokens, and audit events, and take remediation actions directly from Oleria. Connect Teleport to Oleria to see who can access your infrastructure through Teleport, which roles and access lists grant that access, and which bots and join tokens can act on the cluster. Oleria reads identity, access, and audit data from the Teleport API as a Machine ID bot. You can then review over-provisioned access and take action directly from Oleria. One Oleria connection maps one Teleport cluster. Teleport Enterprise Cloud and self-hosted Teleport clusters running version 18 or later are supported. To connect another cluster, add another integration. > [!NOTE] > > For a self-hosted cluster, Oleria must be able to reach your proxy address. Contact [support@oleria.com](mailto:support@oleria.com) to allow the address before you connect. Teleport Enterprise Cloud (`*.teleport.sh`) needs no action. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your Teleport cluster: * **Users** - every local user, and every SSO user that currently has a session, with their roles. A user is shown as disabled while a Teleport lock targets them or one of their roles, or after their account expires. A lock that only blocks one login, device, or desktop is shown in the user's details instead. Oleria also shows: * whether the user has set a password, and when a pending invitation expires * their SSO connector, for users created by a SAML, OIDC, or GitHub connector * MFA status, from the cluster's second factor setting. When the cluster requires a second factor, Teleport is the MFA authority and MFA is shown as enabled; a user with no MFA device enrolled is shown as enrollment required. When the second factor is optional or off, MFA is shown as not required. For SSO users without a Teleport MFA device, MFA is handled by the identity provider. * administrators: users who hold a role that can create or update users or roles * who created the user, and when * their last sign-in and last password change, from the audit log of the last 30 days * the users they can impersonate, from the `impersonate` rules of their roles. Machine ID bots are checked the same way. Rules with a `where` condition aren't counted. * **Groups** - each **access list** is shown as a group, with its user members, its nested access lists, and the access list owners. Membership expiry dates are shown on the membership. * **Roles** - every Teleport role, marked as preset, system, or custom. Oleria shows the roles assigned directly to users and bots, and the roles each access list grants to its members. * **Non-human identities (NHIs)**: * **Service accounts** - Machine ID bots, with their roles, who created them, and when they last authenticated. * **API tokens** - join tokens that use the `token` join method. Oleria never shows the token value: the name is masked the same way Teleport masks it. * **SSH keys** - join tokens that use the `bound_keypair` join method, with the fingerprint of the registered public key. * **Federated credentials** - join tokens that use a cloud or CI identity, such as `iam`, `github`, or `kubernetes`. * **System** - Teleport's own system users, such as `@teleport-access-approval-bot`, and the join tokens Teleport uses for its own infrastructure. Each join token is also shown as a credential with its expiry date, linked to the bot it lets join. When Teleport records it, Oleria also shows when the token was last used to join. * **Activity** - events from the Teleport audit log, such as: * sign-ins and failed sign-ins, including the MFA device used and the client IP address * bot joins * SSH, application, and database session starts * user, role, bot, and access list changes * access list membership changes, access requests, and access request reviews * locks created and removed * join token creation, password changes and resets, and MFA enrollments * changes to the cluster's authentication settings Oleria leaves out the join and certificate events of the bot this integration connects as. Changes that bot makes, including remediation actions, are shown. Nodes, applications, databases, Kubernetes clusters, and desktops enrolled in Teleport aren't discovered. ## Prerequisites * A Teleport Enterprise Cloud tenant or a self-hosted Teleport cluster running version 18 or later. * A Teleport user who can create roles, bots, and join tokens, with `tctl` and `tbot` installed. * Admin access on the Oleria platform to add a new integration. ### Permissions Oleria connects as a Machine ID bot and reads with the roles you grant the bot. Grant a role with these rules, all with the `list` and `read` verbs: `user`, `role`, `access_list`, `bot`, `bot_instance`, `token`, `lock`, `event`, and `cluster_auth_preference`. Without `read` on `cluster_auth_preference`, Oleria shows users' MFA status as unavailable. Remediation actions need more rules. See [Remediation actions](#remediation-actions) for the rules each action needs. > [!NOTE] > > Use a dedicated bot for this integration rather than a person's account. Oleria never disables the bot it connects as, or deletes that bot's join token. ## Create a bot in Teleport **1. Create a key pair** Run `tbot keypair create --proxy-server :443 --static`. The command prints a public key, and a private key value to use in Oleria. Keep the private key value secret. **2. Create the role, bot, and join token** Save the following as `oleria.yaml`, replace the public key with the one from the previous step, and run `tctl create -f oleria.yaml`: ```yaml theme={null} kind: role version: v8 metadata: name: oleria-reader spec: allow: rules: - resources: [user, role, access_list, bot, bot_instance, token, lock, event, cluster_auth_preference] verbs: [list, read] --- kind: bot version: v1 metadata: name: oleria spec: roles: [oleria-reader] --- kind: token version: v2 metadata: name: oleria-bkp spec: bot_name: oleria join_method: bound_keypair roles: [Bot] bound_keypair: onboarding: initial_public_key: ssh-ed25519 AAAA... recovery: limit: 0 mode: insecure ``` The token uses a static key, so it needs the `insecure` recovery mode. Don't set `rotate_after` on it. **3. Optional: allow remediation** To take remediation actions from Oleria, add a second role with the rules from [Remediation actions](#remediation-actions) to the bot's `roles`. > [!NOTE] > > Teleport changes over time. If these steps don't match your cluster, refer to Teleport's guide on [bound keypair static keys](https://goteleport.com/docs/reference/machine-workload-identity/bound-keypair/static-keys/). ## Connect Teleport to Oleria **1. Open the integration** Sign in to your Oleria workspace, navigate to **Integrations**, and select **Teleport**. **2. Complete the connection form** | Field | Notes | | :- | :- | | Proxy address | Required. The address of your Teleport proxy, for example `example.teleport.sh:443`. If you leave out the port, Oleria uses 443. Addresses that resolve to private or loopback IP addresses are refused. | | Join token name | Required. The name of the `bound_keypair` join token, for example `oleria-bkp`. | | Bot private key | Required. The private key value printed by `tbot keypair create --static`, or the private key in PEM format. | **3. Authenticate** Select **Authenticate**. Oleria joins your cluster as the bot, lists one user, and checks that the bot's roles allow `list` and `read` on `user`, `role`, and `lock`. If any of these steps fails, the connection fails with the reason. ### Edit the connection You can change the join token name and private key of an existing connection. Leave the private key blank to keep the stored value. The proxy address can't be changed; to connect a different cluster, add a new integration. ## Verify the integration Confirm the Teleport cluster appears on the **Connected** tab of your Oleria **Integrations** page. The connection is named after your Teleport cluster. After the first sync completes, review the discovered users, access lists, roles, NHIs, and activity in your Oleria workspace. ## Remediation actions Oleria runs actions as the same bot. Each action is available only when the bot's roles allow the rules it needs. | Action | What it does | Revert | | :- | :- | :- | | Disable user accounts | Creates a Teleport lock that targets the user. If Oleria can't confirm the lock right after creating it, the action fails and can't be reverted, and running it again makes no change. Remove the lock with **Enable user accounts**, or in Teleport. | Supported - removes the lock the action created. | | Enable user accounts | Removes the locks that target only the user. Locks that only block one login, device, or desktop are kept. If removing a lock fails partway, the locks already removed stay removed and the action can't be reverted. Run **Enable user accounts** again to remove the remaining locks, or lock the user again in Teleport to keep them disabled. | Supported - creates the removed locks again, with their message and expiry. | | Add user to group | Adds the user as a member of the access list. An expired membership is renewed without an expiry. | Supported - removes the membership the action added, or restores the renewed membership's previous expiry. | | Remove user from group | Removes the user from the access list. | Supported - adds the user back, with the previous expiry and reason. | | Add user to role | Adds the role to the user's roles. | Supported - removes the role again. | | Remove user from role | Removes the role from the user's roles. | Supported - adds the role back. | | Disable NHI accounts - Machine ID bot | Creates a Teleport lock that targets the bot. If Oleria can't confirm the lock right after creating it, the action fails and can't be reverted. Delete the lock in Teleport. | Supported - removes the lock the action created. | | Disable NHI accounts - join token | For a bot's join token, creates a Teleport lock that targets the bot and keeps the token. If Oleria can't confirm that lock right after creating it, the action fails and can't be reverted; delete the lock in Teleport. For any other join token, permanently deletes the token. | Supported for a bot's join token - removes the lock the action created. Not supported for other join tokens. | | Delete user | Permanently deletes a local user. | Not supported - the user's password and MFA devices can't be restored. | | Revoke user sessions | Deletes the user's Web UI and application sessions. | Not supported - the user signs in again to start a new session. | Each action needs these role rules: | Action | Required rules | | :- | :- | | Disable user accounts, Enable user accounts | `user:read`, `lock:list`, `lock:read`, `lock:create`, `lock:update`, `lock:delete` | | Add user to group, Remove user from group | `user:read`, `access_list:list`, `access_list:read`, `access_list:update` | | Add user to role, Remove user from role | `user:read`, `user:update`, `role:read` | | Disable NHI accounts - Machine ID bot | `user:read`, `lock:list`, `lock:read`, `lock:create`, `lock:update`, `lock:delete` | | Disable NHI accounts - join token | `token:list`, `token:read`, `token:delete`, `user:read`, `lock:list`, `lock:read`, `lock:create`, `lock:update`, `lock:delete` | | Delete user | `user:read`, `user:delete` | | Revoke user sessions | `user:read`, `web_session:list`, `web_session:read`, `web_session:delete` | The bot also needs `read` on `role` to check its own permissions. > [!WARNING] > > Deleting a join token is permanent, and it only stops new joins: anything that already joined with it, such as a node, keeps its certificates. Nothing can join with the token again until you create a new one. Oleria refuses these actions and sends no change to Teleport: * Disabling the bot this integration connects as, or deleting its join token. * Disabling, deleting, or revoking the sessions of a Machine ID bot with a user action. Use **Disable NHI accounts** instead. * Changing the roles of a Machine ID bot. Bot roles are managed on the bot. * Changing the roles of an SSO user. The SSO connector sets their roles at every sign-in, so change the connector's role mapping instead. * Deleting an SSO user. The SSO connector creates the user again at every sign-in, so remove the person in your identity provider instead. * Disabling, deleting, or changing the roles of Teleport's system users, or revoking their sessions. * Removing the bot this integration connects as from an access list. * Enabling a user who is blocked by a lock on one of their roles, because that lock also blocks everyone else with the role. Remove the role lock in Teleport instead. * Deleting the join tokens Teleport uses for its own proxy and auth services. * Changing members of an access list that's managed by SCIM. Keep these points in mind: * If the user is already in the requested state, or a user to delete no longer exists, the action succeeds without making a change, and there's nothing to revert. * A lock blocks new sessions and certificates for the user or bot. It doesn't change their roles. * **Revoke user sessions** signs the user out of the Web UI and applications, but certificates already issued to `tsh` or `tbot` stay valid until they expire. To block those too, use **Disable user accounts**. ## Known limitations * **Last sign-in and password change look back 30 days.** Teleport doesn't store these dates on users, so Oleria reads them from the audit log of the last 30 days. Older ones are left empty. Sign-ins still appear as activity. * **Access lists need Teleport Enterprise.** On a cluster without access lists, such as Community Edition, Oleria discovers no groups, and the group actions aren't available. * **Teleport is the MFA authority for SSO users too.** When the cluster requires a second factor, Teleport is listed as the MFA authority for every user, including SSO users whose MFA is handled by their identity provider. * **Infrastructure resources aren't discovered.** Nodes, applications, databases, Kubernetes clusters, and desktops enrolled in Teleport aren't shown. * **Each sync creates a bot instance.** The bot joins your cluster at the start of each sync and action, so Teleport lists a new bot instance for each join. Bot instances expire on their own. * **SSO users without a session aren't listed.** Teleport creates SSO users when they sign in and removes them when their session expires, so Oleria only sees SSO users with a current session. Your identity provider integration remains the source for those people. * **Login lockouts aren't shown as disabled.** A user temporarily locked out after failed sign-ins is still shown as enabled, with the lockout end time in their profile details. * **Self-hosted clusters need allowlisting.** Oleria can connect to `*.teleport.sh` hosts. For a self-hosted proxy, contact [support@oleria.com](mailto:support@oleria.com) to add its host before you connect. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.