Skip to main content

​
Introduction

Single sign-on (SSO) is an authentication method that enables users to securely authenticate with multiple applications and websites by using just one set of credentials. Qobra’s SSO is implemented based on SAML (open standard used for authentication). This feature is pen-tested yearly by independent contractors. There are 3 parties involved in a SSO connection on Qobra:
  • The user who wishes to connect with his email address
  • Qobra, the application where the user wants to authenticate
  • The identity provider (IDP) which authenticates users and grand them access to the platform, such as Okta, AzureDirectory, Keycloak, etc …

​
Setup

You can manually setup your SSO in the Qobra platform (company settings - security). SSO setup dialog

​
Step 1: Retrieve data from Qobra

You’ll have first to retrieve the following information fields below, and input it in your IDP:
  • Entity ID: unique identifier that is used to identify a specific entity (here your Qobra account) in the SAML authentication.
  • Redirect URL or Callback URL: The callback URL represents the place where people will be redirected to after authenticating with their identity provider.

​
Step 2: Input data in Qobra

Then, you’ll have to fill in both field below to complete SAML setup:
  • Domain name: domain name used in the company’s user email addresses. This field will default to your email’s domain name.
  • Metadata URL: URL of the SAML metadata, an XML document which contains information necessary for interaction with Identity Provider(IDP). This document contains essentials data to make the connection secure and successful (ex: URLs of endpoints, information about supported bindings, identifiers and public keys).
The metadata available at the metadata URL should look something like this: 
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://idp-saml.ua3.int/simplesaml/saml2/idp/metadata.php">
  <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID7T...T7yNJg==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID7TCC......QsT7yNJg==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp-saml.ua3.int/simplesaml/saml2/idp/SingleLogoutService.php"/>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp-saml.ua3.int/simplesaml/saml2/idp/SSOService.php"/>
  </md:IDPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:SurName>Administrator</md:SurName>
    <md:EmailAddress>name@emailprovider.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

​
Step 3: Multiple domain names (optional)

If your company currently has more then one domain name (because of a merger or rebranding typically), you can contact the support for them to fill in a second domain name for your company. You can’t do this action on your own for security purposes.

​
Identity provider tutorials

You’ll find here step by step tutorials for our customers top 3 identity providers. If you’d like another identity provider to be present here, just ask us here.
  1. Go to your admin dashboard, in the Applications tab.
  2. Click on the button “Create a new app integration” and select SAML 2.0 New app integration
  3. Fill the basic info of the app (App name: Qobra, logo, etc.) Fill in basic info
  4. Fill the SAML settings as shown below. There is no specificity in the advanced settings for this setup but your organization could have some specific constrains to be filled. Please contact your organization IT for more information. Fill in SAML settings
  5. You can finish the setup by providing the following settings. Finish the setup
  6. Congratulations you now have access to the metadata URL. Access the metadata URL
  1. Go to the Enterprise Applications tab and click the New Application button. Enterprise Applications Tab
  2. Select the Microsoft Entra SAML Toolkit application and put Qobra in the name field. Saml Toolkit Application Gallery
You can now click on the Create button
  1. Once on your new application, go to the Single sign-on tab and click on SAML Single sign-on tab
  2. You can now click on the Edit button to start putting the SAML data Fill in SAML data
  3. Go to your SSO settings at https://app.qobra.co/parameters/security Qobra SSO data
  4. Thanks to the information gathered on your SSO settings you can now fill those 3 fields:
After filling those fields, you can now click on the Save button.
  1. Copy the App Federation Metadata Url in the SAML Certificates section and fill it in Qobra SSO config (Metadata URL field) App Federation Metadata Url
You should also fill the domain name of your email in the Domain name fieldUpdate Qobra SAML config
  1. Go to administration UI to add a client. Add a client
  2. Go to the next step and complete login settings as shown below. Complete login settings
  3. Once the app is created, you MUST update theses parameters on client settings:
  • Sign Assertion: ON Fill in 'Sign assertion' option
  • Name ID Format: Email Fill in 'Name ID Format' option
  • Signing key config: OFF Fill in 'Signing key config' option
  1. Now you can access the metadata URL, as shown below Access the metadata URL

​
Troubleshooting

​
Can’t find the Metadata URL

  • If you use Okta, KeyCloak or AzureDirectory, refer to the documentation about those specific identity providers.
  • If your identity provider only allow clients to download your metadata, you’ll have to serve them through an URL (S3, cloud storage, static server, etc …). Qobra does not allow the upload of SAML metadata in the platform.

​
Metadata URL is rejected

The host of your Metadata URL may point to an internal destination. It happened when you self-host your identity provider on your internal network. As a security measure and because we cannot access this internal host, we block the request. You must serve your metadata through a public URL.

​
Can’t authenticate after registering your SSO

Check your Metadata URL by visiting it directly on your browser:
  • The page should not return an error
  • The page should return an XML file
  • The assertions should be signed in your XML file

​
Issues with setting home realm discovery

As a security measure, an admin is only able to set a home realm discovery matching the domain name of his email address. To change it to another client domain, you should ask the support for help.
⌘I