Login Rules

When users log in to your Teleport cluster with a configured SSO provider, Login Rules can transform the traits provided by your IdP to meet your needs for configuring access within Teleport. Login Rules are a feature of Teleport Enterprise.

Some use cases for Login Rules are:

• When you need to modify a user trait based on logical rules, like "users in group db-admins should also be added to group db-users", Login Rules provide a powerful expression language to make these changes without needing to modify claims in your IdP.
• When your IdP provides a large number of traits with many values, all of these traits will be included in your user's SSH certificates and JWTs, which can become too large for some third-party applications to handle. Login Rules can filter out unnecessary traits and keep just the ones you need.
• When you have multiple Role Templates repeating the same logic to combine and transform external traits, consider using Login Rules to consolidate the logic to one place and simplify your Roles.

Login Rules can solve these problems without requiring changes to your organization's IdP.

Login Rules use a predicate language to provide maximum flexibility when configuring your cluster. This allows you to write simple or complex expressions to define the traits your users should be granted.

For example, you can convert the value of a username trait to lowercase and conditionally extend the value of a groups trait with the following snippet:

traits_map:
  username:
    - 'strings.lower(external.username)'
  groups:
    - 'ifelse(external.groups.contains("db-admins"), external.groups.add("db-users"), external.groups)'

Check out the Login Rules guide for a quick walkthrough that will show you how to write, test, and add the first Login Rule to your cluster. See example Login Rules to learn how to address common use cases.

When you're ready to take full advantage of Login Rules in your cluster, see the Login Rules Reference for details on the expression language that powers them.

FAQ

Which users do Login Rules apply to?

Login Rules apply to all users logging in via OIDC, SAML, or GitHub. They do not apply to local Teleport users.

When are Login Rules evaluated?

Login Rules are evaluated once during each user login, after receiving the claims or assertions from your IdP, before mapping claims/assertions to Teleport roles, and before generating user certificates. If Login Rules modify any traits used for role mapping, the role mapping will be affected.

Can I define custom helper functions for the predicate language?

No, but if you have a use case which is not adequately met by the currently supported helper functions, please talk to support or submit a GitHub issue and we will consider adding helpers which are generally useful.

Can I have multiple Login Rules in a single cluster?

Yes. All Login Rules installed in the cluster will first be sorted by priority and then evaluated in order. Each subsequent Login Rule will receive the full output of the previous rule as its input. It is strongly recommended to give each Login Rule a unique priority, but ties will be broken by sorting by the rule name.