Chatter REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Understanding the Web Server OAuth Authentication Flow

Typically this flow is used by web applications that can confidentially store the client secret. A critical aspect of the Web server flow is that the application must be able to protect the consumer secret.

The following is the general flow. The individual step descriptions follow.

Web Server OAuth Authentication Flow

The following is a general description of the OAuth web-server flow:

  1. To request authorization for a resource, the client application redirects the end-user’s browser to a web page hosted on the resource owner’s authorization server. In this case, it is the Salesforce log in page.
  2. The end-user logs into Salesforce to authenticate themselves. Since this web page is hosted by the resource owner (Salesforce) and interacted with directly by the end user, the client web application never finds out the user’s login credentials. The end-user also grants authorization to the client application.
  3. Salesforce sends the authorization code back to the client application using the specified callback URL.
  4. After obtaining the authorization code, the client application passes back the authorization code to obtain an access token.
  5. After validating the authorization code, Salesforce passes back a response token. If there was no error, the response token includes an access code, a refresh token, and additional information.
  6. The protected resources are Chatter REST API endpoints.

Using the Web Server Flow with Chatter REST API and Salesforce

The following provides specific details for the OAuth Web-server flow when used with Salesforce and Chatter REST API:
  1. Direct the client’s web browser to the page https://login.instance_name/services/oauth2/authorize, with the following request parameters:
    Parameter Description
    response_type Must be code for this authentication flow
    client_id The Consumer Key value from the remote access application defined for this application
    redirect_url The Callback URL value from the remote access application defined for this application
    You can also include the following optional request parameters:
    Parameter Description
    state Specifies URL-encoded state data to be returned in the callback URL after approval.
    immediate Determines whether the user should be prompted for login and approval. Values are either true or false. Default is false.
    • If set to true, and if the user is currently logged in and has previously approved the application, the approval step is skipped.
    • If set to true and the user is not logged in or has not previously approved the application, the session is immediately terminated with the immediate_unsuccessful error code.
    display Indicates the type of web pages that is provided. Valid values are:
    • page—Full-page authorization screen. This is the default value if none is specified.
    • popup—Compact dialog optimized for modern web browser popup windows.
    • touch—mobile-optimized dialog designed for modern smartphones such as Android and iPhone.
    • mobile—mobile optimized dialog designed for less capable smartphones such as BlackBerry OS 5.
  2. After successfully being logged in, the user is asked to authorize the application.
    Mobile Approval Page
    Note that if the user has already authorized the application, this step is skipped.
  3. Once Salesforce has confirmed that the client application is authorized, the end-user’s web browser is redirected to the callback URL specified by the redirect_url parameter, appended with the following values in its query string:
    Parameter Description
    code The authorization code that is passed to get the access and refresh tokens
    state The state value that was passed in as part of the initial request, if applicable.
    It is expected that the redirect_uri web page is hosted by the client application server.
  4. The client application server must extract the authorization code and pass it in a request to Salesforce for an access token. This request should be made as a POST against this URL: https://login.instance_name/services/oauth2/token with the following query parameters:
    Parameter Description
    grant_type Value must be authorization_code for this flow.
    client_id Consumer key from the remote access application definition.
    client_secret Consumer secret from the remote access application definition.
    redirect_uri URI to redirect the user to after approval. This must match the value in the Callback URL field in the remote access application definition exactly, and is the same value sent by the initial redirect.
    code Authorization code obtained from the callback after approval.
    format Expected return format. This parameter is optional. The default is json. Values are:
    • urlencoded
    • json
    • xml
  5. If this request is successful, the server returns a response body holding the following:
    Parameters Description
    access_token Session ID that you can use for making Chatter REST API requests. This session ID cannot be used in the user interface. Treat this like a user's session and diligently protect it.
    refresh_token Token that can be used in the future to obtain new access tokens (sessions).

    This value is a secret. You should treat it like the user's password and use appropriate measures to protect it.

    Warning
    instance_url URL indicating the instance of the user's organization. In this example, the instance is na1: https://na1.salesforce.com
    id Identity URL that can be used to both identify the user as well as query for more information about the user. Can be used in an HTTP request to get more information about the end user.
    signature Base64-encoded HMAC-SHA256 signature signed with the consumer's private key containing the concatenated ID and issued_at. This can be used to verify the identity URL was not modified since it was sent by the server.
    issued_at When the signature was created.