trailhead

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

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 client_id.
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

  1. The customer opens a Mobile SDK app.
  2. An authentication prompt appears.
  3. The customer enters a username and password.
  4. The app sends the customer’s credentials to Salesforce and, in return, receives a session ID as confirmation of successful authentication.
  5. The customer approves the app’s request to grant access to the app.
  6. The app starts.

Ongoing Authorization

  1. The customer opens a mobile app.
  2. 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.
  3. 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

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:
  1. Customer turns on a phone and enters the PIN for the device.
  2. Customer launches a Mobile SDK app.
  3. Customer enters login information for Salesforce organization.
  4. Customer enters PIN code for the Mobile SDK app.
  5. Customer works in the app and then sends it to the background by opening another app (or receiving a call, and so on).
  6. The app times out.
  7. Customer reopens the app, and the app PIN screen displays (for the Mobile SDK app, not the device).
  8. Customer enters app PIN and can resume working.

OAuth2 User-Agent Flow

The user-agent authentication flow is used by client applications residing on the user’s mobile device. The authentication is based on the user-agent’s same-origin policy.

In the user-agent flow, the client app receives the access token as an HTTP redirection. The client app requests the authorization server to redirect the user-agent to another web server or to an accessible local resource. The server can extract the access token from the response and pass it to the client app. For security, the token response is provided as a hash (#) fragment on the URL. It prevents the token from being passed to the server or to any other servers in referral headers.

The user-agent authentication flow doesn’t use the client secret because the client executables reside on the user’s device, which makes the client secret accessible and exploitable.
Warning

Warning

Because the access token is encoded into the redirection URI, it might be exposed to the user and other apps residing on the device.

User agent flow
  1. The client app directs the user to Salesforce to authenticate and authorize the app.
  2. The user approves access for this authentication flow.
  3. The app receives the callback from Salesforce.

After obtaining an access token, the consumer can use the access token to access data on the end-user’s behalf and receive a refresh token. Refresh tokens let the consumer get a new access token if the access token becomes invalid for any reason.

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 scopes 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—Define scope requests in your Mobile SDK app. Client scope requests must be a subset of the connected app’s scope permissions.

Server Side Configuration

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

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 request.

api

Include in your request if you’re  making any Salesforce REST API calls (applies to most apps).

web

Include in your request if your app accesses pages defined in a Salesforce org (for any app that loads Salesforce-based web pages.)

full

Include if you wish to request all permissions. (Mobile SDK implicitly requests refresh_token for you.)

chatter_api

Include in your request 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.

  1. In your Trailhead Playground or Developer Edition org, go to Setup.
  2. 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.
  3. 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
  4. Under API (Enable OAuth Settings), check Enable OAuth Settings.
  5. 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.
  6. Under Available OAuth Scopes, select:
    • Access and manage your data (api)
    • Provide access to your data via the Web (web)
    • Perform requests on your behalf at any time (refresh_token, offline_access)
    This minimal set of scopes works well for most Mobile SDK apps.
  7. Click Add.
  8. 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.

retargeting