SAML 2.0 Settings

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

Swagger Studio 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

Note

Ensure that the Signature settings for your SAML Provider are configured to Sign response and assertion, as versions 2.12.0 and later require both requests and responses to be signed.

  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 Swagger Studio 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 Swagger Studio 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.

    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.

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

Configure a connector in SAML IdP

To configure a Swagger Studio 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 Swagger Studio)

http(s)://{swaggerhub-host}/login/callback

Application URL

http(s)://{swaggerhub-host}

SAML Token Attributes, Attribute Mappings, or similar

Swagger Studio expects a single attribute named email containing the user email address. The attribute name is case-insensitive and can be email, Email, and so on.

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.

Signing (Requests + Responses)

Configure the IdP to sign the SAML token it issues: at a minimum, to sign the Assertion, and if supported, both the Response and the Assertion. Additionally, if your IdP supports or requires signed authentication requests, allow validation (and optionally enforcement) of signed AuthnRequests from the SP.

Replace {swaggerhub-host} above with your Swagger Studio 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 Swagger Studio to complete the configuration, use a file with the following contents. Replace YOUR-SWAGGERHUB-HOST with your Swagger Studio 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="true"
      WantAssertionsSigned="true"
      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 Swagger Studio OnPremise SP -->
    <md:AttributeConsumingService index="0" >

      <md:ServiceName xml:lang="en">Swagger Studio 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 Swagger Studio 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>

SAML response

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

  • A single attribute named email (case-insensitive).

  • A NameID claim 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 Swagger Studio (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 Swagger Studio On-Premise for some common issues and solutions.

See also

In this section:
© 2026
Publication date: