SAML 2.0 for Skuid data sources

Using OAuth’s Authorization Code grant type, Skuid is able to easily connect to a variety of data sources and display them in one place. And while the process is already relatively painless—only requiring that end users sign in with their credentials through an OAuth popup window—single sign-on can streamline that process even further. This is accomplished using the SAML 2.0 Bearer Assertion OAuth grant type. In this OAuth flow, Skuid—through your IdP—authenticates users to the individual data sources used within your Skuid site without any user intervention.

In practice, this means users would sign in to Skuid through SAML, and then go straight to work in their Skuid apps—no other OAuth popup windows or other authentication steps.

Check the documentation of your preferred data source to see what the requirements are for their application and whether it supports this authentication flow.

While this process can vary depending on your use case, there are some common steps. For a specific example, see Accessing a Salesforce org as a Skuid data source with the SAML 2.0 OAuth Flow.

Note

The below steps assume you have already created an indentity provider connection within Salesforce. If you have not done so, you will not be able to complete the steps below.

1. Download a certificate for identity verification

Certificates are a key component of the SAML 2.0 Bearer Assertion OAuth grant type, ensuring that your IdP and your data source can mutually identify one another and securely exchange identity information using SAML.

To obtain the certificate, you’ll be utilizing Salesforce’s Certificate and Key Management. You can choose to download Salesforce’s default certificate or to generate your own self-signed or CA-signed certificate.

Whichever certificate you choose to use, you will need to identify this certificate in the OAuth client / app connection you’ll configure within your data source in Step 4. Configure a Skuid authentication provider and data source.

  1. Within Salesforce Setup, navigate to Administer > Security Controls > Certificate and Key Management.
  2. Click either Create Self-Signed Certificate or Create CA-Signed Certificate.
  3. Fill out the Label field with an appropriate name for your needs.
  4. (CA-signed Certificates) Fill out the required information for your certificate signing request (CSR). This information must be correct, as it will be validated when you provide this CSR to your CA for signing.
  5. The auto-generated values and defaults for your other fields will be correct; click Save.
  6. Click Download Certificate (Self-Signed Certificates) or Download Certificate Signing Request (CA-Signed Certificates).
  7. (CA-Signed Certificates only) Once your CSR has been signed by your CA, you will need to return to this certificate record and click Upload Certificate to import the signed certificate into Salesforce.

You should also note the unique name generated by the label of your certificate, as you will use this value for your Skuid authentication provider’s Assertion Signing Certificate field, created in Step 4. Configure a Skuid authentication provider and data source.

2. Configure your data source and your IdP for SSO authentication

To access Skuid via SAML, you’ll need to configure an SSO application within your IdP of choice. However, to take advantage of the SAML 2.0 Bearer Assertion flow with any data source, you must also configure a service provider application for your chosen data source within your IdP, and the corresponding identity provider connection for your IdP within that data source.

These identity provider connections are essential: they enable the data source to delegate authentication of an end user requesting access to its data to the IdP. You’ll be using the issuer value from your data source’s identity provider connection when configuring your OAuth app connection as well, so take note of this field.

This process will vary from data source to data source, and also from IdP to IdP. Refer to the documentation of the data source and IdP of your choice for more information.

3. Creating an OAuth app connection within your data source

As with other OAuth flows, you’ll need to create an OAuth client within your data source application. This OAuth client will then register Skuid as a party authorized to connect to the data source’s API. After creating this OAuth client within the data source application, you should receive a client Id and client secret—or similarly named credentials.

You will need to securely store these credentials for later access, as they are needed to configure your data source connection within Skuid.

As part of your OAuth client setup, you will also need to configure SAML-specific settings. This will vary depending on the external data source you are connecting to.

Two of these key settings:

With all fields properly configured—and these two essential values in place— the OAuth client connection will facilitate the actual data connection between Skuid and the data source being accessed.

4. Configure a Skuid authentication provider and data source

First, create a Skuid authentication provider.

  1. Navigate to Settings > Data Sources > Authentication Provider.

  2. Click New Authentication Provider.

  3. Fill out the fields as follows:

    • Name: Enter an appropriate name for your authentication provider, such as <Your Data Source>SAML.
    • Authentication Method: OAuth 2.0 / OpenID
    • Provider Type: Select the appropriate provider for the data source you’re accessing.
    • Grant Type: SAML 2.0 Bearer Assertion
    • Token Endpoint URL: Depending on your external data source, you may need to edit the value of this field, perhaps filling in your My Domain or organization ID.
    • Assertion Signing Certificate: Enter the unique name of the certificate you used in the first section.
    • Client ID: Enter the the appropriate id or key of the OAuth client / connected app from the previous section.
    • Client Secret: Enter the enter the appropriate key or secret of the OAuth client / connected app from the previous section.
  4. Click Save.

After this, you’ll need to create a Skuid data source that uses the above authentication provider to authenticate. Within that data source, also configure the name identifier to use to send in the SAML assertion sent to the external data source—a field that correlates with a user record on the external data source, such as a username, federation identifier, or email address.

  1. Navigate to Settings > Data Sources.
  2. Click New Data Source.
  3. Select appropriate option for your Data Source Type.
  4. Enter an appropriate Name for your data source, such as <Your Data Source>SAML.
  5. Click Next Step.
  6. Configure any data source specific options.
  7. Click Next Step.
  8. Select the authentication provider you configured in the previous section.
  9. Click Save new Data Source.

After creating this new data source, configure the advanced settings to properly send a username to the external data source you are connecting to. If you do not see the settings listed below, refresh your page.

  1. Click Advanced Settings for the newly created data source.
  2. Ensure that your Authentication Method is still set for the authentication provider you configured in the previous step.
  3. Beside SAML Name Identifier Source or Name Identifier Field, enter a value that will correlate to the name identifier of the org you are connected to. Select an option appropriate for your use case:
    • Email: Use this option to send the email of the current user—on Salesforce or Skuid SFX—as the identifier in the assertion.
    • Federation Identifier: Use this to send the federation identifier of the current user—on Salesforce or Skuid SFX—as the identifier in the assertion.
    • Username: Use this option to send the username of the current user—on Salesforce or Skuid SFX—as the identifier in the assertion.
    • Result of a Formula: If none of the identifiers above directly correlate with the the data source’s expected name identifier syntax, you can dynamically generate the expected value with a formula using text transformation functions and merge syntax here. The following functions are available:
      • LOWER(): Will return the parameter in entirely lowercase letters.
      • UPPER(): Will return the parameter in entirely uppercase letters.
      • FIRST(): Will return the first letter of its parameter.
      • LAST(): Will return the last letter of its parameter.
      • An example formula with a function and merge syntax: LOWER({{$User.FirstName}}) && “@example.com”
        • If the user’s first name is “Sally” –> “sally@example.com”
  4. Click Save.

Within the Composer, create a new model and connect it to your newly created data source. At build time, it will act just like any other model. But at runtime, your end users will simply see the data they have access to—no OAuth popup windows or the like.

Troubleshooting

There are a lot of moving parts when configuring SSO, so try checking these key areas if you’re seeing issues:

  • The identity provider connection within the external data source for your IdP must be properly configured.
  • The following fields within the OAuth client connection within the external data source must be properly configured with:
    • The Entity ID and ACS URL corresponding to your Salesforce org or Skuid SFX site.
    • The Issuer field from your external data source’s identity provider connection
    • Your certificate of choice

Note

To use this flow you must log into Salesforce/Skuid NLX using your IdP. If you login using the standard Salesforce or NLX login screen—and not through SAML or the Login with SAML option in NLX—then you will not be able to access data sources using this flow.