Authentication and Skuid

Skuid provides several different mechanisms for authenticating to external services. You can choose to store (shared and/or individual) credentials securely within Salesforce, or you can choose to leverage standards like OAuth to delegate authentication to a third party.

Authentication Methods

No Authentication

Select this option if your service is publicly available and does not need any type of credentials for access. This method could also be relevant for services that are behind a firewall and the data source has “Use Apex Proxy” unchecked.

Basic HTTP Authentication

While OAuth is the recommended authentication flow for most data sources, Skuid also allows for basic HTTP authentication—in short, sending encrypted user credentials to a data source to login.

Skuid encrypts all usernames and passwords using AES-256 symmetric encryption. Credential records are stored in Protected Custom Settings which are inaccessible to querying through any API—only Skuid internal code can access this information, and Skuid does so only when making authentication requests to data sources. Your company’s Salesforce administrator can change the encryption key from the Skuid Settings page.

Note

It is impossible for Skuid administrators to login as a different end user and gain access to that user’s data source credentials.

With Basic HTTP Authentication, credentials are sent Base64 encoded as a header with every request. If you select this authentication method, Skuid will automatically construct the “Authorization” as shown below. For example, if a username of “Aladdin” and a password of “open sesame” were provided, Skuid would construct the following header.

1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

When configuring basic HTTP authentication for a data source, you must specify a credential source. This can either be:

  • Shared by all Site Users (Skuid Platform) / Shared Org-wide (Skuid on Salesforce): If you want all end users to share the same username and password to access the external data system, select this option and enter the credentials on the form that appears below the picklist.
  • Shared Per-Profile, with optional Org-wide Defaults: If you want end users to share a login based on a Salesforce profile, enter the credentials on the form that appears below the picklist. You may also enter default org-wide credentials.

Note

This credential source is not currently available on Skuid Platform.

  • Per-User, with optional shared Site-wide Defaults (Skuid Platform) / Per-User, with optional Profile / Org-wide Defaults (Skuid on Salesforce): Allows users to enter their own individual credentials for a data source, with optional default credentials available if needed.

    End users manually add their own credentials within the Skuid UI:

Separate Authentication URL

With the Separate Authentication URL option, Skuid will first make a request to a separate authentication URL, retrieve a token, and then use that token on subsequent requests to the service.

When configuring a Separate Authentication, you can (but are not required to) specify a credential source. This can either be Shared: Org-Wide, Shared: Per-Profile, or Per-User.

  • If the Shared: Org-Wide setting is selected, then you will be prompted to enter the shared username and password.
  • If the Per-Profile, or Per-User settings are selected, then the credentials need to be entered on a separate screen.

Authentication Provider (OAuth, Custom, etc.)

Authentication Providers in Skuid allow for the use of specialized protocols (like OAuth) or custom Apex Code to handle Authentication. Using Authentication Providers, Admins can configure OAuth connections or Custom Apex code.

Grant Type Authentication Flows

When configuring authentication providers, there are several grant types to choose from. Depending on your choice, end users will go through a different authentication flow when they attempt to use a data source.

Authorization Code Grant

In the Authorization Code OAuth flow, Skuid uses a popup to redirect the end user to an authorization endpoint, where it provides a Client ID to identify the client requesting access on behalf of the user. The end user then enters credentials.

Because this is in a separate popup window, Skuid has no access to the credentials being entered. This interaction is completely between the user and the Authorization Server. Once the end user enters credentials here—and it is determined by the authorization server that the credentials are correct—Skuid receives an authorization code via a “Callback URL. Once Skuid has an authorization code, it can exchange that code for an access token from an access token endpoint. Until the token expires (or is otherwise invalidated), it can be used to gain access to the resource server.

The access token has a limited lifespan, specified by “expires” and “expires_in” parameters sent to the client in the access token response. Once the access token expires, a new access token must be requested. One of the benefits of the Authorization Code grant, as opposed to the Implicit grant, is that it provides a mechanism for new access tokens to be automatically requested on the end user’s behalf when access tokens expire. It does this by means of “refresh tokens.”

Typically, the first time an end user successfully retrieves an access token via an Authorization Code flow, the authorization server sends back a refresh token in addition to an access token. Think of the refresh token like “TSA Pre-check”:n it lets an end user skip the authorization code step and skip right to the access token request. (This is significant because it requires manual user interaction with the screen to re-authorize.) If Skuid has a refresh token stored for a particular service, it can use this to perform a “refresh token” grant flow to request new access tokens for the user—and do it behind the scenes, as needed, when access tokens expire. This makes the combination of the Authorization Code / Refresh Token Grants a better user experience than the Implicit Grant, which does not support refresh tokens.

Key Takeaways:

  1. Keeps User Credentials secret
  2. Allows new access tokens to be automatically obtained via refresh tokens

Step 1: Open a popup window at a particular URL

GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

Step 2: If authorization is successful, the popup window is redirected to a “Redirect URI” or “Callback URL”

HTTP/1.1 302 Found

Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

Step 3: Using the Authorization Code received in Step 2 to request an access Token

Both the Client Id and Client Secret are typically used to authenticate the client in this step.

POST /token HTTP/1.1

1
2
3
4
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Step 4: An Access Token is returned

HTTP/1.1 200 OK

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "example_parameter":"example_value"
}

Step 5: Using the access token, make the actual request to the resource server

Client Credentials

This grant type uses the Client ID and Client Secret REST API credentials for authentication instead of individually authenticating specific end users through an authorization code or username/password credentials.

Implicit Grant

In the implicit grant, the client is issued a token directly. Since this flow is initiated from the client (Web Browser) it does not authenticate the client using a client secret. Only the public client Id is used.

Key Takeaways

  1. Keeps User Credentials secret
  2. Does not allow refresh tokens - end users must reauthorize when access tokens expire

Step 1: Client makes a request to the authorization server

GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

Step 2: If authorization is successful, the client is redirected and given an access token

HTTP/1.1 302 Found

1
Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA

Resource Owner Password Credentials Grant

In this grant flow, the resource trusts the client enough to give away its credentials.

Key Takeaways

  1. Stores credentials in Salesforce
  2. No need for end user to enter credentials often

Step 1: Request an access token using the username and password

POST /token HTTP/1.1

1
2
3
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=johndoe&password=A3ddj3w

Step 2: If authorization is successful, the client is given an access token

HTTP/1.1 200 OK

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

Storing Credentials in Salesforce

For data sources that use Basic HTTP Authentication, Separate Authentication URLs, or an Authentication Provider, you can choose to store credentials within a Protected Custom Setting inside of Salesforce. As an extra layer of protection for these credentials, Skuid encrypts all Credentials using 256 Bit AES Encryption. The encryption key can be configured within each individual org that stores credentials. Credentials can be specified on an org-wide level, a Profile level, or can be entered on an individual user basis.

The following fields are stored encrypted in Skuid:

  • Data Source (for org-wide credentials)
  • Username
  • Password
  • Data Source Credentials (for per-profile or per-user credentials)
  • Username
  • Password
  • Authentication Provider
  • Client Id
  • Client Secret

Note: As org-wide credentials and per-profile/per-user credentials are configured in different areas, they are encrypted as different objects. However, this does not affect their security or functionality.

Troubleshooting Tips for Authentication

To troubleshoot OAuth issues, you can use Skuid’s Javascript OAuth API to examine the OAuth response for a particular service for which authentication was requested. For instance, if you were having issues connecting to Dropbox, you could inspect the OAuth response by going into the JavaScript console and entering:

skuid.oauth(‘dropbox’).getAuthResponse();

This returns an object which should contain details of any errors that occurred with your OAuth flow for that service.

  • For all standard OAuth provider types, this will be accessible via skuid.oauth(provider_type), which is usually the lowercase name of the provider type.
  • For other provider types, you will need to use the provider’s name as defined on the data source record.

Removing stored OAuth access credentials

To remove stored OAuth access credentials for a particular service, call the following method:

skuid.oauth(provider_type_or_name).logout();

Intro to OAuth

OAuth is an open source standard for authentication. It allows a third party (Skuid) to create models on services where Skuid never actually receives or knows the username or password required to access that service. The OAuth spec describes 4 different Grant Types (or Flows) that can be used to gain access to a “Resource Server” (External Web Service).

Additional resources:

Everything you need to know about Force.com and OAuth

https://developer.salesforce.com/page/Digging_Deeper_into_OAuth_2.0_on_Force.com

OAuth Spec

https://tools.ietf.org/html/rfc6749

Authenticating with OAuth 1

Skuid does not currently support authenticating with OAuth 1. For example, Twitter is a service requiring OAuth 1 authentication, therefore Skuid does not support connecting to Twitter’s REST API at this time.

Custom Apex Authentication

This option is currently only used internally to support the Sharepoint data source type’s custom authentication process.

Authentication Merge Variables

{{$Auth.BasicAuth}}

{{$Auth.Username}}

{{$Auth.Password}}

{{$Auth.Response.Body}}

{{$Auth.Response.Headers}}

{{$Api.Session_Id}}

Encryption in Skuid

Skuid stores sensitive data in Protected Managed Custom Settings. This prevents direct access to the stored values (except via Skuid Managed Apex code). Certain fields on these Protected Custom Settings are also encrypted when written to the database and decrypted at run time. We call this “SkuidCryption,” and the objects/fields utilizing this feature are as follows:

Encryption Settings

Encrypted Fields:

  1. skuid__Key__c

This object stores the Organization’s Master Encryption key. This key is itself encrypted with a separate key that Skuid manages. This provides an additional layer of security by avoiding storing the actual encryption key in plain text in an Organization’s data.

Data Source

SkuidCrypted Fields:

  1. skuid__Username__c
  2. skuid__Password__c

Data Source Credential

SkuidCrypted Fields:

  1. skuid__Username__c
  2. skuid__Password__c

Auth Provider

SkuidCrypted Fields:

  1. skuid__Client_Id__c
  2. skuid__Client_Secret__c