Docs: Teleport SAML IdP default attribute overwrite (#65159)

2026-09-24 16:17:11 +08:00 · 2026-04-24 09:42:32 +00:00
parent 57c60b6052
commit e76df81866
3 changed files with 122 additions and 0 deletions
@@ -184,6 +184,13 @@ Attribute mapping can be tested using `tctl idp saml test-attribute-mapping` com
 - `--sp`: name of file containing service provider spec with attribute mapping. Required.
 - `--format`: `yaml` or `json`.  Optional. Text output by default if the flag is not provided.

+<Admonition type="note">
+The `test-attribute-mapping` command evaluates attributes against a Teleport
+user resource, which does not include roles granted dynamically through Access
+Lists. Roles granted through Access Lists are resolved at login time and
+will appear in the actual SAML assertion, but not in the test output.
+</Admonition>
+
 E.g.:
 Test with user name and service provider spec file:
 ```code
@@ -207,3 +214,48 @@ Print result in format of choice.
 ```code
 $ tctl idp saml test-attribute-mapping --user user.yml --sp sp.yml --format (json/yaml)
 ```
+
+## Overwriting default attributes
+
+Teleport includes the following default attributes in every SAML assertion:
+
+| Friendly name          | Name                                | Description               |
+|------------------------|-------------------------------------|---------------------------|
+| `uid`                  | `urn:oid:0.9.2342.19200300.100.1.1` | The Teleport username     |
+| `eduPersonAffiliation` | `urn:oid:1.3.6.1.4.1.5923.1.1.1.1` | All Teleport roles        |
+
+When you define a custom attribute mapping with the same `name` as a default
+attribute, the custom mapping overwrites the default value. This is useful when
+a service provider imposes a size limit on SAML assertions. For example, AWS IAM
+Identity Center enforces a 50,000-character limit on SAML assertions, which
+users with a large number of Teleport roles can exceed.
+
+To overwrite the default `eduPersonAffiliation` attribute and include only
+a subset of roles, use the full attribute name (`urn:oid:1.3.6.1.4.1.5923.1.1.1.1`)
+in the mapping:
+
+```yaml
+kind: saml_idp_service_provider
+metadata:
+  name: example-sp
+spec:
+  entity_id: https://example.com/saml/metadata
+  acs_url: https://example.com/saml/acs
+  attribute_mapping:
+  - name: urn:oid:1.3.6.1.4.1.5923.1.1.1.1
+    value: regexp.replace(user.spec.roles, "^prefix-.*", "$0")
+    name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
+```
+
+In this example, only roles matching the `prefix-` prefix are included in the
+assertion instead of all Teleport roles. Replace `prefix-` with the actual
+prefix used by your roles.
+
+To omit all roles from the SAML assertion entirely, use an empty `set()`:
+
+```yaml
+  attribute_mapping:
+  - name: urn:oid:1.3.6.1.4.1.5923.1.1.1.1
+    value: set()
+    name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
+```
@@ -406,6 +406,70 @@ Provider and its role from your AWS IAM console as well.

 ## Troubleshooting

+### "It's not you, it's us" error during AWS SSO login
+
+When a Teleport user with a large number of roles logs in to AWS IAM Identity
+Center through the Teleport SAML IdP, AWS may display the following error:
+
+> **It's not you, it's us**
+>
+> We couldn't complete your request right now. Please try again later.
+
+This error occurs because AWS IAM Identity Center enforces a
+[50,000-character limit](https://aws.amazon.com/blogs/security/saml-identity-federation-follow-up-questions-materials-guides-and-templates-from-an-aws-reinvent-2016-workshop-sec306/)
+on SAML assertions. By default, Teleport includes all of a user's roles in the
+`eduPersonAffiliation` attribute of the SAML assertion. For users with a large
+number of roles (for example, more than 1,000), the assertion can exceed this
+limit.
+
+<Admonition type="note">
+Overwriting default SAML IdP attributes through attribute mapping is available
+starting from Teleport version 18.7.4. In earlier versions, the only workaround
+is to reduce the number of roles assigned to the user.
+</Admonition>
+
+To resolve this issue, use [SAML IdP attribute mapping](../../../identity-governance/idps/saml-attribute-mapping.mdx)
+to overwrite the default `eduPersonAffiliation` attribute
+(`urn:oid:1.3.6.1.4.1.5923.1.1.1.1`) and reduce the assertion size.
+
+Follow these steps to update the SAML IdP service provider resource:
+
+1. Retrieve the current service provider resource:
+
+   ```code
+   $ tctl get saml_idp_service_provider/aws-identity-center-sso > aws-ic-sp.yaml
+   ```
+
+2. Open `aws-ic-sp.yaml` in a text editor and add an `attribute_mapping` entry
+   to the `spec` section. Use `set()` to omit all roles from the assertion:
+
+   ```yaml
+   spec:
+     attribute_mapping:
+     - name: urn:oid:1.3.6.1.4.1.5923.1.1.1.1
+       value: set()
+       name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
+   ```
+
+3. Apply the updated resource:
+
+   ```code
+   $ tctl create -f aws-ic-sp.yaml
+   ```
+
+You can verify the attribute mapping before applying it by running:
+
+```code
+$ tctl idp saml test-attribute-mapping --user <username> --sp aws-ic-sp.yaml
+```
+
+<Admonition type="note">
+The `test-attribute-mapping` command evaluates attributes against the static
+user object, which does not include roles granted dynamically through Access
+Lists. Roles granted through Access Lists are resolved at login time and
+will appear in the actual SAML assertion, but not in the test output.
+</Admonition>
+
 ### Access forbidden during AWS account login

 This may happen if the user does not have access to the SAML IdP service provider 
@@ -102,6 +102,12 @@ The assertions currently provided by Teleport's SAML identity provider are liste
 | `uid`                  | `urn:oid:0.9.2342.19200300.100.1.1` | The user ID from Teleport | `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` |
 | `eduPersonAffiliation` | `urn:oid:1.3.6.1.4.1.5923.1.1.1.1`  | The user's Teleport roles | `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` |

+If a custom [attribute mapping](../../identity-governance/idps/saml-attribute-mapping.mdx)
+uses the same `name` as a default attribute, the custom mapping overwrites the
+default value. This allows you to filter or limit the values included in the
+assertion, which is useful when a service provider enforces a size limit on SAML
+assertions.
+
 ## RBAC

 Access to the SAML IdP service provider can be configured by using a Teleport role