Document how to use external. notation with Azure AD and AD FS SAML attributes

[pschisa]

Applies To

https://goteleport.com/docs/access-controls/sso/azuread/?scope=enterprise
https://goteleport.com/docs/access-controls/sso/adfs/?scope=enterprise

Details

When using Azure AD or ADFS, the attribute names passed in are not simple strings but full URLs (example: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups). This does not play nicely with our standard examples for RBAC (https://goteleport.com/docs/access-controls/guides/role-templates/?scope=enterprise#sso-users) and other places where the typical external.attributename format is used. In order to use AD traits, you have to pass the full URL in with the following example syntax:

For logins fields where the quotes don't have to be escaped:
'{{external["http://schemas.microsoft.com/identity/claims/displayname"]}}'

for an x-forwarded app header where the double quotes must be escaped.
- "X-Forwarded-User: {{external[\"http://schemas.microsoft.com/identity/claims/displayname\"]}}"

My recommendation is to update the two SSO documents with example syntax help when using these attributes. Also update the examples within these SSO docs to use the correct syntax.

[pschisa]

Note that the ADFS does call out the non-escaped reference (not in the Azure AD guide though): https://goteleport.com/docs/access-controls/sso/adfs/?scope=enterprise#create-teleport-roles

[ptgott]

See #20269 for some more context and a screenshot with an Azure AD example.