Understand Security and Authentication
Learning Objectives
After completing this unit, you'll be able to:
- Understand the methods of security and authentication used in Salesforce apps.
- Understand the use of connected apps for integrating mobile apps with the Salesforce server.
- Understand basic OAuth terminology.
- Understand the flow of events in OAuth authentication and PIN security.
About Security and Authentication
Secure authentication is essential for enterprise applications running on mobile devices. OAuth 2.0, the industry-standard protocol, enables secure authorization for access to a customer’s data, without handing out the username and password. It is often described as the valet key of software access. A valet key restricts access to certain features of your car. For example, a parking attendant can’t open the trunk or glove compartment using a valet key.
Mobile app developers can quickly and easily embed the Salesforce OAuth 2.0 implementation. The implementation uses an HTML view to collect the username and password, which are then sent to the server. The server returns a session token and a persistent refresh token that are stored on the device for future interactions.
A Salesforce connected app is the primary means by which a mobile app connects to Salesforce. A connected app gives both the developer and the administrator control over how the app connects and who has access. For example, a connected app can restrict access to a set of customers, set or relax an IP range, and so on.
OAuth Terminology
If you’re feeling lost, this list can help you find your way. These labels, considered together, lead directly to OAuth nirvana.
Note
The term “consumer” in this list always refers to a Mobile SDK app. A humanoid consumer, on the other hand, is called a “user” or “end user.”
Consumer Key |
A value used by the consumer—in this case, the Mobile SDK app—to identify itself to Salesforce. Referred to as |
|---|---|
Access Token |
A value used by the consumer to gain access to protected resources on behalf of the user, instead of using the user’s Salesforce credentials. The access token is a session ID, and can be used directly. |
Refresh Token |
A token used by the consumer to obtain a new access token, without having the end user approve the access again. |
Authorization Code |
A short-lived token that represents the access granted by the end user. The authorization code is used to obtain an access token and a refresh token. |
Connected App |
An application external to Salesforce that uses the OAuth protocol to verify both the Salesforce user and the external application. |
OAuth2 Authentication Flow
The flow of events during OAuth authorization depends on the state of authentication on the device.
First Time Authorization Flow
- The customer opens a Mobile SDK app.
- An authentication prompt appears.
- The customer enters a username and password.
- The app sends the customer’s credentials to Salesforce and, in return, receives a session ID as confirmation of successful authentication.
- The customer approves the app’s request to grant access to the app.
- The app starts.
Ongoing Authorization
- The customer opens a mobile app.
- If the session ID is active, the app starts immediately. If the session ID is stale, the app uses the refresh token from its initial authorization to get an updated session ID.
- The app starts.
PIN Security
Salesforce connected apps have an additional layer of security via PIN protection on the app. This PIN protection is for the mobile app itself, and isn’t the same as the PIN protection on the device or the login security provided by the Salesforce organization.
In order to use PIN protection, the developer must select the Implements Screen Locking & Pin Protection checkbox when creating the connected app. Mobile app administrators then have the options of enforcing PIN protection, customizing timeout duration, and setting PIN length.
Note
Because PIN security is implemented in the mobile device’s operating system, this feature isn’t available in HTML5 Web apps.
In practice, PIN protection can be used so that the mobile app locks up if it isn’t used for a specified number of minutes. When a mobile app is sent to the background, the clock continues to tick.
To illustrate how PIN protection works:
- Customer turns on a phone and enters the PIN for the device.
- Customer launches a Mobile SDK app.
- Customer enters login information for Salesforce organization.
- Customer enters PIN code for the Mobile SDK app.
- Customer works in the app and then sends it to the background by opening another app (or receiving a call, and so on).
- The app times out.
- Customer reopens the app, and the app PIN screen displays (for the Mobile SDK app, not the device).
- Customer enters app PIN and can resume working.
OAuth2 User-Agent Flow
In the user-agent flow, the connected app, which integrates the client app with the Salesforce API, receives the access token as an HTTP redirection. The connected app requests that the authorization server redirects the user-agent to a web server or to an accessible local resource. The web server can extract the access token from the response and pass it to the connected app. For security, the token response is provided as a hash tag (#) fragment on the URL. This format prevents the token from being passed to the server or to any other servers in referral headers.
Warning
Because the access token is encoded into the redirection URL, it can be exposed to the user and other apps on the device.
Note
Connected apps for these types of clients can protect per-user secrets. However, the client secret is accessible and exploitable because client executables reside on the user’s device. For this reason, the user-agent flow doesn’t use the client secret. Authorization is based on the user-agent’s same-origin policy. Also, the user-agent flow doesn’t support out-of-band posts.
For example, you use Salesforce Mobile SDK to build a mobile app that looks up customer contact information from your Salesforce org. Mobile SDK implements the OAuth 2.0 user-agent flow for your connected app, integrating the mobile app with your Salesforce API and giving it authorized access to the defined data. The flow follows these steps.
- The end user opens the mobile app.
- The connected app directs the user to Salesforce to authenticate and authorize the mobile app.
- The user approves access for this authorization flow.
- The connected app receives the callback from Salesforce to the redirect URL, which extracts the access and refresh tokens.
- The connected app uses the access token to access data on the end user’s behalf.
Connected Apps
A connected app integrates an application with Salesforce using APIs. Connected apps use standard SAML and OAuth protocols to authenticate, provide single sign-on, and provide tokens for use with Salesforce APIs. In addition to standard OAuth capabilities, connected apps allow Salesforce admins to set various security policies and have explicit control over who can use the corresponding apps.
Here’s a general list of information that you provide when you create a connected app.
- Name, description, logo, and contact information
- URL where Salesforce can locate the app for authorization or identification
- Authorization protocol: OAuth, SAML, or both
- IP ranges from where users can log in to connected app (optional)
- Information about mobile policies that the connected app can enforce (optional)
Salesforce Mobile SDK apps use connected apps to access Salesforce OAuth services and to call Salesforce REST APIs.
Scope Parameter Values
OAuth requires scope configuration both on server and on client. The agreement between the two sides defines the scope contract.
-
Server side—Define scope permissions in a connected app on the Salesforce server. These settings determine which levels of access client apps, such as Mobile SDK apps, can request. At a minimum, configure your connected app OAuth settings to match what’s specified in your code. For most apps, refresh_token, web, and api are sufficient.
-
Client side—Specify scope requests in your Mobile SDK app. Client scope requests must be a subset of the connected app’s scope permissions.
Server Side Configuration
You can set the following scope parameter values.
Value |
Description |
|---|---|
api |
Allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API. This value also includes chatter_api, which allows access to Chatter REST API resources. |
chatter_api |
Allows access to Chatter REST API resources only. |
custom_permissions |
Allows access to the custom permissions in an organization associated with the connected app, and shows whether the current user has each permission enabled. |
full |
Allows access to all data accessible by the logged-in user, and encompasses all other scopes. full does not return a refresh token. You must explicitly request the refresh_token scope to get a refresh token. |
id |
Allows access to the identity URL service. You can request profile, email, address, or phone, individually to get the same result as using id; they are all synonymous. |
openid |
Allows access to the current, logged in user’s unique identifier for OpenID Connect apps. Use the openid scope in the OAuth 2.0 user-agent flow and the OAuth 2.0 web server authentication flow to receive a signed ID token conforming to the OpenID Connect specifications in addition to the access token. |
refresh_token |
Allows a refresh token to be returned when you are eligible to receive one. Then the app can interact with the user’s data while the user is offline, and is synonymous with requesting offline_access. |
visualforce |
Allows access to customer-created Visualforce pages. Doesn’t allow access to standard Salesforce UIs. |
web |
Allows the ability to use the access_token on the web, and includes visualforce, allowing access to customer-created Visualforce pages. |
Note
For Mobile SDK apps, you’re always required to select refresh_token in server-side Connected App settings. Even if you select the full scope, you still must explicitly select refresh_token.
Client Side Configuration
The following rules govern scope configuration for Mobile SDK apps.
Scope |
Mobile SDK App Configuration |
|---|---|
refresh_token |
Implicitly requested by Mobile SDK for your app; no need to include in your app’s list of scopes. |
api |
Include if you’re making any Salesforce REST API calls (applies to most apps). |
web |
Include if your app accesses pages defined in a Salesforce org (for any app that loads Salesforce-based web pages.) |
full |
Include to request all permissions. (Mobile SDK implicitly requests refresh_token for you.) |
chatter_api |
Include if your app calls Chatter REST APIs. |
id |
(Not needed) |
visualforce |
Use web instead. |
Creating a Connected App
Creating a connected app is simple but requires administrator rights. In your own Developer Edition or Trailhead Playground org, you’re automatically granted these permissions.
- In your Trailhead Playground or Developer Edition org, go to Setup.
- Do one of the following steps.
- If you’re using Salesforce Classic, select Create | Apps, scroll to Connected Apps, and click New.
- If you’re using Lightning Experience, select Apps | App Manager, and click New Connected App.
- Under Basic Information, fill out the form as follows:
-
Connected App Name: <whatever you like; can contain spaces>
-
API Name: accept the suggested value
-
Contact Email: enter your email address
- Under API (Enable OAuth Settings), check Enable OAuth Settings.
- Set Callback URL to: <any URL string, real or fictional, such as mysampleapp://auth/success>. If autofill offers a suggestion, do not accept it. Instead, type in the callback URL.
- Under Available OAuth Scopes, select:
-
Manage user data via APIs (api)
-
Manage user data via Web browsers (web)
-
Perform requests at any time (refresh_token, offline_access)
- Click Add. This minimal set of scopes works well for most Mobile SDK apps.
- Uncheck Require Secret for Web Server Flow.
- Click Save.
After you save the configuration, notice the details of your new connected app.
- The Callback URL and the Consumer Key. You copy these values into your Mobile SDK app configuration before you distribute the app.
- Mobile SDK apps do not use the consumer secret, so you can ignore this value.
Now that you know a bit about Mobile SDK architecture and security, it’s time for you to get hands-on with Mobile SDK. You can start by completing the following challenge, which requires only a Developer Edition or Trailhead Playground. Afterward, we recommend that you complete the Set Up Your Mobile SDK Developer Tools project.
Resources