If you're having trouble getting a SAML connector to work with Teleport usually the issue will come down to one of the following:

1. Improper YAML format in the connector config file

2. Improper attributes configuration in the connector config file

3. Improper mapping of returned values in the role config file

Improper YAML Format

Error message(s) to look for:

Error while processing SAML callback

Steps to troubleshoot:

First start by making sure that your environment is set up for debugging by following the steps outlined in the "How to debug Teleport" guide.

Next, grab a clean SAML connector template either from our docs or your proxy by navigating to the proxy WebUI address > Team > Auth Connectors and clicking New Auth Connector > SAML Connector.

Lastly, fill out the config carefully with appropriate values, making sure to copy and paste the Entity Descriptor portion portion line-by-line to preserve the default format. This can be a bit tedious, especially when it comes to copying the actual x509 cert line by line, but it will ensure that the expected YAML standard format is preserved.

Improper Scope Configuration

Error message(s) to look for:

Unable to process callback

Steps to troubleshoot:

Assuming you're already set up to debug and troubleshoot and you've ruled out YAML formatting issues, the next thing to look at will be the attributes configuration on the connector file.

Start by reviewing the attributes-to-roles portion of the config, paying careful attention to the values string and the roles list. The most common issue seen with improper attribute definitions is mismatched cases in the expected values (lowercase/uppercase mismatch between Teleport definition and what's configured in the idP), or mismatched cases between declared role and actual role in teleport. 

You will also want to confirm that your idP is passing back the expected attributes by confirming the received values in the Teleport logs.

For this you will want to have the Teleport logs on the auth server running in debug mode. Start by either dumping the logs directly to terminal or tailing a log file (depending on which option you've opted for in your log config) and grep for 'user.login'.

As you're watching the logs with the above setup attempt to log in via the connector. You should immediately see a series of logs detailing the exact attributes being passed back by the SAML connector. 

The key here will be to review the attributes and make sure that the keys you've specified in your connector config are being presented to Teleport by your idP.

For example: if you've configured your connector's attributes-to-roles name parameter as "groups," you will want to make sure that there is in fact an attribute in the returned attributes map called "groups." 

Improper Role Mapping

Error message(s) to look for:

Unable to process callback

Steps to troubleshoot:

If you've ruled out YAML formatting and confirmed that the configured values in the idP match the values configured in the Teleport connector, the next thing to check will be the Teleport role mapping.

Here you will want to confirm that the attribute you want to map is specified in your Teleport role file in the logins section. 

For example: if your idP is passing back a user email as an attribute and you're mapping this in your connector, then you will want to have the following in your role config login section:  '{{email.local(external.email)}}' This will take the external e-mail (external.email) and strip off everything after and including the @ symbol, leaving just the user name.

If you've gone through all of the steps above but still having issues, please reach out to our support team and we will be happy to assist!