MYDIGIPASS.COM. OAuth API Integration Guide

MYDIGIPASS.COM OAuth API Integration Guide May 2012

Table of Contents 1. Introduction... 1 1.1. Audience and Purpose of this Document... 1 1.2. What is DIGIPASS as a Service?... 1 1.3. What is MYDIGIPASS.COM?... 1 1.4. About VASCO... 1 2. MYDIGIPASS.COM Secure Login Concepts... 3 2.1. What is MYDIGIPASS.COM?... 3 2.2. About OAuth 2.0... 3 2.3. How MYDIGIPASS.COM uses OAuth to provide Authentication... 4 2.4. MYDIGIPASS.COM Authentication Flow... 5 2.5. Universally Unique IDentifier (UUID)... 5 2.6. Integrating MYDIGIPASS.COM Secure Login... 6 2.6.1. Overview... 6 2.6.2. Buttons... 6 2.6.3. Linking and Unlinking Users... 6 2.6.4. Sharing OAuth User Attributes... 6 2.7. Possible User Authentication Scenarios... 7 3. How to implement MYDIGIPASS.COM Secure Login... 8 3.1. Overview... 8 3.2. Before you Start... 8 3.3. Registering your Web Application... 9 3.4. Integrating the MYDIGIPASS.COM Secure Login Button... 9 3.4.1. Overview... 9 3.4.2. Recommendations... 9 3.4.3. Attributes... 9 3.5. Setting up the redirection endpoint... 10 3.6. Implementing OAuth 2.0 Authentication.... 10 3.6.1. HTTP Requirements... 11 3.6.2. Redirecting the User to the MYDIGIPASS.COM Secure Login Authorization Endpoint... 11 3.6.3. Exchanging the Authorization Token for an Access Token... 11 3.6.4. Retrieving the User Data with the Access Token... 12 3.7. Linking your Application Users to their MYDIGIPASS.COM UUID... 12 3.7.1. Tracking your application s users / MYDIGIPASS.COM UUID pairs... 12 3.7.2. User attributes... 13 3.7.3. In progress page... 13 3.8. What s Next?... 13 4. Support... 15 4.1. Overview... 15 4.2. If you encounter a problem... 15 Alphabetical Index... 19 VASCO Data Security 2012 ii

VASCO Products. VASCO Data Security, Inc. and/or VASCO Data Security International GmbH are referred to in this document as VASCO. VASCO Products comprise Hardware, Software, Services and Documentation. This document addresses potential and existing VASCO customers and has been provided to you and your organization for the sole purpose of helping you to use and evaluate VASCO Products. As such, it does not constitute a license to use VASCO Software or a contractual agreement to use VASCO Products. Disclaimer of Warranties and Limitations of Liabilities. VASCO Products are provided as is without warranty or conditions of any kind, whether implied, statutory, or related to trade use or dealership, including but not limited to implied warranties of satisfactory quality, merchantability, title, non-infringement or fitness for a particular purpose. VASCO, VASCO DISTRIBUTORS, RESELLERS AND SUPPLIERS HAVE NO LIABILITY UNDER ANY CIRCUMSTANCES FOR ANY LOSS, DAMAGE OR EXPENSE INCURRED BY YOU, YOUR ORGANIZA- TION OR ANY THIRD PARTY (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF DATA) ARISING DIRECTLY OR INDIRECTLY FROM THE USE, OR INABILITY TO USE VASCO SOFTWARE, HARDWARE, SERVICES OR DOCUMENTATION, RE- GARDLESS OF THE CAUSE OF THE LOSS, INCLUDING NEGLIGENCE, EVEN IF VASCO HAS BEEN AD- VISED OF THE POSSIBILITY OF SUCH DAMAGES, OR IF THEY WERE FORESEEABLE. OUR MAXIMUM AGGREGATE LIABILITY TO YOU, AND THAT OF OUR DISTRIBUTORS, RESELLERS AND SUPPLIERS SHALL NOT EXCEED THE AMOUNT PAID BY YOU FOR THE PRODUCT. THE LIMITATIONS IN THIS SECTION SHALL APPLY WHETHER OR NOT THE ALLEGED BREACH OR DEFAULT IS A BREACH OF A FUNDAMENTAL CONDITION OR TERM, OR A FUNDAMENTAL BREACH. THIS SECTION WILL NOT AP- PLY ONLY WHEN AND TO THE EXTENT THAT APPLICABLE LAW SPECIFICALLY REQUIRES LIABILITY DESPITE THE FOREGOING EXCLUSIONS AND LIMITATIONS. Intellectual Property and Copyright. VASCO Products contain proprietary and confidential information. VASCO Data Security, Inc. and/or VASCO Data Security International GmbH own or are licensed under all title, rights and interest in VASCO Products, updates and upgrades thereof, including copyrights, patent rights, trade secret rights, mask work rights, database rights and all other intellectual and industrial property rights. No part of these Products may be transferred, disclosed, reproduced or transmitted in any form or by any means, electronic, mechanical or otherwise, for any purpose, except as expressly permitted by VASCO or its authorized licensee in writing. This document is protected under US and international copyright law as an unpublished work of authorship. No part of it may be transferred, disclosed, reproduced or transmitted in any form or by any means, electronic, mechanical or otherwise, for any purpose, except as expressly permitted in writing by VASCO or its authorized licensee. Trademarks. VASCO, VACMAN, IDENTIKEY, axsguard, DIGIPASS, DIGIPASS as a Service, MYDIGIPASS.COM and the logo are registered or unregistered trademarks of VASCO Data Security, Inc. and/or VASCO Data Security International GmbH in the U.S. and other countries. Other company brand or product names or other designations, denominations, labels and/or other tags, titles, as well as all URLs (Internet addresses) linked to such designations or communications (irrespective of whether protected by intellectual property law or not), mentioned in VASCO Products may be the trademarks or registered trademarks or be part of any other entitlement of their respective owners. RADIUS Disclaimer. Information on the RADIUS server provided in this document relates to its operation in the DIGIPASS as a Service environment. We recommend that you contact your NAS/RAS vendor for further information. Copyright 2012 VASCO Data Security, VASCO Data Security International GmbH. All rights reserved. Date Last Updated : 21/05/2012 VASCO Data Security 2012 iii

Chapter 1. Introduction 1.1. Audience and Purpose of this Document This document is intended for developers who want to integrate the MYDIGIPASS.COM Secure Login OAuth API with their online applications. Knowlegde of Web 2.0 development and HTTP is required. In Section 1.2, What is DIGIPASS as a Service?, Section 1.3, What is MYDIGIPASS.COM? and Section 1.4, About VASCO, we introduce DIGIPASS as a Service, MYDIGIPASS.COM and VASCO. In Chapter 2, MYDIGIPASS.COM Secure Login Concepts, we explain the properties and features of the MYDIGIPASS.COM Secure Login API. In Chapter 3, How to implement MYDIGIPASS.COM Secure Login, we explain the steps that you must follow to swiftly implement the MYDIGIPASS.COM Secure Login API. We also list the OAuth calls and responses that are exchanged between a web application and MYDIGIPASS.COM. In Chapter 4, Support, we explain how to request support. 1.2. What is DIGIPASS as a Service? DIGIPASS as a Service (DPS) is VASCO s cloud-based authentication service platform which makes use of VASCO s proprietary authentication technology. Organisations can secure their entire infrastructure via the DPS platform. Nowadays, most web applications are secured with usernames and passwords, which can be easily hacked, stolen or passed on. Providers and customers have become more conscious about the security risk of static passwords and accelerate their investments in strong user authentication to protect their users business critical information. B-to-C application providers looking to deploy two-factor authentication for their user base sometimes face a number of barriers. They consider traditional strong authentication as too costly or they lack the resources to manage the distribution of authentication devices to end-users. As a result, VASCO experienced a strong demand from the market to launch DIGIPASS as a Service. With DIGIPASS as a Service, VASCO is managing the full authentication process while the B-to-C provider focuses on its core business. The DIGIPASS as a Service offering includes a fully redundant hosted authentication back-end, the provisioning of DIGIPASS software or hardware authenticators to end-users, DIGIPASS services including fulfillment services (branding, customization, packaging, provisioning, distribution and storage), professional services and first line support. 1.3. What is MYDIGIPASS.COM? MYDIGIPASS.COM is VASCO s single sign-on, identity management and two-factor authentication enduser solution for cloud-based applications. Via MYDIGIPASS.COM, users can register, enable and use their MYDIGIPASS.COM authenticator to sign in to their favorite online applications. Our sandbox environment allows you to discover and fully test the MYDIGIPASS.COM platform. This environment provides access to a demo application, the API documentation and the tools needed for your own integration. 1.4. About VASCO VASCO is a world leader in strong authentication and e-signature solutions, specializing in online accounts, identities and transactions. As a global software company, VASCO serves a customer base of approximately 10,000 companies in over 100 countries, including approximately 1,500 international financial institutions. In addition to the financial sector, VASCO s technologies secure sensitive information and transactions for the enterprise security, e-commerce and e-government industries. VASCO Data Security 2012 1

Chapter 1. Introduction For further information, please visit http://www.vasco.com. VASCO Data Security 2012 2

Chapter 2. MYDIGIPASS.COM Secure Login Concepts 2.1. What is MYDIGIPASS.COM? MYDIGIPASS.COM allows web developers to easily integrate VASCO s strong authentication with any online application at a minimum cost. In this document, we explain how to link your online application to MYDIGIPASS.COM so it can benefit from the advantages of the MYDIGIPASS.COM global federation network. Once your application is linked, users can securely authenticate using any MYDIGIPASS.COM compatible DIGIPASS. Example 2.1. MYDIGIPASS.COM compatible DIGIPASS Your online banking DIGIPASS, such as your HSBC or Citibank DIGIPASS. A dedicated MYDIGIPASS.COM DIGIPASS, downloaded from the ios App Store or the Android Market. A DIGIPASS for Mobile that is provisioned via our Text Messaging Service to your Mobile Phone. Advantages of MYDIGIPASS.COM Secure Login: Uses VASCO s proven two-factor DIGIPASS authentication technology. Uses an OAuth 2.0 standard for authentication and authorization. MYDIGIPASS.COM does all the heavy lifting concerning the complexity of presenting two-factor authentication to the user, e.g. handling various two-factor authentication mechanisms. MYDIGIPASS.COM Secure Login provides user interface consistency accross multiple end-user applications. A single MYDIGIPASS.COM device can secure access to a wide range of web applications. Easy integration using the MYDIGIPASS.COM Secure Login button code and OAuth 2.0 libraries. 2.2. About OAuth 2.0 The OAuth 2.0 authorization protocol enables a third-party application to get limited access to user data on a web application on behalf of and in agreement with the user. The user authenticates with the web application using his / her regular credentials. The third-party application doesn t know the credentials of the authenticating user. Example 2.2. Third-party application accessing photos on Flickr.com A third-party web application that visualises the location of photographs on a map wants access to the photographs of a user on Flickr.com. The Flickr user wants to approve this access without compromising his/her Flickr password. OAuth 2.0 provides approval and authorization interaction flows between the resource owner (the Flickr user) and the third-party visualisation application. As a result, the third-party visualisation application can access Flickr photos on behalf of the user through an OAuth token without ever knowing the user s Flickr password. This is preferred over other authentication methods, because the access scope of OAuth tokens can be limited to specific types of data and because the third-party application s access can be revoked at any time by the user. For more information about OAuth 2.0, see the specification: OAuth 2.0 draft 22: http://tools.ietf.org/html/draft-ietf-oauth-v2-22 The latest version of the OAuth 2.0 spec can be found at http://tools.ietf.org/html/draft-ietf-oauth-v2 VASCO Data Security 2012 3

Chapter 2. MYDIGIPASS.COM Secure Login Concepts 2.3. How MYDIGIPASS.COM uses OAuth to provide Authentication Terms in bold are the same as mentioned in the OAuth 2.0 specification (draft 22). MYDIGIPASS.COM Secure Login uses the concepts of the OAuth 2.0 protocol, i.e. the authorization of a client (your web application) to access data (the MYDIGIPASS.COM user identifier) of a resource owner (the MYDIGIPASS.COM user), and adds secure two-factor authentication technology (the MYDIGIPASS.COM DIGIPASS) to authenticate the user before an OAuth token is issued to your web application. The client, i.e. your Web application, can then trust that the user - who is identified based on the data returned from the MYDIGIPASS.COM service (the user identifier and approved personal details) - was strongly authenticated and can continue to sign in (or even sign up). Advantages of using OAuth 2.0 for (federated) authentication purposes include: Simplified integration as many third-party OAuth libraries are available for different programming languages. The user credentials (static password and one-time password) are transmitted directly and securely from the user s browser to MYDIGIPASS.COM (SSL). Your web application no longer needs to enforce strong passwords, manage or store passwords; the authentication process is entirely handled by MYDIGIPASS.COM. MYDIGIPASS.COM user details, a.k.a. attributes can be used to transparently sign up new users. You may also use these attributes because users expect you to automatically update their profile on your web application with their MYDIGIPASS.COM profile (also see Section 3.7, Linking your Application Users to their MYDIGIPASS.COM UUID ). MYDIGIPASS.COM OAuth Technical Specifications Compatible with OAuth 2.0 draft 22 Confidential client type for use with web application profiles Authorization grant type is: authorization code bearer access tokens for one-time use (no refresh tokens) Verifies incoming redirect_uri parameters Secures requests with HTTPS VASCO Data Security 2012 4

Chapter 2. MYDIGIPASS.COM Secure Login Concepts 2.4. MYDIGIPASS.COM Authentication Flow Figure 2.1. MYDIGIPASS.COM Secure Login Authentication Flow 1. The user navigates to the web application and clicks on the MYDIGIPASS.COM Secure Login button. 2. The web application redirects the browser to the MYDIGIPASS.COM OAuth authorization endpoint URI. 3. MYDIGIPASS.COM strongly authenticates the user using his MYDIGIPASS.COM DIGIPASS and his MYDIGIPASS.COM password. 4. MYDIGIPASS.COM redirects the browser to the OAuth redirection Endpoint URI of the web application and includes an OAuth authorization code in its response. At this stage, the web application only "knows" that the user successully authenticated with MYDIGIPASS.COM. It has no way of knowing who the user is locally. 5. The web application identifies itself to MYDIGIPASS.COM, using its unique client_id and client_secret. The application exchanges this OAuth authorization code for a one-time OAuth access token. The access token is issued at the MYDIGIPASS.COM OAuth token endpoint URI. 6. The web application uses the one-time OAuth access token to request the MYDIGIPASS.COM user identifier (UUID) from the MYDIGIPASS.COM user data endpoint URI. Other data approved for sharing by the user, i.e. user attributes, is also included in the response (e.g. the user s email, home address etc.). Based on the UUID, the web application can match the obtained UUID with the appropriate user in its local database and consider the user as successfully authenticated. The sharing of user attributes is entirely at the user s discretion and therefore optional. The UUID is always required to authenticate your users. 2.5. Universally Unique IDentifier (UUID) The UUID is a unique identifier assigned by MYDIGIPASS.COM and represents a secured user account on a web application. A user is assigned a different UUID for each account that he / she secures with MYDIGIPASS.COM. If a user unlinks a secured account via MYDIGIPASS.COM, the associated UUID is permanently deleted. If a user decides to relink his / her account, a new UUID will be assigned. For security reasons, a UUID is never reused. VASCO Data Security 2012 5

Chapter 2. MYDIGIPASS.COM Secure Login Concepts For more information about UUID specifications, see RFC 4122. 2.6. Integrating MYDIGIPASS.COM Secure Login 2.6.1. Overview You can use MYDIGIPASS.COM on your website to: Authenticate users that already have a MYDIGIPASS.COM account. Allow existing users to secure their account with MYDIGIPASS.COM. Sign up and enroll new users. 2.6.2. Buttons Use the appropriate button for each situation. The buttons are provided and explained in the "connected sites" section on the developer site. Note that the color of the buttons varies depending on the environment you are working in. Sandbox buttons are orange, while production buttons are blue. Sign up buttons: Use these buttons to sign up new users. Make sure to also create an account on your application (also see the next section). Connect buttons: Use these buttons to connect the account of an authenticated user to MYDIGIPASS.COM. Secure login buttons: Use these buttons to allow users to securely log in. 2.6.3. Linking and Unlinking Users When integrating MYDIGIPASS.COM with your web application, you need a mechanism to couple each of your users with his / her unique MYDIGIPASS.COM UUID. This coupling ensures that: The user of your application is associated with the correct MYDIGIPASS.COM user; the username as known by your application isn t necessarily identical to the MYDIGIPASS.COM username. The user accesses the correct profile on your web application whenever he / she authenticates via MYDIGIPASS.COM. Access rights are respected. The user should be able to access his / her data; nothing more, nothing less. The user s profile attributes on your web application are properly updated with the user s MYDIGIPASS.COM profile attributes, because users expect your to keep their profile settings updated (also see Section 3.7, Linking your Application Users to their MYDIGIPASS.COM UUID ). Depending on the scenarios provided in Section 3.7, Linking your Application Users to their MYDIGIPASS.COM UUID, certain actions must be taken by your web application. Provide a mechanism so that users can unlink their application account with MYDIGIPASS.COM. This prevents users from being locked out of your application and allows them to reuse their initial application credentials, if any. 2.6.4. Sharing OAuth User Attributes When authenticating for the first time via MYDIGIPASS.COM to sign in to your web application, the user will be prompted to share his / her MYDIGIPASS.COM user profile information with your application. Once the user has authorized access to his / her profile information, your web application will be able to use this data (also see Section 3.7, Linking your Application Users to their MYDIGIPASS.COM UUID ) for any purpose, except to authenticate users. Users have the option to share profile attributes such as their: Full name Email address Date of birth Home address VASCO Data Security 2012 6

Chapter 2. MYDIGIPASS.COM Secure Login Concepts Phone number Never use attributes, such as an e-mail address, to authenticate users. Attributes can be changed at the user s discretion, while the UUID cannot. Always use the application s user identifier / UUID association. Remember that a user can always reset his / her sharing permissions via MYDIGIPASS.COM, e.g. to only share one attribute. 2.7. Possible User Authentication Scenarios Users of your application can encounter the following scenarios: 1. The user is signed in and has granted permission to share his / her user data with your web application: The user is immediately authenticated and rerouted to the redirection endpoint with a valid OAuth authorization code. 2. The user is signed in, but has not yet granted permissions to share his / her user data with your web application: The user is prompted to select which profile attributes he / she wants to share with your web application. After doing so, (s)he will be rerouted to the redirection endpoint with a valid OAuth authorization code. 3. The user is not signed in: The user can sign in to MYDIGIPASS.COM, using strong authentication (twofactor authentiction) and, if needed, will be prompted to share his / her profile attributes (see scenario 2) before being rerouted to the redirection endpoint. VASCO Data Security 2012 7

Chapter 3. How to implement MYDIGIPASS.COM Secure Login 3.1. Overview In this chapter, we explain how to implement the MYDIGIPASS.COM Secure Login OAuth API. Topics covered in this chapter include: Important information about MYDIGIPASS.COM sandbox and production URIs. Registering your web application with https://developer.mydigipass.com. Integrating the MYDIGIPASS.COM Secure Login button. Setting up a redirection endpoint for your web application. Integrating the MYDIGIPASS.COM Secure Login API, which executes the steps illustrated below and explained in Section 2.4, MYDIGIPASS.COM Authentication Flow. HTTP protocol requirements. Mandatory procedures to properly link the users of your web application to their corresponding MYDIGIPASS.COM UUID. Figure 3.1. MYDIGIPASS.COM Secure Login API Authentication Flow 3.2. Before you Start MYDIGIPASS.COM provides a sandbox and a production environment. The sandbox environment allows you to get acquainted with and explore the possibilities of MYDIGIPASS.COM. While using the sandbox environment, substitute all references to mydigipass.com with sandbox.mydigipass.com in your application URLs. VASCO Data Security 2012 8

Chapter 3. How to implement MYDIGIPASS.COM Secure Login To migrate your sandbox environment to a production environment, contact us. 3.3. Registering your Web Application To use your web application as an OAuth client with the MYDIGIPASS.COM federated authentication service, you must first request a client_id and a client_secret from VASCO Data Security. To receive your client_id and client_secret, log on to https://developer.mydigipass.com and select Connect your site. You will be asked to provide the following information: Client Application name: the canonical name of your application Client redirect URI: The redirection endpoint URI (absolute URI) that MYDIGIPASS.COM will use to call back your application after authenticating a user. You will also need to pass this URI in the redirect_uri parameter for requests to the MYDIGIPASS.COM token endpoint (also see the following section). Logo: the logo you want to use on MYDIGIPASS.COM. For details about OAuth redirection endpoints, see section-3.1.2 of the OAuth specification. See section-2 of the OAuth specification to learn more about OAuth clients. 3.4. Integrating the MYDIGIPASS.COM Secure Login Button 3.4.1. Overview The MYDIGIPASS.COM Secure Login button is the easiest and recommended way to provide the MYDIGIPASS.COM sign in functionality to your end-users. Place this button on the landing page of your website and on the user s profile page. The JavaScript code is easy to integrate. When pressed, the button will open the MYDIGIPASS.COM authorization endpoint in a pop-up window. The user will be prompted to sign in to your application using his MYDIGIPASS.COM credentials. The call that is initiated when the button is pressed corresponds to step 2 in the figure above and the call listed in Section 3.6.2, Redirecting the User to the MYDIGIPASS.COM Secure Login Authorization Endpoint. An overview of MYDIGIPASS.COM buttons can be found here: http://www.vasco-events.com/mdp/ 3.4.2. Recommendations 1. Place the dp_connect code immediately before the closing </body> tag of your pages in order to avoid page loading delays or any other page loading issues for visitors with slow Internet connections. <script src="https://mydigipass.com/dp_connect.js" type="text/javascript"></ script> 2. Next, add an <a> tag with the attributes listed in Table 3.1, Required data attributes and Table 3.2, Optional data attributes to the desired page: <a class="dpplus-connect" data-client-id="xxx..." data-redirect-uri="https:// my.domain" href="#">connect with MYDIGIPASS.COM</a> 3.4.3. Attributes Required Attributes data-client-id Description Your MYDIGIPASS.COM Connect OAuth client_id VASCO Data Security 2012 9

Chapter 3. How to implement MYDIGIPASS.COM Secure Login Required Attributes Description data-redirect-uri Your MYDIGIPASS.COM Connect OAuth redirect_uri. It must match the one you submitted to VASCO Data Security. Table 3.1. Required data attributes Optional Attributes Description data-origin Points to a different instance of MYDIGIPASS.COM (e.g. https:// sandbox.mydigipass.com). data-state data-style data-text data-help An attribute to store useful information such as the URL where the MYDIGIPASS.COM secure login button was clicked or the username as known by your web application. This optional attribute is used when the user is redirected to the specified redirection endpoint. Sets the button style. Available styles are: default, large, medium, small and false. If no style is selected, default is used. Use false if you don t want to use the default MYDIGIPASS.COM Secure Login button styling. Specifies the text to appear on the button. Available options are: connect, sign-up and secure-login. If not specified, the default style connect is used. Note that this attribute is irrelevant if the data-style attribute is set to default or small. Can be set to true or false (default). If set to true, meta-text is used to display information about the button in question. Table 3.2. Optional data attributes 3.5. Setting up the redirection endpoint Set up your web application to accept the following call from MYDIGIPASS.COM (see step 4 in Figure 3.1, MYDIGIPASS.COM Secure Login API Authentication Flow : HTTP Request. GET /callback?code=mydigipass.com_authorization_code Parameter Description code The authorization code you can exchange for an access token at the token endpoint URI. Table 3.3. Web Application Redirection Endpoint Parameters Make sure that your redirection endpoint is not an open redirector, because this is a serious security risk. See section-10.15 of the OAuth specification for more information about open redirectors. 3.6. Implementing OAuth 2.0 Authentication. As OAuth is a widely supported protocol, many libraries are available online. Look for the OAuth library that best suits your environment and install it. Note that the library must be compatible with OAuth2 v22. Even if you decide to use a library, you must implement a mechanism to link your users to their MYDIGIPASS.COM UUID, as explained in Section 3.7, Linking your Application Users to their MYDIGIPASS.COM UUID. If you can t find a suitable library, simple HTTP methods can be used instead. In the following sections, we provide the details of each call at the HTTP level. You can use tools such as wget or curl to test them. VASCO Data Security 2012 10

Chapter 3. How to implement MYDIGIPASS.COM Secure Login 3.6.1. HTTP Requirements Our OAuth API uses HTTPS. It is therefore crucial to respect the HTTP protocol stack and implement proper handling of the HTTP status codes. A list of HTTP status codes and their description can be found here. It is recommended to: Test the 2xx OK / success codes Implement the 3xx codes (such as a 302 redirect) Implement 4xx codes (such as 403 Forbidden) Handle 5xx codes, which indicate a failure on the MYDIGIPASS.COM side Example 3.1. Handling HTTP Redirects If you issue an HTTP POST to https://mydigipass.com/oauth/token, you will be redirected to https://www.mydigipass.com/oauth/token (HTTP 302). Your library should be able to handle this. As an alternative, you can issue an HTTP POST to www.mydigipass.com. 3.6.2. Redirecting the User to the MYDIGIPASS.COM Secure Login Authorization Endpoint Use the MYDIGIPASS.COM Secure Login button to redirect the user to the MYDIGIPASS.COM Secure Login authorization endpoint. Corresponds to steps 1, 2, 3 and 4 in Figure 3.1, MYDIGIPASS.COM Secure Login API Authentication Flow. HTTP Request. GET /oauth/authenticate?response_type=code&client_id=xxx... Host: mydigipass.com Parameters Parameter Required? Value response_type Yes Value must be set to "code". client_id Yes The client_id provided to you by VASCO Data Security. redirect_uri Yes The redirect_uri you provided to VASCO Data Security. Table 3.4. MYDIGIPASS.COM Connect Authorization Endpoint Parameters 3.6.3. Exchanging the Authorization Token for an Access Token Corresponds to step 5 in Figure 3.1, MYDIGIPASS.COM Secure Login API Authentication Flow. HTTP Request. POST /oauth/token HTTP/1.1 Accept: */* Connection: close Content-Type: application/x-www-form-urlencoded Content-Length: 184 Host: mydigipass.com code=xxx...&client_secret=xxx... VASCO Data Security 2012 11

Chapter 3. How to implement MYDIGIPASS.COM Secure Login Parameters Parameter Required? Description code Yes The authorization code received from the authorization server. client_id Yes See Section 3.3, Registering your Web Application client_secret Yes See Section 3.3, Registering your Web Application redirect_uri Yes The value must be identical to the redirect_uri you provided to VASCO Data Security (see Section 3.3, Registering your Web Application ). grant_type Yes The value must be set to "authorization_code". Table 3.5. MYDIGIPASS.COM Connect Token Endpoint Call Parameters HTTP Response. {"access_token":"xxx..."} 3.6.4. Retrieving the User Data with the Access Token When you call the user data endpoint you must use the access_token value as a bearer token in the Authorization header. Most libraries will take care of this automatically or can be configured to do so. Corresponds to step 6 in Figure 3.1, MYDIGIPASS.COM Secure Login API Authentication Flow. HTTP Request. GET /oauth/user_data HTTP/1.1 Accept: */* Connection: close Authorization: Bearer xxx... Host: mydigipass.com HTTP Response. {"uuid":"da788f7f-2b74-4a6b-a662-a0f624e93921","city":"london","...} 3.7. Linking your Application Users to their MYDIGIPASS.COM UUID 3.7.1. Tracking your application s users / MYDIGIPASS.COM UUID pairs The following logic is required to track your application s usernames / MYDIGIPASS.COM OAuth UUID pairs. Envision the following scenarios: Scenario User exists in your application? Did you store the user s MYDIGIPASS.COM UUID? 1 Yes Yes 2 Yes No 3 No No Table 3.6. Authentication Scenarios VASCO Data Security 2012 12

Chapter 3. How to implement MYDIGIPASS.COM Secure Login Scenario 1: Include the MYDIGIPASS.COM Secure Login button on the landing page of your web application. Scenario 2: When the user exists in your application and chooses to secure his account with MYDIGIPASS.COM: Provide the MYDIGIPASS.COM Secure Login button, so that the user can secure his account with MYDIGIPASS.COM. When the user successfully authenticates with MYDIGIPASS.COM, associate the retrieved UUID with the user s local account. It is recommended to disable local authentication. Scenario 3: Allow new users to enroll via MYDIGIPASS.COM. Place the MYDIGIPASS.COM Secure Login button on the landing page of your website, so that users can enroll via MYDIGIPASS.COM. After the user has enrolled via MYDIGIPASS.COM, provide a mechanism to create and associate a local account with the returned MYDIGIPASS.COM UUID. It is recommended to disable local authentication. In scenarios 2 and 3, situations may occur where your application receives an unknown UUID. If a user decides to click on the MYDIGIPASS.COM secure login button before logging in to or signing up for your application, MYDIGIPASS.COM will send a UUID to your application. Your application has no way of knowing who the UUID belongs to. By redirecting the user to your application s login / registration page and requesting him / her to provide credentials or sign up, your application can create the required user / UUID pair. 3.7.2. User attributes You can use the user s shared MYDIGIPASS.COM profile attributes. This is recommended because users expect you to automatically update their local profiles with their MYDIGIPASS.COM profile. As users can revoke attribute sharing after the initial registration, make sure your software can handle a variable list of attributes. Do not assume the list or the attributes themselves will always be the same with each authentication. Consequently, you should never use MYDIGIPASS.COM attributes to authenticate users. 3.7.3. In progress page Provide an "in progress" page to users while the back-channel requests are being processed. When a user authenticates successfully with MYDIGIPASS.COM, he / she is redirected to your application with an OAuth authorization code (see step 4 in Figure 3.1, MYDIGIPASS.COM Secure Login API Authentication Flow ). Although this means that the user is authenticated with MYDIGIPASS.COM, your application must still go through steps 5 and 6 to obtain an OAuth access token and the user s UUID. An "in progress" page is advised at this stage, as it tells the user that he / she must wait before the resources can be accessed. It is also useful for error catching or can be used to redirect users in case a problem occurs. Once a user revokes your application s access, that user will not longer be able to sign in to your application via MYDIGIPASS.COM. Provide a mechanism so that users can unlink their application account with MYDIGIPASS.COM. This prevents users from being locked out of your application and allows them to reuse their initial application credentials, if any. 3.8. What s Next? Once you finalized your development cycle and have tested your application against our sandbox environment, you can migrate your sandbox environment to a production environment. To migrate to a production environment: 1. Complete the contact form on https://developer.mydigipass.com. You will be contacted by VASCO shortly afterwards. VASCO Data Security 2012 13

Chapter 3. How to implement MYDIGIPASS.COM Secure Login 2. VASCO will send you the production client_id and client_secret (which are different from the sandbox client_id and client_secret ). 3. Substitute references to sandbox.mydigipass.com with mydigipass.com in your application URLs. VASCO Data Security 2012 14

Chapter 4. Support 4.1. Overview In this section we provide instructions on what to do if you have a problem, or experience a hardware failure. 4.2. If you encounter a problem If you encounter a problem with a VASCO product, follow the steps below: 1. Check whether your problem has already been solved and reported in the Knowledge Base at the following URL: http://www.vasco.com/support 2. If there is no solution in the Knowledge Base, please contact the company which supplied you with the VASCO product. 3. If your supplier is unable to solve your problem, they will automatically contact the appropriate VASCO expert. For details about support capabilities by user, visit: http://www.vasco.com/support/support_services/ types_of_customes.aspx VASCO Data Security 2012 15

List of Figures 2.1. MYDIGIPASS.COM Secure Login Authentication Flow... 5 3.1. MYDIGIPASS.COM Secure Login API Authentication Flow... 8 VASCO Data Security 2012 xvi

List of Tables 3.1. Required data attributes... 9 3.2. Optional data attributes... 10 3.3. Web Application Redirection Endpoint Parameters... 10 3.4. MYDIGIPASS.COM Connect Authorization Endpoint Parameters... 11 3.5. MYDIGIPASS.COM Connect Token Endpoint Call Parameters... 12 3.6. Authentication Scenarios... 12 VASCO Data Security 2012 xvii

List of Examples 2.1. MYDIGIPASS.COM compatible DIGIPASS... 3 2.2. Third-party application accessing photos on Flickr.com... 3 3.1. Handling HTTP Redirects... 11 VASCO Data Security 2012 xviii

Alphabetical Index A Attributes, 6 C Client, 4 Client Application name, 9 Client redirect URI, 9 Client registration, 9 client_id, 9 client_secret, 9 D DIGIPASS as a Service, 1 M MYDIGIPASS.COM, 1 MYDIGIPASS.COM Connect, 3 O OAuth, 3 P Production environment, 8 R Resource owner, 4 S Sandbox environment, 8 U User identifier, 5 UUID, 5, 5