Single Sign-On

SAML (Security Assertion Markup Language) is an XML-based single sign-on protocol. This authentication protocol is used by many services to allow end users to log into one service (known as an identity provider) to access multiple different services (known as service providers). Hence, single sign-on can simplify logging in to a process that looks more like this:

  1. Users login once to their identity provider (IdP), where they enter their unique username and password for the IdP.
  2. After logging into the IdP, users typically see a list of all services they have permission to access.
  3. Users click on the desired service, and they are logged into the service without entering a username or password.

By ensuring users have one method of entry into various services, authentication becomes a more streamlined—and arguably more secure—process.

Skuid (both Platform and on Salesforce) can be used with the SAML protocol. By configuring Skuid for SAML, you can allow your users to login into Skuid with the click of a button. And with SAML functionality, you can also authenticate your end users to some of your Skuid data sources.

Concepts to know

When using SAML to connect to Skuid—or your data sources—the actual screen-by-screen experience will vary depending on which single sign-on services you utilize. However, there are several concepts and phrases that are consistent for this process:

Single Sign-On (SSO): The actual process of logging into an identity provider to access multiple service providers.

Identity Provider (IdP): An application that defines your end users and which applications/services these users are able to access. Examples include:

  • Active Directory
  • Okta
  • PingIdentity
  • OneLogin

Additionally services like Salesforce and Google Apps may be used as IdPs.

Service Provider (SP): The services being accessed by the IdP. This can include Skuid, Google apps, Salesforce, or other services.

Security Assertion Markup Language (SAML): An XML-based standard for SSO. Skuid only supports SAML 2.0.

Assertion: The term used for the XML message IdPs send to SPs to authenticate. Assertions contain several necessary authentication values used for logging in, as well as user provisioning when enabled.

IdP metadata files: A file provided by an IdP describing what is contained within the XML of its authentication assertion. These files contain the following:

  • Entity ID: Tells the service provider (i.e. Skuid Platform) who the IdP is.
  • Certificates: One or more security certificate used for identifying the IdP and encrypting/decrypting SAML messages.
  • Single sign-on location URL: A URL that the SP can redirect a user to in order to initiate SSO. If the user has not logged in to the IdP yet, they will be prompted to login, otherwise they will be redirected back to the SP’s ACS URL with an assertion.

Skuid Platform needs all of this information to enable SSO. Rather than configuring information manually, it’s best to use IdP metadata files whenever possible, as they make creating SSO configurations much easier.

Assertion Consumer Service (ACS) URL: The URL where an IdP will send an assertion for an SP to consume and properly authenticate users.

Audience URI / Service Provider Entity ID: The unique ID of an SP, which may be a Skuid Platform site, a Salesforce org, Google application, or any other SP. Your IdP needs to know this value to properly send its assertions.

  • In Skuid Platform this is an XML file that may be retrieved at the URL provided or downloaded via the Download Metadata XML File button in the SSO config detail screen. This file can be used to simplify registration of Skuid as a service provider in many identity provider systems.

Federated SSO and Federation ID (FID): In federated SSO, the IdP serves as a singular entry point to a group—or federation—of applications. To accomplish this, the IdP and SP will typically communicate a federation ID, which is a trusted piece of data—known to both systems—that can identify individual users.

The SP will receive a federation ID from the IdP, and it will trust that the end user has been properly authenticated. In practice, this means some SPs will not require a password to authenticate a user if it receives the proper FID, and sometimes a password may not even exist.

Within Skuid Platform, users’ federation IDs are set when a user is provisioned and can be updated by Skuid admins at any time.

SSO for Skuid on Salesforce

Since Skuid on Salesforce is a managed package installed within a Salesforce org, user management—and thus SSO—is handled by Salesforce itself.

To learn more about configuring your Salesforce org for SSO, read Salesforce’s Single Sign-On Implementation Guide.

After logging into Salesforce through an IdP, you can access Skuid as you would normally.

SSO for Skuid Platform

You’ll need to configure both your IdP and Skuid Platform for SSO. This process varies depending on which IdP you use, but the concepts below are universal.

Minimally, you’ll need to configure the following values within your IdP so it can access Skuid Platform:

  • ACS URL
  • Service Provider Entity ID

Skuid Platform will generate these URLs after you create a new SSO Config within Skuid Settings.

To create a new SSO Config:

  1. Navigate to Configure > Site > Single Sign On.
  2. Click to the SAML Enabled checkbox to enable SSO.
  3. Click New Single Sign On Config.

You’ll have several options:

  • Enter information manually: Configure the fields listed in the next section manually.
  • Import from Identity Provider Metadata File: Skuid will use the metadata file from your IdP to automatically configure all of the necessary fields. Download the metadata file from your IdP and use this option to upload it.
  • Import from Identity Provider Metadata File - at URL: Skuid will use the metadata file from your IdP to automatically configure all of the necessary fields. Insert the URL that points to your IdP’s metadata file.

Using your IdP’s metadata file is the recommended way to create your SSO configurations. To do this, you may need to initially configure your IdP—potentially using some dummy information—to access its metadata file. Refer to your chosen IdP’s documentation for more information.

If you manually create a new SSO configuration, or edit an existing one, you’ll see the following fields:

Basic Details

  • Provider Name: The human-readable name of your SSO configuration within Skuid Platform. (While not sent in SSO requests, this field should correlate with your IdP.) If you have multiple SSO configurations in your Site, this name will be displayed on the login screen to allow end users to choose which Provider to use for SSO during login.
  • Entity (Service Provider Id): The unique identifier for Skuid Platform as a service provider. This is used during SAML to identify Skuid to your IdP. This value must match a corresponding setting in your IdP’s configuration for this service provider, so that the IdP and Skuid are able to identify each other during SAML message exchanges. Skuid generates a default entity value, but you can change this if your IdP dictates a specific format for service provider entity values. For example, Active Directory generates a specific entity for each service provider, and you must use this value here in order for Active Directory to work with Skuid SSO.

Identity Provider Details

  • Issuer (Identity Provider Id): The unique identifier for your IdP, frequently in URL format. This is sent by Skuid as part of SAML exchanges, and is used by Skuid to validate that a SAML message came from an authorized IdP.
  • Identity Provider Certificate: The security certificate that is used to mutually identify Skuid to your IdP, and vice versa. This certificate must be provided by the IdP, and is usually included in an IdP’s metadata file.
  • Identity Provider Login URL: A URL from your IdP that Skuid can use for SP-initiated SSO (i.e. this is the URL that the Login with SAML link on the login screen will go to).
  • Identity Provider Logout URL (Optional): If your IdP has a separate URL for logging out an SSO user, enter it here.
  • Assertion Decryption Certificate: If the XML assertion sent by your IdP will be encrypted, select the appropriate decryption certificate here. You must first create or upload a certificate by navigating to Configure > Site > Certificates, and then return here to select the certificate.
  • Request Signing Certificate: By default, Skuid will sign SAML requests using a default certificate, which can be downloaded by going to Configure > Site > Certificates and clicking Download Default Certificate on the certificates table. For increased security, you can instead create a custom certificate to use for request signing. The request certificate must be created / uploaded from the Certificates tab, after which you can select it here. Skuid will then use that certificate when signing SAML requests. Note: Whichever certificate you choose for request signing must be downloaded and uploaded into your IdP’s corresponding service provider configuration.
  • Request Signature Method: Select whether your requests will be signed using the SHA-1 or SHA-256 algorithm.

Identity Location

For Skuid to log a user in based on a SAML assertion sent from the IdP, Skuid needs to do two things:

  • Extract a piece of information from the assertion that uniquely identifies the user.
  • Match this identity information with a corresponding attribute on an existing user record.
    • If user provisioning is enabled, Skuid will examine the identity information to determine that no corresponding user exists and provision a new user accordingly.

You’ll configure how this process should operate using the properties in this section.

  • SAML Identity is in: Used to configure which piece of information Skuid extracts to identify the user.
    • The NameIdentifier element of the Subject statement: When your IdP sends a SAML assertion to Skuid in response to a user’s request for SAML identification, this assertion will always include a “Name Identifier” element within a “Subject” statement. Generally, an IdP can be configured so that this Name Identifier element will contain the user’s Skuid username, and most SSO Configs will use this NameIdentifer option.
    • An Attribute element: IdPs generally send various attributes about the user, such as the First Name, Last Name, Email, or a Federation Identifier, within various Attribute elements in the assertion. If the NameIdentifier element does not contain the necessary identity information, Skuid will need to identify the user by examining one of these attribute elements.To do so, select this option and then specify the name of the attribute that contains the desired identification element.
  • SAML Assertion contains Skuid user’s: Used to configure which piece of Skuid user data to search for the SAML identity provided in the assertion. When your IdP sends an assertion, it will need to include at least one field that correlates to a Skuid Platform user field. This allows Skuid Platform to authenticate the correct user. Select that corresponding field here.
  • Username
  • Federation ID
  • Email Address
  • User Id

Enable User Provisioning?: When user provisioning is enabled, Skuid Platform automatically will automatically create a new end user if it receives an assertion containing an unknown user identifier—provided the IdP provides the necessary fields for user provisioning.

Once an SSO config is created, you may download Skuid’s service provider XML file via the Download Metadata XML File button.

User Provisioning within Skuid Platform

With Enable User Provisioning selected, your Skuid site will automatically generate new end user accounts for anyone that tries to authenticate through your IdP, if their account does not already exist.

While the specific process varies depending upon the IdP, user provisioning always requires that your IdP sends Skuid Platform several key attributes in a particular format within the assertion in order for a new user to be created. These Attributes must be sent in <saml:Attribute /> nodes within the <saml:AttributeStatement /> portion of the assertion. The attributes include:

  • First Name
    • Must be contained within an attribute named one of the following:
      • User.FirstName
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • Last Name
    • Must be contained within an attribute named one of the following:
      • User.LastName
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • Email: The new user’s email address, to which all user-related communications will be sent. Does not need to be unique.
    • Must be contained within an attribute named one of the following:
      • User.Email
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Username: Used for logging in to your Skuid site. Must be unique within your site. Ensure that this username follows whatever standardized format you wish to follow on your site.
    • Must be contained within an attribute named one of the following:
      • User.Username
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
  • Federation Identifier: Used for uniquely identifying a user across multiple service providers. If not provided separately from username, this will be extracted from the same set of attributes used for username.
    • Must be contained within an attribute named one of the following:
      • User.FederationId
      • User.Username
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier

How you configure your assertion to include these values will vary from IdP to IdP.

Note

  • Any end users created through SSO provisioning will not have passwords on Skuid Platform; Skuid authenticates any SSO-provisioned users differently. Therefore they cannot access Skuid Platform any other way than through the IdP (IdP-initiated SSO) or the Login with SAML link on the Skuid Login page (SP-initiated SSO).
  • Users created by SSO provisioning in Skuid Platform will receive the Standard user profile, which by default has no permissions. Make sure to configure App Access and Data Source Access permissions for the Standard profile.

Logging in via SSO

After configuring Skuid Platform and your IdP, both IdP-initiated and SP-initiated SSO are supported.

  • IdP-initiated: Within your IdP, you’ll configure your Skuid Platform application and access as normal for your particular IdP.
  • SP-initiated: Once an SSO configuration exists within your Skuid Platform Site’s settings, you’ll see a Login with SAML link on your Skuid site’s login screen.
    • If only one SSO configuration exists, clicking this link will log you in directly to Skuid Platform using the one available configuration.
    • If more than one SSO configuration exists, clicking this link will display a list of all available SSO providers, so that the end user can select the desired provider.

SAML 2.0 OAuth grant type 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.

This is a relatively new authentication flow that grants OAuth 2.0 tokens. As such, many services do not yet support it. You will need to check the documentation of your preferred data source to see what the requirements are for their application.

While this process can vary depending on your use case, there are some common steps.

Note: The below steps assume you have already set an IdP configuration within Skuid on Salesforce or Skuid Platform. 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.

How you obtain your certificate will differ based on how you are using Skuid:

  • When using Skuid Platform, you can download a default certificate available on every Skuid Platform site, or you can generate your own self-signed or CA-signed certificate.
  • When using Skuid on Salesforce, 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.

In Skuid Platform

  1. Navigate to Configure > Site > Certificates.
  2. From here, download Skuid Platform’s default certificate or generate a unique self-signed or CA-signed certificate.
    • To download the default certificate:
      • Click the drop down arrow beside Create Self-Signed Certificate.
      • Click Download Default Certificate.
    • To generate your own certificate:
      • Click Create Self-Signed Certificate.
      • Fill out the Certificate Name field with an appropriate name for your needs.
        • Choose whether the certificate’s Key Size is 2048 or 4096 bits. A larger key will be more secure, but will take longer for to parse.
      • Click Save.
      • Click View Certificate Details.
      • Click Download.

If you choose to generate and use a self-signed or CA-signed certificate for your data source’s OAuth app connection, you must select this certificate within your IdP SSO configuration:

  1. Navigate to Configure > Site > Single Sign On.
  2. Click Edit SSO Config.
  3. Select the appropriate certificate in the Request Signing Certificate field.

If you choose to generate CA-signed certificate, you must download the certificate’s signing request and provide this to your Certificate Authority (CA). Once the CA provides you with a signed certificate, you must upload the signed certificate into the original certificate record in Skuid Platform, and you must select this certificate within your IdP SSO configuration.

In Skuid on Salesforce

  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.

When using Skuid on 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—whether on Salesforce or on Skuid Platform—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 SSO configuration for your IdP within that data source.

These SSO configurations 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 SSO configuration 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 Configure > 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 (Skuid on Salesforce only): 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 Configure > Data Sources > 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 Platform—as the identifier in the assertion.
    • Federation Identifier: Use this to send the federation identifier of the current user—on Salesforce or Skuid Platform—as the identifier in the assertion.
    • Username: Use this option to send the username of the current user—on Salesforce or Skuid Platform—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 App 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 in this process, so if you’re having difficulties, here are some key areas to check:

  • The SSO configuration 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 Platform site.
    • The Issuer field from your external data source’s SSO configuration
    • Your certificate of choice
  • If in Skuid Platform, the SSO Config’s Request Signing Certificate must match the certificate used within your OAuth app connection in your external data source.

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

For a specific example of this process, see Accessing a Salesforce org as a Skuid data source with the SAML 2.0 OAuth Flow.