Security and 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.com supports only the Secure Sockets Layer (SSL) protocol SSLv3 and the Transport Layer Security (TLS) protocol. Ciphers must have a key length of at least 128 bits.

User Profile Configuration

An organization's Salesforce.com administrator controls the availability of various features and views by configuring profiles 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” profile permission. Client applications can query or update only those objects and fields to which they have access via the profile of the logged-in user.

To create, edit, or delete a profile, go to Setup | Manage Users | Profiles in the Salesforce.com user interface.

Note

The Force.com Web Services WSDL files return all available objects and fields for an organization.

Security Token

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

Salesforce.com 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.
Salesforce.com 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.com checks whether the user is logging in from an IP address they have not used to access Salesforce.com before:
- If the user's login is from a browser that includes a Salesforce.com cookie, the login is allowed. The browser will have the Salesforce.com cookie if the user has previously used that browser to log in to Salesforce.com, 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.com cookie, the login is blocked.

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

For access via the user interface, the user is prompted to click a Send Activation Link button to send an activation email to the address specified on the user's Salesforce.com record. The email instructs the user to copy and paste an activation link into their browser to activate their computer for logging in to Salesforce.com. The activation link included in the email is valid for up to 24 hours from the time the user clicked the Send Activation Link button. After 24 hours, the activation link expires, and users must repeat the activation process to log in.
Note
The first time a user logs into Salesforce.com, they do not have to activate their computer. However, the next time a user logs in, they must activate their computer using the Send Activation Link button.
For access via the API or a client, the user must add their security token to the end of their password in order to log in. A security token is an automatically-generated key from Salesforce.com. For example, if a user's password is mypassword, and their security token is XXXXXXXXXX, then the user must enter mypasswordXXXXXXXXXX to log in.
Users can obtain their security token by changing their password or resetting their security token via the Salesforce.com user interface. When a user changes their password or resets their security token, Salesforce.com sends a new security token to the email address on the user's Salesforce.com record. The security token is valid until a user resets their security token, changes their password, or has their password reset.
Tip
It is recommended that you obtain your security token via the Salesforce.com user interface from a trusted network prior to attempting to access Salesforce.com from a new IP address.

Note

For more information about tokens, see “Resetting Your Security Token” in the Salesforce.com 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.com 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.com. For more information, see “Setting Login Restrictions” and “Setting Password Policies” in the online help.

Sharing

In the Salesforce.com 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.com 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.
Edit	Read/Write	Read/Write	All Users and Groups can view and edit the record.
ReadEditTransfer	Read/Write/Transfer	Read/Write/Transfer	All Users and Groups can view, edit, delete, and transfer the record. (Only available for cases and leads as an organization-wide default setting.)
All	Full Access	Owner	All Users and Groups can view, edit, transfer, delete, and share the record. (Only available for campaigns as an organization-wide default setting.)
ControlledByParent	Controlled by Parent	Controlled By Parent	(Contacts only.) All Users and Groups can perform an action (such as view, edit, or delete) on the contact based on whether he or she can perform that same action on the record associated with it.

Not all access levels are available for every object. See the Fields table for each object to learn which access levels are available, as well as other sharing details specific to that object.

For more information about sharing in general, see the Salesforce.com online help.

Note

In the API, you can create and update objects such as AccountShare and OpportunityShare that define sharing entries for records.

Implicit Restrictions for Objects and Fields

Certain objects can be created or deleted only in the Salesforce.com 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.com 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.com user interface. For more information, see “Managing API and Dynamic Apex Access in Packages” in the Salesforce.com 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 profile permissions.

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

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

API access in a package overrides the following permissions granted in a user's profile:
- 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.
Salesforce.com denies access to Web service and executeanonymous requests from an AppExchange package that has Restricted access. For more information about executeanonymous and accessing Web services with Apex, see the Force.comApex Code Developer's Guide.

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.com 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.com and rendered inline in Salesforce.com. 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.com 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.com online help.

Note

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

Outbound Port Restrictions

For security reasons, Salesforce.com 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.
7000-10000 (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.