Database.com Java SDK

OAuth Authentication

Your Java applications can use Force.com user accounts for authentication and identity management. The Database.com Java SDK simplifies the process of authenticating users in Force.com using the OAuth protocol.

Force.com OAuth Connector

The Force.com OAuth Connector is a library of classes that handles most of the details of the OAuth handshake for you.

Prerequisite: Creating a Force.com Remote Access Application

Before you can use OAuth to authenticate users for your application, you must create a remote access application in Force.com. This generates the consumer key and secret that you'll need for the OAuth configuration.

  1. Log in at https://login.salesforce.com.
  2. Click Your Name > Setup > Develop > Remote Access.
  3. Click New.
  4. Enter your application name in the Application field and your email in the Contact Email field.
  5. Enter a Callback URL for your application. This is the URL that the user will be returned to after they approve access for the application. To use the Force.com OAuth Connector, your callback URL must be https://<applicationName>.<host>/_auth, where <applicationName> and <host> point to where your application is hosted. If you're testing your application on your localhost, the URL can be http://localhost:<port>/<applicationName>/_auth, where <port> is the port used on the localhost. If you are running your application somewhere other than localhost, your URL must use HTTPS.
  6. Click Save.

You'll now see your application in the list of remote access applications. Click on your application to see the details and retrieve the automatically generated consumer key and secret. The consumer key and secret are the values that you'll use for {$oauthKey} and {$oauthSecret} when you configure the Force.com OAuth Connector in your application.

Configuring the Force.com OAuth Connector

To use the connector, add the following servlet filter to your application's web.xml file: You can set the connection URL in the <param-value> for the url <param-name> or you can reference a system property or environment variable that contains the connection URL by setting <param-value> to ${CONNECTION_URL}. The AuthFilter will look for the URL in a system property named CONNECTION_URL. If it's not found there, it looks for an environment variable named CONNECTION_URL.

<!-- Enables Security -->
<filter>
    <filter-name>AuthFilter</filter-name>
    <filter-class>com.force.sdk.oauth.AuthFilter</filter-class>
         <init-param>
            <param-name>url</param-name>
            <param-value>URL or a ${Java system property} or ${environment variable}</param-value>
        </init-param>


         <!-- Optional parameters -->
         <init-param>
            <param-name>securityContextStorageMethod</param-name>
            <param-value>typeOfSecurityContextStorageMethod</param-value>
        </init-param>
         <init-param>
            <param-name>secure-key-file</param-name>
            <param-value>name Of Key-File</param-value>
        </init-param>
         <init-param>
            <param-name>storeUsername</param-name>
            <param-value>set to false to not store user name in the security context.</param-value>
        </init-param>

        <!-- Optional parameters for logout configuration -->
         <init-param>
            <param-name>logoutFromDatabaseDotCom</param-name>
            <param-value>true or false (defaults to true)</param-value>
        </init-param>
         <init-param>
            <param-name>logoutUrl</param-name>
            <param-value>the URL that will log the user out (defaults to /logout)</param-value>
        </init-param>
</filter>
<filter-mapping>
    <filter-name>AuthFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

The OAuth Connector uses the Force.com API Connector to access the Force.com APIs. The url is used to define OAuth properties. For example, the connection URL below specifies the OAuth key and secret that your application will need:

  force://login.salesforce.com?user=user@salesforcedoc.org&password=samplePassword&oauth_key=3MVG9lKcPoNINVBLqaGC0WiLS7H9aehOXaZad80Ve1OB43i.DpfCjn_SqwIAtyY6Lnuzcvdxgzu.IAaLVk4pH.&oauth_secret=516990866494775428

This URL can be stored in a system property or environment variable. Just put the case-sensitive name of that property or variable into the tag of the url param in the following format: ${PARAMETER_NAME}.

For more information about setting up connection URLs, see Force.com Database Connections.

Other init-param values can be configured to customize behavior:

  • securityContextStorageMethod - Controls whether data about the authenticated user is stored in a server side session or an encrypted browser cookie. The default is cookie. Set this to session to use sessions. Sessions should only be used if sticky load balancing is available or if the application runs with a single instance.

  • secure-key-file - AES encryption is used to encrypt the data about the authenticated user when it is stored in a browser cookie. This is only used if browser cookie storage is on. If cookies are used and no file is specified, a key is automatically generated. However, this should only be done for development purposes because it will be problematic in a multi-instance deployment since each instance will generate a different key. The key is base-64 encoded. For example, replace yourKeyGoesHere with a secure key in the following file. For more information on AES, see Using AES with Java Technology.

      # A valid key in base 64 encoding.   
  private-key=yourKeyGoesHere

  • storeUsername - Flag that sets whether or not the username is stored in the user data. This enables you to avoid storing usernames in browser cookies, but it can be used to prevent username storage in sessions too. The default is true.

  • logoutFromDatabaseDotCom - controls whether the user will also be logged out from Database.com. The default is true. If you set the value to false, your users will keep a Database.com session open and will automatically be passed through future OAuth attempts while their session remains active. We recommend that you use the default value. If you use the default value, a logout redirects users to the Database.com logout link so their final destination is the Database.com logout page.

  • logoutUrl - the URL that logs a user out. You should point your logout links to this URL. The default is /logout. If you set logoutFromDatabaseDotCom to false, you should create your own logout landing page at this URL. Note: A logged out user will always go to the logout landing page hosted at the logout URL. We recommend putting a page there even if you use the automatic logout from Database.com. This will prevent a user from getting an error when using their browser's back button.

The filter-mapping element above contains a url-pattern of "/*". This redirects every URL through the filter. It is not required to do this. If your application requires only certain URL patterns to be authenticated, you can configure the filter to match a subset of requests. However, the filter must always include the "/_auth" URL pattern. Otherwise, the OAuth callback won't be properly handled. For example, if you only wanted to check for authentication for "/Secure" your configuration would look like this:

<filter-mapping>
    <filter-name>AuthFilter</filter-name>
    <url-pattern>/Secure</url-pattern>
    <url-pattern>/_auth</url-pattern>
    <url-pattern>/logout</url-pattern>
</filter-mapping>

If you are using the logout functionality, you must map either /logout or your configured logout URL in the filter mapping. The filter can't handle logout for you if you don't send logout requests through it.