IP Pinning

IP Pinning is a security feature that helps protect against unauthorized access by ensuring that Teleport users can only access resources from the IP address they used during the login process. This helps minimize the risk of compromised credentials being used from different locations.

How it works

When IP pinning is enabled for at least one of a user's roles, the IP address observed by Teleport during the login process will be embedded into the user's certificates. Later, whenever the user attempts to access Teleport resources, the system will compare the observed IP address with the pinned IP address stored in the certificate. If the IP addresses do not match, access will be denied.

If the user's role requires IP pinning, but the user's certificate that is presented to a Teleport service doesn't have pinned IP information embedded, access will be denied. This means that if you enable IP pinning for some role, any users that are already authenticated with that role will have to log in again in order to regenerate their certificates. A client's observed IP will be propagated internally between Teleport services if needed, so Teleport performs the IP pinning check against the correct IP.

IP pinning can work across trusted clusters, but be aware that if a user tries to access a leaf cluster's resources through the root cluster, and their mapped role on the leaf cluster has IP pinning enabled, they should also have IP pinning enabled on their root cluster roles. Otherwise, their certificates will not contain pinned IP information.

Configure IP Pinning

To enable IP pinning, update the role to contain pin_source_ip option:

kind: role
version: v7
metadata:
  name: example-role-with-ip-pinning
spec:
  options:
    # require IP pinning for this role
    pin_source_ip: true
  allow:
    ...
  deny:
    ...

Role example

Let's walk through an example of setting up IP pinning for a role.

A Teleport admin adds the following role, which enforces IP pinning for users:

# pinned-ip.yaml
kind: role
version: v7
metadata:
  name: pinned-ip
spec:
  options:
    pin_source_ip: true

The admin assigns this role to the user Alice, who then logs into Teleport using the 'tsh' command and tries to access a node from the same IP address she logged in with:

curl ifconfig.me

198.51.111.1

tsh ssh telenode.example.com

[email protected] >

As with Alice's usual attempts to access a node, this one is successful.

Later, Alice changes her IP address, and her attempt to access the same node will fail due to the IP address mismatch. This will trigger the relogin process, prompting Alice to authenticate again.

curl ifconfig.me

198.51.222.2

tsh ssh telenode.example.com

Enter password for Teleport user alice:

Observing IPs through load balancers

If your Teleport Proxy is behind a load balancer, there are a few steps you can take to ensure the correct IPs are observed.

For layer 4 load balancers such as AWS Network Load Balancer, enable either client IP preservation or PROXY protocol, if available.

For layer 7 load balancers such as AWS Application Load Balancer, ensure that the load balancer is configured to set client IPs in "X-Forwarded-For" headers. Then adjust the Proxy configuration by setting proxy_service.trust_x_forwarded_for to true and restart the service.