Identity and Access Management
Client
An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).
OAuth 2.0 Authentication Endpoints
OAuth endpoints are the URLs that you use to make OAuth authentication requests to Salesforce. When your application makes an authentication request, make sure you're using the correct Salesforce OAuth endpoint. The primary endpoints are: Authorization—https://login.salesforce.com/services/oauth2/authorize Token—https://login.salesforce.com/services/oauth2/token Revoke—https://login.salesforce.com/services/oauth2/revoke (see Revoke OAuth Tokens for details on revoking access) Instead of login.salesforce.com, customers can also use the My Domain, community, or test.salesforce.com (sandbox) domains in these endpoints.
Refresh Token
A refresh token can have an indefinite lifetime, persisting for an admin-configured interval or until explicitly revoked. The client application can store a refresh token, using it to periodically obtain fresh access tokens. For this reason, the app must protect a refresh token against unauthorized access. Like a password, a refresh token can be used repeatedly to gain access to the resource server. Because a refresh token can expire or a user can revoke it outside of the client, the client must handle failures to obtain an access token. Typically, the client replays the protocol from the start.
Configuring a Connected App with OAuth
All types of OAuth 2.0 flows, except for the SAML Assertion flow, require that you define a connected app. 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. The developer creates the connected app and defines the API integration, providing OAuth metadata about the app, such as: Basic descriptive and contact information for the connected app The OAuth scopes and callback URL for the connected app The admin defines policies for the app, including: Optional IP ranges where the connected app can run Optional information about mobile policies that the connected app can enforce The connected app wizard walks you through the steps to create a connected app. To configure OAuth settings, select Enable OAuth Settings to open the API section and supply the required metadata, including the callback URL. The callback URL is an endpoint in your application to which Salesforce can redirect the user's browser with an authentication code or access token. To protect the token, the only hostname allowed with an HTTP callback URL is localhost. Other hosts must use HTTPS. Alternatively, you can specify a URI with a custom URI scheme. This approach is often used in a User-Agent flow to pass control back to a native application. If you're using the JWT Bearer Token or SAML Bearer Assertion flows, select Use Digital Signatures and upload a signing certificate. After you save the connected app definition, you are provided an OAuth client ID key and client secret for the connected app.
Resource Owner
An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
OAuth 2.0 Web Server Authentication Flow
Apps hosted on a secure server use the web server authentication flow. A critical aspect of the web server flow is that the server must be able to protect the client secret. This flow uses an OAuth 2.0 authorization code grant type. Users can authorize an app to access Salesforce more than once, for example, for a laptop and a desktop computer. The default is five authorizations per app per user. If a user tries to grant access to an app after reaching the org's limit, the least-recently used access token is revoked. Newer OAuth 2.0 apps using the Web Server flow are approved for more devices after the user has been granted access once.
When Can Users Be Prompted for Two-Factor Authentication?
Every time they log in to Salesforce, including API logins. When they access a connected app, dashboard, or report. This process is known as step-up or high-assurance authentication. During a custom login flow or within a custom app, for example, before reading a license agreement. More on this topic later in the trail.
Self-Registration
For B2C Communities, it often makes sense to let visitors self-register. The self-registration user flow is as follows: The visitor clicks or gets redirected to the Self-Registration page The visitor fills in the form and submits his information Salesforce creates Contact and User records If the user profile has been previously added to the community, the user gets instant access to the community Optionally, he receives an email (option needs to be selected in setup) Self-Registration can be set up in three steps: 1. Enable Self-Registration in the Community Go to the Communities setup overlay, select the "Login Page" tab, and enable Self-Registration. Optionally, select a default profile to assign to self-registered users. Only profiles that were previously added to the community are shown. 2. Customize Self-Registration Code Edit the CommunitiesSelfRegController to include the Account ID you want to associate self-registered users with. This step is mandatory. If you're creating a user associated to a license that does not have roles (e.g.: Customer Community), you're done. Otherwise, you need to assign a role to the new user. Note that there's a known issue that forces all self-registered users to be associated with the lowest role in the hierarchy. In this example, we did not assign a profile ID to profileID because we've already associated a profile in the Self-Reg Communities setup. Setting a value in the controller will overwrite the default Self-Reg profile. 3. Customize Self-Registration pages We provide a default Self-Registration page called CommunitiesSelfReg that you can customize and brand as needed. If a user doesn't create a password during self-registration—either because they left the password field blank or your organization customized the self-registration form to omit the password field—the CommunitiesSelfRegConfirm page and CommunitiesSelfRegConfirm controller confirm that a password reset email has been sent. Users landing on this page can't log in until they reset their password.
ID Token
OpenID Connect, an authentication layer on top of OAuth 2.0, defines an ID token as a signed data structure. The data structure contains authenticated user attributes (including a unique identifier for the user), the time when the token was issued, and an identifier for the requesting client. An ID token is encoded as a JSON web token (JWT).
Social Sign-On Provisioning
Social Sign-On enables users to authenticate from a range of identity providers, including Facebook, Google, Microsoft, Amazon, Paypal, any OpenID Connect provider, and even other salesforce.com orgs ( future plans include support for LinkedIn and Twitter as well ). Social sign-on is key to a new way of acquiring prospects, and servicing customers. As part of the process users are created or updated on the fly using Registration Handlers.
OAuth 2.0 SAML Bearer Assertion Flow
The OAuth 2.0 SAML bearer assertion flow defines how a SAML assertion can be used to request an OAuth access token when a client wants to use a previous authorization. Authentication of the authorized app is provided by the digital signature applied to the SAML assertion. Bearer flows can be used only after the consumer has received a refresh token.
SAML Assertion Flow
The SAML assertion flow is an alternative for orgs that are currently using SAML to access Salesforce and want to access the web services API the same way. You can use the SAML assertion flow only inside a single org. You don't have to create a connected app to use this assertion flow. Clients can use this assertion flow to federate with the API using a SAML assertion, the same way they federate with Salesforce for web single sign-on.
Authorization Code Grant Type
The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.
Authorization Token
The authorization server creates this short-lived token and passes it to the client application via the browser. The client application sends the authorization code to the authorization server to obtain an access token and , optionally, a refresh token.
Access Token
The client uses an access token to make authenticated requests on behalf of the end user. It has a longer lifetime than the authorization code, usually minutes or hours. When an access token expires, attempts to use it fail, and the app must obtain a new access token. In Salesforce terms, the access token is a session Id (SID), much like a session cookie on other systems. It must be protected against interception, for example, by Transport Layer Security (TLS, also called SSL). To use an OAuth access token to access Salesforce web UI on behalf of a user, you can either set a SID cookie or use a "front door" URL (such as https://mydomain.salesforce.com/secur/frontdoor.jsp?sid=<sid value> ). In both cases, you must include "web" in the list of requested scopes.
OAuth 2.0 Device Authentication Flow
The device authentication flow is typically used by applications on devices with limited input or display capabilities, such as TVs, appliances, or command-line applications. Users can connect these client applications to Salesforce by accessing a browser on a separate device that has more developed input capabilities, such as a desktop computer or smartphone.
Implicit Grant Type
The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server. Unlike the authorization code grant type, in which the client makes separate requests for authorization and for an access token, the client receives the access token as the result of the authorization request. The implicit grant type does not include client authentication, and relies on the presence of the resource owner and the registration of the redirection URI. Because the access token is encoded into the redirection URI, it may be exposed to the resource owner and other applications residing on the same device.
OAuth 2.0 JWT Bearer Token Flow
The main use case of the JWT Bearer Token Flow is server-to-server API integration. This flow uses a certificate to sign the JWT request and doesn't require explicit user interaction. The OAuth 2.0 JWT bearer token flow defines how a JWT can be used to request an OAuth access token from Salesforce when a client wants to use a previous authorization. Authentication of the authorized app is provided by a digital signature applied to the JWT. Bearer flows can be used only after the consumer has received a refresh token.
Resource Server
The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
Authorization Server
The server issuing access tokens to the client after successfully authenticating the re source owner and obtaining authorization.
OAuth 2.0 User-Agent Flow
The user-agent authentication flow is used by client apps (consumers) that reside on the user's device or computer. It's also used by client apps running in a browser using a scripting language such as JavaScript. These apps can protect per-user secrets. But, because the apps are widely distributed, the client secret can't be confidential. Authentication is based on the user-agent's same-origin policy. Users can authorize an app to access Salesforce more than once, for example, for a laptop and a desktop computer. The default is five authorizations per app per user. If a user tries to grant access to an app after reaching the org's limit, the least-recently used access token is revoked. The User-Agent flow requires user approval every time (a new device is added).
OAuth 2.0 Username-Password Flow
Use the username-password authentication flow to authenticate when the consumer already has the user's credentials. Avoid the username and password flow because it transmits credentials. Other flows free the application from having to manage, store, and protect credentials. Also, Salesforce Communities don't support the username-password authentication flow.
Identity URL
When a client app makes an authorization request that's successful, the HTTP response contains an identity URL along with the access token. The URL is returned in the id scope parameter. The identity URL is also a RESTful API that you can use to query user information, including the username, email address, and org ID. It also returns endpoints that the client can talk to, such as photos for profiles and accessible API endpoints. The identity URL is the gateway to Salesforce's Identity Service. You can send a GET request to the id URL, accompanied by an OAuth authorization HTTP header containing the access token. In response, you receive details about the user and org. When a request includes the custom_permissions scope parameter, the response includes a map containing custom permissions in an org associated with the connected app. The OpenID Connect UserInfo endpoint provides similar user attributes to Salesforce's Identity Service.
Just-In-Time Provisioning over SAML
With Just-in-Time provisioning, you can use a SAML assertion to create regular and portal users on the fly the first time they try to log in. This eliminates the need to create user accounts in advance. For example, if you have a customer that needs access to your support Community, you don't need to manually create the user in Salesforce. When they log in with single sign-on, their account is automatically created for them, eliminating the time and effort with on-boarding the account. This greatly simplifies the integration work required in scenarios where users need to be dynamically provisioned, by combining the provisioning and single sign-on processes into a single message. Just-in-Time provisioning works with your SAML identity provider to pass the correct user information to Salesforce in a SAML 2.0 assertion attribute statement. You can both create and modify users, contacts, and accounts this way. Because Just-in-Time provisioning uses SAML to communicate, your organization must have SAML-based single sign-on enabled.
API Provisioning
You can provision community users by using the SOAP or REST API on the User object. When using this API, keep in mind that the Community user has to be associated to a valid contact and account so these fields need to be set. The account must also be owned by a Salesforce user that has a role. We also provide the following methods to provision a new user through Apex: createPortalUser(user, accountId, password) lets you create an external user associated to a Customer or Partner account. createPersonAccountPortalUser(user, ownerId, password) lets you create an external user associated to a Person Account.