Security and the API

Client applications that access your organization's Salesforce data are subject to the same security protections that are used in the Salesforce user interface. Additional protection is available for organizations that install Force.comAppExchange managed packages if those packages contain components that access Salesforce via the API.

User Authentication

Client applications must log in using valid credentials for an organization. The server authenticates these credentials and, if valid, provides the client application with:

a sessionId that must be set into the session header so that all subsequent calls to the Web service are authenticated

a URL address (serverUrl) for the client application's Web service requests

Salesforce supports only the Secure Sockets Layer (SSL) protocol SSLv3, the Transport Layer Security (TLS) protocol, and frontdoor.jsp. Ciphers must have a key length of at least 128 bits.

User Profile and Permission Sets Configuration

An organization's Salesforce administrator controls the availability of various features and views by configuring profiles and permission sets, and assigning users to them. To access the API (to issue calls and receive the call results), a user must be granted the “API Enabled” permission. Client applications can query or update only those objects and fields to which they have access via the permissions of the logged-in user.

The Web services WSDL files return all available objects and fields for an organization.

Security Token

When users log in to Salesforce, either via the user interface, the API, or a desktop client such as Connect for Outlook, Salesforce for Outlook, Connect Offline, Connect for Office, Connect for Lotus Notes, or the Data Loader, Salesforce confirms that the login is authorized as follows:

Salesforce checks whether the user’s profile has login hour restrictions. If login hour restrictions are specified for the user’s profile, any login outside the specified hours is denied.

If the user has the “Two-Factor Authentication for User Interface Logins” permission, Salesforce prompts the user for a time-based token (which the user may also be prompted to create if it hasn’t already been added to the account) upon logging in.

If the user has the “Two-Factor Authentication for API Logins” permission and a time-based token has been added to the account, Salesforce returns an error if a time-based token is not used to access the service in place of the standard security token.

Salesforce then checks whether the user’s profile has IP address restrictions. If IP address restrictions are defined for the user’s profile, any login from an undesignated IP address is denied, and any login from a specified IP address is allowed.

If profile-based IP address restrictions are not set, Salesforce checks whether the user is logging in from an IP address they have not used to access Salesforce before:

If the user’s login is from a browser that includes a Salesforce cookie, the login is allowed. The browser will have the Salesforce cookie if the user has previously used that browser to log in to Salesforce, and has not cleared the browser cookies.

If the user’s login is from an IP address in your organization’s trusted IP address list, the login is allowed.

If the user’s login is from neither a trusted IP address nor a browser with a Salesforce cookie, the login is blocked.

Whenever a login is blocked or returns an API login fault, Salesforce must verify the user’s identity:

For access via the user interface, the user is prompted to enter a token (also called a verification code) to confirm the user’s identity.

Note

Users aren’t asked for a verification code the first time they log in to Salesforce.

For access via the API or a client, users must add their security token (or time-based token if Two-Factor Authentication on API Logins is set on the user’s profile and the user has added a time-based token to his or her account) to the end of their password in order to log in.

A security token is an automatically-generated key from Salesforce. For example, if a user’s password is mypassword, and the security token is XXXXXXXXXX, then the user must enter mypasswordXXXXXXXXXX to log in. Or, some client applications have a separate field for the security token.

Users can obtain their security token by changing their password or resetting their security token via the Salesforce user interface. When a user changes their password or resets their security token, Salesforce sends a new security token to the email address on the user’s Salesforce record. The security token is valid until a user resets their security token, changes their password, or has their password reset.

Tip

We recommend that you obtain your security token using the Salesforce user interface from a trusted network prior to attempting to access Salesforce from a new IP address.

For more information about tokens, see “Resetting Your Security Token” in the Salesforce online help.

When a user's password is changed, the user's security token is automatically reset. The user will experience a blocked login until he or she adds the automatically-generated security token to the end of his or her password or enters the new password after the administrator adds their IP address to the organization's list of trusted IP addresses.

If Single Sign-On (SSO) is enabled for your organization, users who access the API or a desktop client cannot log in to Salesforce unless their IP address is included on your organization's list of trusted IP addresses or on their profile, if their profile has IP address restrictions set. Futhermore, the delegated authentication authority usually handles login lockout policies for users with the “Uses Single Sign-On” permission. However, if the security token is enabled for your organization, then your organization's login lockout settings determine the number of times a user can attempt to log in with an invalid security token before being locked out of Salesforce. For more information, see “Setting Login Restrictions” and “Setting Password Policies” in the online help.

Sharing

In the Salesforce user interface, sharing refers to the act of granting read or write access to a user or group so that they can view or edit a record owned by other users, if the default organization access levels do not otherwise permit such access. All API calls respect the sharing model.

The following table describes the types of access levels.

API Value

Salesforce User Interface Label

API Picklist Label

Description

None

Private

Private

Only the record owner and Users above that role in the hierarchy can view and edit the record.

Read

Read Only

Read Only

All Users and Groups can view the record but not edit it. Only the owner and users above that role in the hierarchy can edit the record.

Implicit Restrictions for Objects and Fields

Certain objects can be created or deleted only in the Salesforce user interface. Other objects are read-only—client applications cannot create(), delete(), or update() such objects. Similarly, certain fields within some objects can be specified on create() but not on update(). Other fields are read-only—client applications cannot specify field values in create() or update() calls. For more information, see the respective object descriptions in Standard and Custom Object Basics.

API Access in Force.com AppExchange Packages

The API allows access to objects and calls based on the permissions of the user who logs into the API. To prevent security issues from arising when installed packages have components that access data via the API, Salesforce provides additional security:

When a developer creates an AppExchange package with components that access the API, the developer can restrict the API access for those components.

When an administrator installs an AppExchange package, the administrator can accept or reject the access. Rejecting the access cancels the installation.

After an administrator installs a package, the administrator can restrict the API access of components in the package that access the API.

Editing API access for a package is done in the Salesforce user interface. For more information, see “Managing API and Dynamic Apex Access in Packages” in the Salesforce online help.

API access for a package affects the API requests originating from components within the package; it determines the objects that the API requests can access. If the API access for a package is not defined, then the objects that the API requests have access to are determined by the user's permissions.

The API access for a package never allows users to do more than the permissions granted to the user. API access in a package only reduces what the user's permissions allow.

Choosing Restricted for the API Access setting in a package affects the following:

API access in a package overrides the following user permissions:

Author Apex

Customize Application

Edit HTML Templates

Edit Read Only Fields

Manage Billing

Manage Call Centers

Manage Categories

Manage Custom Report Types

Manage Dashboards

Manage Letterheads

Manage Package Licenses

Manage Public Documents

Manage Public List Views

Manage Public Reports

Manage Public Templates

Manage Users

Transfer Record

Use Team Reassignment Wizards

View Setup and Configuration

Weekly Export Data

If Read, Create, Edit, and Delete access are not selected in the API access setting for objects, users do not have access to those objects from the package components, even if the user has the “Modify All Data” and “View All Data” permissions.

A package with Restricted API access can’t create new users.

Salesforce denies access to Web service and executeanonymous requests from an AppExchange package that has Restricted access.

The following considerations also apply to API access in packages:

Workflow rules and Apex triggers fire regardless of API access in a package.

If a component is in more than one package in an organization, API access is unrestricted for that component in all packages in the organization regardless of the access setting.

If Salesforce introduces a new standard object after you select restricted access for a package, access to the new standard object is not granted by default. You must modify the restricted access setting to include the new standard object.

When you upgrade a package, changes to the API access are ignored even if the developer specified them. This ensures that the administrator installing the upgrade has full control. Installers should carefully examine the changes in package access in each upgrade during installation and note all acceptable changes. Then, because those changes are ignored, the administrator should manually apply any acceptable changes after installing an upgrade.

S-controls are served by Salesforce and rendered inline in Salesforce. Because of this tight integration, there are several means by which an s-control in an installed package could escalate its privileges to the user’s full privileges. In order to protect the security of organizations that install packages, s-controls have the following limitations:

For packages you are developing (that is, not installed from AppExchange), you can only add s-controls to packages with the default UnrestrictedAPI access. Once a package has an s-control, you cannot enable RestrictedAPI access.

For packages you have installed, you can enable access restrictions even if the package contains s-controls. However, access restrictions provide only limited protection for s-controls. Salesforce recommends that you understand the JavaScript in an s-control before relying on access restriction for s-control security.

If an installed package has RestrictedAPI access, upgrades will be successful only if the upgraded version does not contain any s-controls. If s-controls are present in the upgraded version, you must change the currently installed package to UnrestrictedAPI access.

To manage API access to packages, see “Managing API and Dynamic Apex Access in Packages” in the Salesforce online help.

Note

XML-RPC requests that originate from restricted packages will be denied access.

Outbound Port Restrictions

For security reasons, Salesforce restricts the outbound ports you may specify to one of the following:

80: This port only accepts HTTP connections.

443: This port only accepts HTTPS connections.

1024–66535 (inclusive): These ports accept HTTP or HTTPS connections.

The port restriction applies to any feature where a port is specified, for example outbound messages, AJAX proxy, or single-sign on.