Login Rules (Preview)
Login Rules are currently in Preview mode.
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 available starting
Some use cases for Login Rules are:
- When you need to modify a user trait based on logical rules, like
"users in group
db-adminsshould 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
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.
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.
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 and traits used for role mapping, the role mapping may 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.