Advanced Setup

Verifying a 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 backend 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.

Obtaining OAuth Echo headers

The DGTOAuthSigning class provides a convenient way to generate authorization headers for a user session.

DGTOAuthSigning relies on the application auth config (an object conforming to TWTRAuthConfig) as well as a Digits user session (DGTSession). These are both available on the Digits shared instance.

After a user has completed the Digits authentication flow:

// Objective-C
// Digits *digits = [Digits sharedInstance];
DGTOAuthSigning *oauthSigning = [[DGTOAuthSigning alloc] initWithAuthConfig:digits.authConfig authSession:digits.session];
NSDictionary *authHeaders = [oauthSigning OAuthEchoHeadersToVerifyCredentials];
// Swift
let digits = Digits.sharedInstance()
let oauthSigning = DGTOAuthSigning(authConfig:digits.authConfig, authSession:digits.session())
let authHeaders = oauthSigning.OAuthEchoHeadersToVerifyCredentials()

The authHeaders dictionary looks as follows:

// authHeaders dictionary
{
  "X-Auth-Service-Provider": A URL used to retrieve Digits user account information,
  "X-Verify-Credentials-Authorization": An OAuth signature for the provided user
}

Note: These keys can be accessed with the constants: TWTROAuthEchoRequestURLStringKey and TWTROAuthEchoAuthorizationHeaderKey.

Your backend should take the OAuth signature in X-Verify-Credentials-Authorization and use it to set the Authorization header for a GET request to the URL in X-Auth-Service-Provider.

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 OAuthEchoHeadersToVerifyCredentialsWithParams: 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.

Receiving Session Updates

The Digits users might change their phone number or deactivate their account. By implementing the DGTSessionUpdateDelegate protocol, Digits will notify you whenever one of these changes occur on the current session. Remember, the userID is the only attribute that will never change.

In your delegate:

// Objective-C
// Set the Session update delegate
[Digits sharedInstance].sessionUpdateDelegate = self;
// Swift
// Set the Session update delegate
Digits.sharedInstance().sessionUpdateDelegate = self

digitsSessionHasChanged:

It notifies your delegate when the access token and secret are rotated, or the phone number has changed. This method will pass the new Digits session containing the all the existing and updated values. We will at this moment have updated the sharedInstance’s session and you may also want to create a new OAuth Echo header and call your own API to validate and update the new values.

digitsSessionExpiredForUserID:

It notifies your delegate when the account or the access tokens are no longer valid; for example if the user has deactivated his Digits account. We will log the current user out of Digits; you may now start the Digits log-in flow again to identify the new user and update your own session; or log the current user out of your app.