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.
Data Source Authentication Methods¶
These authentication methods are available at the data source level.
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 NLX) / Shared Org-wide (Skuid SFX): 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 NLX.
Per-User, with optional shared Site-wide Defaults (Skuid NLX) / Per-User, with optional Profile / Org-wide Defaults (Skuid SFX): 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:
- In Skuid NLX, credential management is done in My Settings > Username / Password Credentials.
- In Skuid SFX, credential management is done in My Credentials.
API Key Authentication¶
Some services authenticate by requiring a special key be passed along in each request—this key being associated with certain permissions in the service. By selecting this authentication type, the API key field appears, which stores the given API key as an encrypted piece of data in Skuid. This key can then be used within any common HTTP header or body request data for the data source—where it will be securely injected server-side to prevent end users from seeing the key should they observe their network traffic.
- API key: The key to store
Once entered and saved, use the {{$Auth.API_Key}}
merge variable to set up a common request header or body data in the format required by the service.
Note
This authentication method requires the use of Skuid’s proxy.
Example¶
Assume a service requires an API key be sent with as an Authorization
header with this format:
1 | Authorization: Bearer <API_KEY>
|
Also assume the API key’s value is abc123
.
To authenticate to this service using API key authentication:
- Create a new data source (or open an existing one).
- Set the authentication method to API Key Authentication.
- In the API key field, enter the API key:
abc123
. - Click Save.
Now you can use the {{$Auth.API_Key}} merge variable in a common request header matching the service’s API reference material.
Click Common HTTP Request Data.
In the Common request headers section, click the box icon in the object, then click Append.
Add a key-value pair that includes the $Auth merge variable:
Authorization: Bearer {{$Auth.API_Key}}
Click Save
Now, when a Skuid model makes a request to this data source’s service, the Authorization
header will appear on the request. To end users, this header’s value appears as Bearer {{$Auth.API_Key}}
. However, when making the request, Skuid’s proxy securely injects the true value.
Separate Authentication URL¶
With the Separate Authentication URL option, Skuid will first make a request to a separate authentication URL, which is expected to return an access token after successfully authenticating. This token can then be used on subsequent requests by updating the data source’s Common request headers and/or Common request body data to use the {{$Auth.Response.Body}}
and {{$Auth.Response.Headers}}
merge variables. You can also access nested parameters/headers through those merge variables. For more information, see the Authentication Merge Variables section
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.
Authentication Provider Authentication Methods¶
The following methods require the use of data source in conjunction with an authentication provider.
Custom Apex Authentication¶
This option is currently only used internally to support the Sharepoint data source type’s custom authentication process.
OAuth 2.0 / Open ID¶
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 several different grant types (or flows) that can be used to gain access to a resource server (External Web Service).
Warning
Skuid does not currently support authenticating with OAuth 1.
Additional resources¶
- Salesforce documentation: Digging Deeper into OAuth 2.0 in Salesforce
- OAuth 2.0 Authorization Framework Spec from the IETF
OAuth 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, also known as a redirect URI. 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. Refresh tokens functionally let an end user bypass 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:
- Keeps user credentials secret
- Allows new access tokens to be automatically obtained via refresh tokens
What happens in this grant flow [[]]¶
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 callback URL/redirect URI.
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 (i.e., the end user’s web browser), it does not authenticate the client using a client secret. Only the public client Id is used.
Key Takeaways
- Keeps user credentials secret
- Does not allow refresh tokens; end users must reauthorize when access tokens expire
What happens in this grant flow [[]]¶
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
|
JWT Bearer Assertion [[]]¶
A JSON Web Token (JWT) is an internet standard JSON object with a variety of key-value pairs typically used for data access. When this grant type is selected, Skuid sends a JWT with each data source request containing several standard claims, as well as any configured custom claims. These claims can be verified as originating from a specific site because of the use of signed certificates—with the Skuid site providing a public key certificate to be uploaded to the external system.
Claims are the key-value pairs that pass along the information that is used to identify the user when they attempt to access data. You’ll likely need to configure one or more custom claims depending on the data your data source expects for authentication.
One of this grant type’s advantages is that there is no OAuth popup, allowing a more seamless experience when users access the page.
To utilize this grant type you must:
- Download a signing certificate from your Skuid site by navigating to Settings > Certificates and clicking the certificate you wish to use. You may create a new certificate or use Skuid’s default certificate.
- If your system requires an RSA public key as opposed to a certificate file, choose Download RSA Public Key.
- Configure an OAuth application in your external system.
- Upload the Skuid site’s certificate to your external system as part of the OAuth app configuration.
- This is typically labeled something like Use digital signatures within most systems.
- Create an authentication provider with this grant type.
- Enter the OAuth app’s client ID and client secret within the authentication provider.
- Configure the custom claims as needed for the external system.
Properties¶
Standard Claims: A set of claims that are reserved under the JWT spec for specific pieces of information. These claims are sent with every JWT and cannot be changed, regardless of settings.
Custom Claims: A set of additional claims that are passed along in each JWT. The values entered here vary depending on the service you’re connecting to. You can append various types of claims, even arrays, using the JSON builder on the screen.
Custom claims may contain both merge variables, such as the $User merge variable, and formula functions to allow for retrieving and transforming data you may need to pass to your service.
JWT Signing Algorithm: The cryptographic algorithm used to digitally sign each JWT sent by Skuid.
Signing Certificate: The certificate used to sign each JWT.
Resource Owner Password Credentials Grant [[]]¶
In this grant flow, the resource trusts the client enough to give away its credentials.
Key Takeaways
- Stores credentials in Salesforce
- End users do not have to enter credentials often
What happens in this grant flow [[]]¶
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"
}
|
AWS: Assume Role with ARN¶
This authentication method allows you to use the ARN of an assumable role instead of hard-coded AWS access keys. When a Skuid user makes a request using this authentication method, Skuid makes a secure server-side request to assume the configured role. If this request is successful, Skuid receives temporary access credentials, which Skuid caches until the credentials expire after 60 minutes.
Requests made through an assumed role are traceable via the AWS console. From there, you can see both the Skuid site and Skuid user who initiated the request, which provides AWS administrators full visibility into who requested access credentials and from what Skuid site.
Due to this method’s security and ease-of-management after initial setup, we typically recommend it over the access keys method. However, it does require some technical knowledge to configure. Be sure to read all of the instructions below.
Before you begin
Skuid can only access roles that have a defined path containing the string /skuid-assumable-role/
. This is different from the role’s name. Role paths can only be set when first created, so it isn’t possible to update an existing role with a new path.
In order to create a role with a path, you’ll need to use either the AWS IAM API or the AWS CLI.
The instructions below assume you are using AWS CLI (version 2) and that you’ve already configured an access key ID and secret access key for use with the CLI. Ensure these credentials have the iam:CreateRole
permission. Command line examples are also tailored for Linux or macOS operating systems; commands for command line programs on Windows may differ.
Finally, because IAM roles require a trust relationship policy upon creation, you’ll need to save the JSON that Skuid provides when creating an authentication provider. Because of this you’ll need to navigate between your browser window, your computer’s file explorer, as well as the command line.
In Skuid
- From the Skuid navigation bar, navigate to Data Sources > Authentication Providers.
- Click Create.
- Configure the authentication provider’s basic properties:
- Name: Enter a name, such as AWSAuth.
- Authentication Method: AWS: Assume Role with ARN
- In the Trust Relationship Policy, click Copy to Clipboard.
This copied policy will enable your role to grant proper access to your Skuid site.
Note
If you want this role to be assumable by multiple Skuid sites—for example a staging site and a production site, make the sts:ExternalId property
’s value into an array of Skuid site Ids.
For example, change this key/value:
"sts:ExternalId": "09583eba-de0e-49d3-ae42-61b3927a61b1"
Into this:
"sts:ExternalId": [
"09583eba-de0e-49d3-ae42-61b3927a61b1",
"e354e60f-5a80-4024-b01a-4cae13d0948c"
]
Site IDs are accessible from Settings > Site > Profile.
On your local machine
- With the policy copied to your clipboard, paste the policy into a text editor.
- Save the file to an easily accessible directory (for example, your desktop) on your machine with a recognizable name and the JSON file extension, like trust-policy.json
In a command line interface
With the trust policy saved to your machine, you can now use the AWS CLI to create an assumable role.
Open your command line program of choice and navigate to the directory containing your policy JSON file. For example, if you saved the file on your desktop:
1
cd ~/Desktop
Use the AWS CLI’s
iam create-role
command to create the role with the proper path value and trust relationship policy:1
aws iam create-role --role-name Skuid-S3-Access --path /skuid-assumable-role/ --assume-role-policy-document file://trust-policy.json
Note
While
role-name
can vary from this example, thepath
must contain/skuid-assumable-role/
The CLI creates the role, outputting its ARN and other related metadata. Because of the configured path, your ARN should look similar to this:
arn:aws:iam::1234567891011:role/skuid-assumable-role/Skuid-S3-Access
.Copy this created ARN, either from the command line output or the AWS console.
In Skuid
- Return to the authentication provider window.
- Paste the copied ARN into the AWS Role ARN to assume field.
- Click Save.
AWS: Access Keys¶
This authentication method utilizes an Amazon Web Service (AWS) IAM role’s access keys to authenticate to an AWS system.
If you are not the manager of your AWS services, follow along with Amazon’s steps for creating access keys with your IT administrator. You’ll need to do the following:
In AWS
- Create a new group and select the appropriate policies for that group.
- These should align with your intended Skuid use. Ensure your access policies match the services (S3, DynamoDB, or SNS) you’ll be using.
- Create a new user in AWS Identity and Access Management (IAM) within the newly created group.
- Retrieve the access credentials generated for that user:
- The secret access key is only displayed once, immediately after the access key is generated, and cannot be found later. Be sure to copy it to a safe place.
In Skuid
With your access credentials handy, you can now use them to configure a Skuid authentication provider that will work with all AWS data sources.
- Navigate to Configure > Data Sources > Authentication Providers.
- Click New Authentication Provider.
- Configure the authentication provider’s basic properties:
- Name: Enter a name, such as AWSAuth.
- Authentication Method: AWS: Access Keys
- Enter your IAM role’s credential information:
- AWS Access Key Id: The access key ID to use when authenticating.
- AWS Secret Access Key: The secret access key to use when authenticating.
- Click Save.
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:
1 | 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();
Authentication Merge Variables¶
{{Auth.API_Key}}
: A reference to the API key stored when API Key Authentication is selected for a data source. When used, Skuid injects the stored value on the server-side, so users cannot see the value. For more information, see the API Key Authentication section.
{{$Auth.BasicAuth}}
{{$Auth.Username}}
{{$Auth.Password}}
{{$Auth.Response.Body}}
: Contains the values returned by the authentication request’s response. It’s possible to target specific body parameters by appending the parameter to the end of the merge variable. For example: {{$Auth.Response.Body.access_token}}
would return the access_token
parameter value included in the authentication request’s response.
{{$Auth.Response.Headers}}
: Contains the values returned by the authentication request’s response. It’s possible to target specific header parameters by appending the parameter to the end of the merge variable. For example: {{$Auth.Response.Headers.Expires}}
would return the Expires
header value included in the authentication request’s response.
{{$Api.Session_Id}}
Encryption in Skuid¶
The following fields are stored encrypted in Skuid:
- Data Source (for org-wide credentials)
- Username
- Password
- API key
- Per-profile or per-user username
- Per-profile or per-user password
- Authentication Provider
- Client Id
- Client Secret