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

Open the Admin Center.
Select Settings on the left.
Under Authentication, change the Authentication Type to SAML.

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.

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.

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.
Wait a few minutes for the system to restart completely.
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, [email protected] 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">[email protected]</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">[email protected]</saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>
...

Troubleshooting

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

SAML 2.0 Settings

Configure SAML authentication

Note

Configure a connector in SAML IdP

SAML metadata file

SAML request

Note

SAML response

Troubleshooting

See Also

Search results