Login

To login you first acquire an access token from the /oauth/token endpoint which is used to get a one time code from the /oauth/exchange endpoint.

This code can be given to another client, who may use it to request an access token for the same user. This is how you can give your backend server an access token which identifies your app and authorize to make requests on your behalf.

The server needs to communicate with SPiD on behalf of the user, but the user authenticates on the app, not the server.

Because of the security implications of having the app share its tokens or the logged in user data with the backend server directly, the app must ask SPiD for a one-time code corresponding to the authenticated user. After retrieving the exchange code, the app may share this code with the backend, which then authenticates directly with SPiD with the code and gets its own user access token - thus keeping a high level of security and giving both apps and backends full access to user data and the SPiD APIs.

Please note:

  • Both clients must belong to the same merchant.
  • The code expires after 30 seconds.

To acquire the access token you can use one of two OAuth flows; authorization code grant or implicit grant. Authorization code grant is used to obtain both access tokens and refresh tokens. Implicit grant is used to obtain access tokens (it does not support refresh tokens) and is typically implemented in a browser or webview using a scripting language such as JavaScript.

For authorization code grant there are several different ways to authenticate the client. The different grant types used in SPiD are

  • password Authenticate by username and password
  • client_credentials Authenticate by client id and client secret
  • authorization_code Authenticate by code
  • urn:ietf:params:oauth:grant-type:jwt-bearer Used for third party token bearers. In SPiD’s case this is for Facebook or Google+ (Google+ login is only available for Android)
  • refresh_token Used when you want to refresh your access token after it has expired

Connecting using Facebook or Google+

If you want to use Facebook or Google+ to connect to SPiD use the urn:ietf:params:oauth:grant-type:jwt-bearer grant type. In addition to what you need for normal authentication you need to specify which third party provider you want to use for your login as well as identify your app to that provider. This is done through the use of a JSON web token, JWT. If you’re using the SPiD SDKs to develop your app you won’t have to create the JWT or specify the grant type as we take of it for you. See the code below for examples how to login using Facebook or Google+.

Facebook

Before you get started you need to register your app for a Facebook application id at developers.facebook.com.

Android

// Session is a class from the Facebook API

Session session = Session.getActiveSession();
SPiDConfiguration config = SPiDClient.getInstance().getConfig();
SPiDFacebookTokenRequest tokenRequest;
try {
    tokenRequest = new SPiDFacebookTokenRequest(session.getApplicationId(), session.getAccessToken(), session.getExpirationDate(), new LoginListener());
        tokenRequest.execute();
} catch (SPiDException e) {
        dismissLoadingDialog();
        Toast.makeText(config.getContext(), "Error creating login request", Toast.LENGTH_LONG).show();
}

iOS

SPiDTokenRequest *request = [SPiDTokenRequest
        userTokenRequestWithFacebookAppID:[FBSession activeSession].appID
                            facebookToken:[FBSession activeSession].accessTokenData.accessToken
                           expirationDate:[FBSession activeSession].accessTokenData.expirationDate
                        completionHandler:^(SPiDError *tokenError) {
                            if (tokenError) {
                                if (tokenError.code == SPiDOAuth2UnknownUserErrorCode) {
                                    UIAlertView *alertView = [[UIAlertView alloc]
                                            initWithTitle:@"User does not exist"
                                }
                            }
                        }

Google+

Android

First register your app in the Google Developers Console. A detailed guide of the steps that need to be taken can be found here.

This example is simplified for brevity, for a working app using Google+ to register new SPiD users and logging in see the SPiDGooglePlusApp in the Android SPiD repository.

// First we get a token from Google
String token = GoogleAuthUtil.getToken(activity, Plus.AccountApi.getAccountName(googleApiClient), "oauth2:" + MainActivity.GOOGLE_PLUS_SCOPES);

final SPiDGooglePlusTokenRequest tokenRequest = new SPiDGooglePlusTokenRequest(getPackageName(), token, new SPiDAuthorizationListener() {
    @Override
    public void onComplete() {
        SPiDLogger.log("SPiD login successful, access token received: " + SPiDClient.getInstance().getAccessToken().getAccessToken());
       // Switch to a login screen
    }

iOS

Not yet implemented for iOS.

Example of an authentication sequence between a native device app and its Backend API:

Grant type: code

Grant type: session

The process described above allows your backend to communicate on behalf of a user logged into the device. You might also need to generate a session for the user in a webview layer of a native mobile application. You do that with this endpoint as well, setting the type to session (RequestType.SESSION in the Android SDK).

Example flow:

Native mobile development

Help us improve

Did you spot an error? Or maybe you just have a suggestion for how we can improve? Leave a comment, or better yet, send us a pull request on GitHub to fix it (in-browser editing, only takes a moment).

History of this page

Comments/feedback

Do you have questions, or just want to contribute some newly gained insight? Want to share an example? Please leave a comment. SPiD reads and responds to every question. Additionally, your experience can help others using SPiD, and it can help us continuously improve our documentation.