SAML 2.0 Settings

Last modified on October 14, 2021

This information applies to SwaggerHub On-Premise.

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:

    Option Description
    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.

    Note: These options were added in v. 1.27.
    Option Description
    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 "3.3.2.2.1 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) Value
Protocol version SAML 2.0
Assertion Consumer URL http(s)://{swaggerhub-host}/login/callback
Entity ID (of SwaggerHub) http(s)://{swaggerhub-host}/login/callback
Application URL http(s)://{swaggerhub-host}
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"?>
<md:EntityDescriptor
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="swaggerhub">

  <md:SPSSODescriptor
      AuthnRequestsSigned="false"
      WantAssertionsSigned="false"
      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

    <md:NameIDFormat>
      urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    </md:NameIDFormat>

    <md:AssertionConsumerService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="http://YOUR-SWAGGERHUB-HOST/login/callback"
        index="0" />

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

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

      <md:RequestedAttribute
          FriendlyName="email"
          Name="urn:oid:0.9.2342.19200300.100.1.3"
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
          isRequired="true" />

    </md:AttributeConsumingService>
  </md:SPSSODescriptor>

</md:EntityDescriptor>

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"
	ID="_b20f917a81b68dc7f1d4"
	Version="2.0"
	IssueInstant="2018-11-27T09:49:48.916Z"
	ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
	AssertionConsumerServiceURL="https://your_swaggerhub_host/login/callback"
	Destination="https://your_idp.example.com/sso/saml">
	<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"
		Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
		AllowCreate="true"
	/>

	<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>
	</samlp:RequestedAuthnContext>
</samlp:AuthnRequest>
Note: 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, USER@EXAMPLE.COM is the email address of the authenticating user.

...
<saml2:Assertion
    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">https://your_idp.example.com/Issuer</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">USER@EXAMPLE.COM</saml2:NameID>
        ...
    </saml2:Subject>
    ...
    <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">USER@EXAMPLE.COM</saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>
...

Troubleshooting

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

See Also

Single Sign-On - Overview
How to: Single Sign-On With Okta
Single Sign-On FAQ

Highlight search results