SAML 2.0 Settings

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

SwaggerHub On-Premise supports single sign-on through the SAML 2.0 standard. This guide provides general configuration steps for SAML 2.0 identity providers (IdP).

Note: If you use Okta, see the Okta configuration guide instead.

Configure SAML authentication

  1. Open the Admin Center.

  2. Select Settings on the left.

  3. Under Authentication, change the Authentication Type to SAML.

  4. Specify your SAML settings:



    Authentication Type

    Change to SAML.

    SAML Identity Provider EntityID (Issuer)

    The unique identifier of your SAML identity provider, usually, a URL.

    SAML Identity Provider SSO URL

    The URL where SwaggerHub will redirect the users for logging in.

    SAML Identity Provider Certificate

    The X.509 signing certificate provided by your identity provider. When pasting the certificate contents, include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

    The following options define the authentication contexts in the SAML requests sent to the identity provider. Authentication contexts indicate the type of user authentication that SwaggerHub suggests to the identity provider. If no contexts are sent in the SAML request, the default mechanism set in the identity provider will be used.


    These options were added in v. 1.27.



    Send RequestAuthnContext in the SAML request

    Specifies whether to include the RequestAuthnContext element in SAML requests. By default, this element is included.

    If your identity provider expects SAML requests without authentication contexts, unselect this option. This may be needed when authenticating against Active Directory Federation Services (ADFS) servers.

    If this option is unselected, the next two options are ignored.

    AuthnContext values

    A comma-separated list of authentication contexts to include in SAML requests. The default value is urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport ("Password Protected Transport").

    This option is required if Send RequestAuthnContext in the SAML request is selected; otherwise, it is ignored.

    RequestedAuthnContext comparison type

    Possible values: exact (default), minimum, maximum, better. For a description of these values, see section " Element <RequestedAuthnContext>" of the SAML 2.0 core specification.

    This option is required if Send RequestAuthnContext in the SAML request is selected; otherwise, it is ignored.

  5. Click Save Changes and Restart.

    In v. 1.19.1 or earlier, click Save Changes, then switch to the System page and click Restart SwaggerHub.

  6. Wait a few minutes for the system to restart completely.

  7. If you use SwaggerHub On-Premise v. 1.20.0 or earlier, follow the instructions on this page to migrate the existing users to single sign-on.

Configure a connector in SAML IdP

To configure a SwaggerHub connector in your SAML identity provider, use the following values:

Option (Typical Name)


Protocol version

SAML 2.0

Assertion Consumer URL


Entity ID (of SwaggerHub)


Application URL


SAML Token Attributes, Attribute Mappings or similar

SwaggerHub expects a single attribute named email containing the user email address. Since SwaggerHub On-Premise v. 1.19.1, the attribute name is case-insensitive and can be email, Email, and so on. Previous versions expect email exactly.

NameID Format

Email address (format = urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

Protocol binding

POST (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST)

Single Logout Endpoint

Not supported, leave it blank.

Replace {swaggerhub-host} above with your SwaggerHub On-Premise host name. Use https:// if SSL access is enabled, otherwise use http://.

SAML metadata file

If your identity provider requires a metadata file from SwaggerHub to complete the configuration, use a file with the following contents. Replace YOUR-SWAGGERHUB-HOST with your SwaggerHub On-Premise DNS name.

<?xml version="1.0"?>



        index="0" />

    <!-- Requested Attributes for SwaggerHub OnPremise SP -->
    <md:AttributeConsumingService index="0" >

      <md:ServiceName xml:lang="en">SwaggerHub OnPremise</md:ServiceName>

          isRequired="true" />



SAML request

Below is an example of the SAML request (before encoding) that SwaggerHub sends to your IdP. The presence and contents of the RequestedAuthnContext element depends on the corresponding SAML options set in the Admin Center.

<?xml version="1.0"?>
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
        <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://your_swaggerhub_host/login/callback</saml:Issuer>
        <samlp:NameIDPolicy xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"

        <samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Comparison="exact">
                <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>


In instances created using SwaggerHub On-Premise 1.21.0 or earlier versions, the saml:Issuer value in requests may be the swaggerhub string instead of the URL http(s)://your_swaggerhub_host/login/callback. In this case, you may need to add this string to your identity provider’s Circle of Trust. If you need to change the saml:Issuer value to a URL, contact Support.

SAML response

SwaggerHub expects the following data in the SAML response from your identity provider:

  • A single attribute named email (case-insensitive in SwaggerHub On-Premise v. 1.19.1 and later, case-sensitive in earlier versions).

  • A NameIDclaim of format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Both must contain the unique email address of the authenticating user. The name part of the email will be used as the username in SwaggerHub (see Username and email considerations for details).

Below is an example of the expected SAML assertion in the identity provider’s response. Here, [email protected] is the email address of the authenticating user.

    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="id70527211628353331025746989" IssueInstant="2018-11-27T12:30:57.833Z" Version="2.0">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"></saml2:Issuer>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
        <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
                xmlns:xsi="" xsi:type="xs:string">[email protected]</saml2:AttributeValue>


See Troubleshooting Single Sign-On in SwaggerHub On-Premise for some common issues and solutions.

See Also

Publication date: