Troubleshoot Single Sign-On in SwaggerHub On-Premise

This information applies to SwaggerHub On-Premise. For SwaggerHub SaaS, click here.

When troubleshooting single sign-on (SSO) login errors, also check the log file named swaggerhub.json for additional diagnostic information.

Common issues

A new user is created even though the user already exists

This happens if the user’s email address in the identity provider (IdP) does not match the email address stored in SwaggerHub. In this case, SwaggerHub cannot associate the SSO login with the existing user and creates a new user instead. Please contact SmartBear Support to resolve the issue.

Okta and SAML

Incomplete response received from application

This error can occur in the following cases:

A new SSO user logs in using an email address containing + or other unsupported characters. Please refer to Username and email considerations for the supported characters in email addresses.
(In versions prior to 1.20.1) The SSO login email matches an existing internal user (for example, admin) but this user has not been migrated to SSO. To learn how to migrate the users, see Migrating Existing Users to Single Sign-On.

Email attribute missing from SAML profile

The SAML response from your IdP does not contain the email attribute. Review your IdP configuration and make sure this attribute is included in the SAML response. If your IdP uses another name for the email attribute, configure the attribute mappings to send this attribute as email.

Here is an example of the email attribute expected in an IdP’s SAML response:

...
<saml2:Assertion
    <saml2:AttributeStatement>
        <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">[email protected]</saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
    ...
</saml2:Assertion>
...

Note

In SwaggerHub On-Premise v. 1.19.1 and later, the system expects the email in any letter case: email, Email and so on. Earlier versions of SwaggerHub On-Premise expect email in lowercase.

Unable to extract username from email attribute

The email attribute in the SAML response from your IdP does not contain a valid email address. Review your IdP configuration and make sure the email attribute is mapped to the email address of the authenticating user.

Cannot POST /login/callback

This error can occur in SwaggerHub On-Premise versions prior to 1.18.8 in the following cases:

The SAML response from the identity provider (IdP) is missing the email attribute. Review the IdP configuration and make sure this attribute is included. The attribute name must be email in lowercase. If your IdP uses a different letter case or name for the email attribute, configure the attribute mappings to send this attribute as email.
The email attribute does not contain a valid email address. Review your IdP configuration and make sure the email attribute is correctly mapped to the email address of the authenticating user.

We recommend that you upgrade your SwaggerHub On-Premise instance to the latest version, which does not have this issue.

LDAP and Active Directory

Incorrect LDAP authentication settings can result in the following error messages at user login.

Invalid user name or password

This usually means that the Profile name option (or LDAP Username Field in earlier versions) is misspelled or specifies a non-existent field.

Self-signed certificate in certificate chain

This means your LDAPS server is using a self-signed certificate, or a certificate signed by a private CA. You need to upload your trusted root certificate to SwaggerHub so that it trusts this certificate. See the instructions here.

After you have configured the trusted certificates, click Test LDAP to verify the connection.

Precondition failed

This error can happen in versions prior to 1.20.1, and it means that a user with this email already exists but was not migrated to single sign-on. Please run the maintenance script to migrate the users, and then ask the user to try again.

Alternatively, upgrade your SwaggerHub On-Premise instance to the latest version, which does not have this issue.