Advanced Setup

Verify Digits User

Many apps use a web server to persist Digits user information. An app should take care to obtain details such as the Digits ID and phone number from their server rather than submitting them directly from the client to the server. This ensures your web server will receive trusted user information.

From your web server, over SSL, you should query Digits to securely request the userID, phone number, and OAuth tokens of the Digits user. With this approach there is no need to configure OAuth signing, or configure and host a callback url for Digits.

This is accomplished through the use of OAuth Echo. OAuth Echo is a means to securely delegate OAuth authorization with a third party while interacting with an API.

More technical information about OAuth Echo can be found at Twitter’s developer site.

Generating OAuth Echo headers

The DigitsOAuthSigning class provides a convenient way to generate authorization headers for a user session. DigitsOAuthSigning relies on the TwitterAuthConfig as well as a TwitterAuthToken.

The TwitterAuthConfig class encapsulates the credentials to identify your Twitter or Digits application. You can get this object from the Digits class.

The TwitterAuthToken class represents the user credentials of a Twitter of Digits user. You can get this object from a TwitterSession or DigitsSession.

TwitterAuthConfig authConfig = TwitterCore.getInstance().getAuthConfig();
TwitterAuthToken authToken = session.getAuthToken();
DigitsOAuthSigning oauthSigning = new DigitsOAuthSigning(authConfig, authToken);

The easiest way to use OAuth Echo is by generating the authorization headers in the client. Use these headers to make an OAuth Echo request from outside the app (e.g. from your web server server).

Map<String, String> authHeaders = oauthSigning.getOAuthEchoHeadersForVerifyCredentials();

The authHeaders map contains the X-Auth-Service-Provider and X-Verify-Credentials-Authorization keys. Your web server should take the value in X-Verify-Credentials-Authorization, and use it to set the Authorization header for a request to the URL in X-Auth-Service-Provider. Once you have the headers, you can send those to your web server to verify the credentials.

URL url = new URL("http://api.yourbackend.com/verify_credentials.json");
HttpsURLConnection connection = (HttpsURLConnection)url.openConnection();
connection.setRequestMethod("GET");

// Add OAuth Echo headers to request
for (Map.Entry<String, String> entry : authHeaders.entrySet()) {
  connection.setRequestProperty(entry.getKey(), entry.getValue());
}

// Perform request
connection.openConnection();

For additional security, on your web host you should:

  • Validate that the oauth_consumer_key header value in the X-Verify-Credentials-Authorization matches your oauth consumer key, to ensure the user is logging into your site. You can use an oauth library to parse the header and explicitly match the key value, e.g. parse(params['X-Verify-Credentials-Authorization']).oauth_consumer_key=<your oauth consumer key>.
  • Verify the X-Auth-Service-Provider header, by parsing the uri and asserting the domain is api.digits.com, to ensure you are calling Digits.
  • Validate the response from the verify_credentials call to ensure the user is successfully logged in
  • Consider adding additional parameters to the signature to tie your app’s own session to the Digits session. Use the alternate form getOAuthEchoHeadersForVerifyCredentials(Map<String, String> optParams) to provide additional parameters to include in the OAuth service URL. Verify these parameters are present in the service URL and that the API request succeeds.