Java SDK

OAuth Authentication

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

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

Prerequisite: Creating a Remote Access Application

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

  1. Log in at
  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 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 OAuth Connector in your application.

Configuring the 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 -->
            <param-value>URL or a ${Java system property} or ${environment variable}</param-value>

         <!-- Optional parameters -->
            <param-value>name Of Key-File</param-value>
            <param-value>set to false to not store user name in the security context.</param-value>

        <!-- Optional parameters for logout configuration -->
            <param-value>true or false (defaults to true)</param-value>
            <param-value>the URL that will log the user out (defaults to /logout)</param-value>

The OAuth Connector uses the API Connector to access the 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:


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 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.   
  • 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 The default is true. If you set the value to false, your users will keep a 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 logout link so their final destination is the 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 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:


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.