DIGIPASS as a Service. Product Guide

Transcription

1 DIGIPASS as a Service Product Guide October 2011

2 Table of Contents 1. Introduction Audience and Purpose of this Document... Available Guides... What is DIGIPASS as a Service?... About VASCO Main Objectives of DPS Overview... Strong Authentication... Identity Federation and Single Sign-On... Signing Online Transactions... Provisioning and Decommissioning... Easy Application Management... Centralized Maintenance DPS Environments DPS Resources Organisations and Applications Users and User Accounts Authenticators What is an Authenticator? Supported Types Assignment Restrictions Operators and Roles Summary Integrating DPS Overview Organisation-Specific Applications External Applications SP-Initiated Authentication DPS-Initiated Authentication Supported Applications Policies DPS Interfaces and Services Overview The Web Administrator Tool Web Services Definition The SOAP API The REST API SSO for External Applications using SAML The DPS Portal SSL/TLS Encryption Introduction ii

3 Keys and Certificates Server-only Authentication Mutual Authentication Use Cases Overview Users and User Accounts Getting a new User Started Adding additional Accounts to Existing Users Scenarios for locking Users and User Accounts Removing Accounts Authenticator Management Assigning one Authenticator to an Account Assigning Multiple Authenticators to a Single Account Configuring Virtual DIGIPASS as a Backup Unassigning an Authenticator Client-Side Unlocking of Authenticators Server PIN Actions Authenticator Life Cycle Handling Lost or Stolen Authenticators Handling Broken Authenticators Support Overview If you encounter a problem Return procedure if you have a hardware failure A. Authenticator Life Cycle Phases B. DPS Resource Statuses C. DPS Login Permutations Alphabetical Index iii

4 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 ORGANIZATION 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, REGARDLESS OF THE CAUSE OF THE LOSS, INCLUDING NEGLIGENCE, EVEN IF VASCO HAS BEEN ADVISED 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 APPLY 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 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 2011 VASCO Data Security, Inc, VASCO Data Security International GmbH. All rights reserved. Date Last Updated : 28/10/2011 iv

5 Chapter 1. Introduction 1.1. Audience and Purpose of this Document This document is intended for developers and technical experts who wish to integrate DPS Authentication with their organisation s online applications. It describes the structure and concepts underpinning the product, and how DPS can secure your organisation s online applications. In Section 1.3, What is DIGIPASS as a Service? and Section 1.4, About VASCO, we introduce DIGIPASS as a Service and VASCO. In Chapter 2, Main Objectives of DPS, we explain the purpose of the DPS platform and how you can use it to integrate strong authentication methods with your online applications. In Chapter 3, DPS Environments, we explain the separate DPS environments, i.e. the proof of concept and the production environment. In Chapter 4, DPS Resources, we explain the various DPS resources, i.e. Organisations, Applications, Users, User Accounts, Authenticators and Operators and how these resources relate to each other. In Chapter 5, Integrating DPS, we explain the subtle difference between organisation-specific and external applications. We also define DPS policies. In Chapter 6, DPS Interfaces and Services, we explain the various DPS interfaces that are available to manage your DPS resources. We also explain the concept of Mutual Authentication. In Chapter 7, Use Cases, we explain some recommended procedures, such as what to do when an Authenticator is lost or stolen. In Chapter 8, Support, we explain how to request support Available Guides The set of DPS documentation includes: Conceptual documentation: DPS Product Guide, where we explain the concepts underpinning DPS and how DPS can provide authentication for your organisation s online applications. This guide also provides the procedures to securely manage DPS resources, such as Users, Accounts, Authenticators, etc. Howto guides: DPS Web Administration Guide, where we explain how to manage DPS Operators, Roles, Applications, Users and Authenticators via its web-based administration tool. DPS REST Howto, where we explain how to build REST API calls using HTTP CRUD operations. DPS SOAP Howto, where we explain how to build SOAP API calls. DPS Google Apps Integration Guide, where we explain how to integrate DPS Authentication with Google Apps. DPS Salesforce Integration Guide, where we explain how to integrate DPS Authentication with Salesforce. Reference material: DPS SOAP Reference Guide, which is a technical reference document listing all available SOAP API calls. DPS REST Reference Guide, which lists all DPS Resources and how they can be addressed via REST. All documents can be downloaded via the Web Administrator Tool s Help function. 1

6 Chapter 1. Introduction 1.3. 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-B application owners sometimes face a number of barriers to the deployment of two-factor authentication for their user base. Sometimes 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-B 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 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. For further information, please visit 2

7 Chapter 2. Main Objectives of DPS 2.1. Overview DIGIPASS as a Service or DPS is VASCO s cloud based authentication service which makes use of VASCO s proprietary authentication technology. In this chapter, we explain the main goals of DPS and the different services that it provides, including: Strong authentication for your online applications Single Sign-On for the users of your online applications Signing of online transactions Provisioning and decommissioning of authenticators Application management Centralized maintenance 2.2. Strong Authentication The Vulnerabilities of One-Factor Authentication. The most commonly used Authentication Method is the username / static password combination. Only one factor comes into play, which is something the user knows, i.e. the username and static password combination. One-Factor Authentication is inherently less secure than Two-Factor Authentication, because complex static passwords are hard to remember and many users tend to write them down somewhere near their workstation. Static Passwords are also prone to social hacking, a technique to persuade users to release personal information, such as passwords. Furthermore, Static Passwords can easily be stolen and used by a third party to impersonate the actual user or access the user s personal data. Enhanced Security with Two-Factor Authentication. Two-Factor Authentication is a Strong Authentication Method requiring two factors: Something the user knows, i.e. a DIGIPASS PIN needed to generate a One-Time Password (OTP). Something the user has, which is the DIGIPASS itself. Two-Factor Authentication eliminates the vulnerabilities associated with One-factor Authentication, as explained above. Client PIN. A client PIN is a digit-based secret provided to and only known by the user. The user needs to enter this PIN on the authenticator before an OTP can be generated. If the user fails to enter the correct PIN a subsequent number of times, the authenticator will be locked as a security precaution. An authenticator can be unlocked either: Via the web-based administration tool. See the Web Administration guide for details. Via DPS Web Services, i.e. SOAP or REST. See the relevant documentation for details. Server PIN. A client PIN cannot be used with one-button DIGIPASS models. You can overcome this restriction by using a Server PIN. The Server PIN provides a way to implement two-factor authentication for DIGIPASS models that do not support a client PIN; a Server PIN can be used together with the OTP generated by the DIGIPASS device, as part of the on line authentication process. The Server PIN is a digit-based secret, typed in by the User into the login password field in front of the OTP and is checked by the authenticating server. The server only permits verification of the OTP if submitted with a valid Server PIN. The Server PIN thus provides an extra layer of security, an alternative 2-factor security solution. To authenticate, the holder needs to have a connection to the authenticating server, to know the Server PIN (something you know), and to be in 3

8 Chapter 2. Main Objectives of DPS possession of the DIGIPASS device (something you have) to generate an OTP. A detailed list containing each Server PIN / DIGIPASS pair is included with your order. The Server PIN of a DIGIPASS can be modified either: Via the web-based administration tool Via DPS web services, i.e. SOAP or REST. See the relevant documentation for details. The use of the Server PIN can be disabled via the web-based administration tool. For details, see the Web Administration Guide. Users can change their Server PIN: By authenticating successfully (see Appendix C, DPS Login Permutations). Via a dedicated web service, i.e. SOAP or REST (see the appropriate SOAP or REST documentation). Via the web-based administration tool (see the Web Administration Guide). About DIGIPASS Modes. The DIGIPASS mode is the method used to generate an OTP or a signature on a DIGIPASS. Each DIGIPASS is programmed with at least one DIGIPASS Application and a unique secret. The DIGIPASS Application uses this secret when generating One Time Passwords and Signatures. Each type of DIGIPASS Application generates One Time Passwords or Signatures from different data, and in slightly different ways: Response Only Mode: Creates a One Time Password based on the current date and time or on the number of uses (events). Challenge/Response Mode: Creates a One Time Password (also referred to as a Response) based on a numerical challenge given on a login page. This may be either a challenge custom-created for the specific DIGIPASS, or a randomly created challenge. The One Time Password may also be based on the date and time. Digital Signature Mode: Digital Signature DIGIPASS Applications are typically used for online banking. The DIGIPASS generates a unique code - referred to as a Digital Signature - based on a number of entered transaction data fields, plus (optionally) the date and time or number of uses (events) Identity Federation and Single Sign-On Identity federation creates a greater level of security, protecting your company s critical data and online assets. Identity Federation provides users safe access to applications across the Internet using VASCO s strong authentication technology. It reduces the need to maintain user profiles on multiple systems. An other important aspect, Secure Internet Single sign-on, reduces security gaps by using a trusted connection between the VASCO DPS infrastructure, also known as the identity provider, and the service provider. Single Sign-on allows users to authenticate once and access any system available to them, rather than being prompted to authenticate for each application separately. Using secure Internet Single Sign-on, Identity federation allows you to: Greatly reduce the chance of getting "Phished" Prevent data theft and destruction Leverage existing identity infrastructure Utilize secure standards 4

9 Chapter 2. Main Objectives of DPS Figure 2.1. DPS Federated Identity Concept Currently, Single Sign-On is only supported for Google Apps and Salesforce. Other applications may be supported in the future Signing Online Transactions DPS allows you to sign transaction data using an authenticator that is set up to generate digital signatures. A digital signature is based on transaction details entered into the authenticator, e.g. a hardware DIGIPASS. The authenticator uses the transaction details and an embedded secret to generate a signature, which is typically entered into a confirmation page to proceed with the transaction. If the signature is invalid, the transaction is aborted. The signing of online transactions is only possible via the REST API. See Section 6.3.3, The REST API for details Provisioning and Decommissioning Provisioning involves the following administrative procedures: Creating Users and User Accounts Assigning Authenticators to User Accounts (Hardware and Software) Distribution and activation of software DIGIPASS Decommissioning involves the following administrative procedures: Removal of Users and User Accounts 5

10 Chapter 2. Main Objectives of DPS Unassigning Hardware or Software DIGIPASS Authenticators Provisioning and decommissioning can be done: Manually, via the DPS Web Administrator Tool Automatically via SOAP or REST calls (See Chapter 6, DPS Interfaces and Services for details) Easy Application Management Applications are created and managed by VASCO on demand. Organisations can create Accounts for the Applications: Manually with the DPS Web Administrator Tool Automatically with SOAP or REST calls See Chapter 6, DPS Interfaces and Services for details. Management tasks include : Registration and removal of Users and User Accounts Provisioning and decommissioning of Hardware and Software Authenticators Monitoring and reporting (only available via the Web Administrator Tool) Troubleshooting end-user issues (only available via the Web Administrator Tool) 2.7. Centralized Maintenance The entire DPS server infrastructure is ran and maintained centrally by VASCO. The advantages of this approach are: Regular DPS updates, including the latest feature and software security upgrades. High Availability and backups; VASCO uses failover systems to ensure the best quality and continuity of service. Centralized technical support for your DPS-secured organisations. 6

11 Chapter 3. DPS Environments VASCO provides separate environments for demo and commercial accounts, i.e. a proof of concept and a production environment. The proof of concept environment allows new users (holders of demo accounts) to get acquainted with and explore the possibilities of DPS, while existing customers can use it to test changes without affecting their setup on the production environment. To access the proof of concept environment, simply replace dps with dpp in all the URLs that are provided throughout the documentation. Base URL to be used for the proof of concept platform (demo accounts): Base URL of the production environment: You cannot access the production environment with a demo account. To upgrade your account, contact your sales representative. 7

12 Chapter 4. DPS Resources 4.1. Organisations and Applications On DPS, organisations are entities (such as companies, schools, hospitals, government institutions, etc.) which host (a) DPS-secured software application(s) on their server infrastructure. Users can access this / these online application(s) from virtually anywhere, as long as they have a valid DPS Account and an Authenticator. Policies define the required work flows and parameters to access a DPS-secured Application. Policies are configured by VASCO as part of the DPS service contract and can be customized if necessary. Policy examples include, but are not limited to: Hardware: a hardware authenticator must be used to authenticate, e.g. a DIGIPASS. Static Password: a static password is used for authentication. Static passwords are insecure and should only be used during a DIGIPASS rollout phase. Policies that are specific to external applications, such as Google Apps and Salesforce Users and User Accounts Users: A DPS User is a person who is authorized to access DPS-secured application(s) and is uniquely referenced by an Identifier. Other user properties include, but are not limited to, the first and last name, a mobile number, an address. User Accounts: A User Account consists of a set of login credentials and an authentication method, e.g. a Hardware DIGIPASS, to access an organisation s DPS-secured application. A DPS User can have multiple accounts. The number of accounts your organisation is entitled to is determined by your service contract. If you require additional accounts, contact your sales representative Authenticators What is an Authenticator? Authenticators are devices for generating One-Time Passwords (OTPs). They are the client side component of VASCO s Two-Factor authentication solution, issued by a DPS-secured organisation to its Users. A User can have more than one Authenticator, for example a one-button Hardware DIGIPASS GO 7 and a software DIGIPASS for Web. Authenticators all have a life cycle, i.e. a set of states, which are explained in Appendix A, Authenticator Life Cycle Phases. For details about Two-Factor authentication and Authenticator properties, see Section 2.2, Strong Authentication Supported Types DIGIPASS Software: products in this group run on existing non-vasco platforms, such as PCs, mobile phones and palm tops etc. DIGIPASS Software includes DIGIPASS for Web (fully browser-based), DIGIPASS for Windows (client-based), DIGIPASS for Mobile Phone (JAVA-based) and the Virtual DIGIPASS (server-based authentication). These products thus re-use existing and familiar end-user devices. 8

13 Chapter 4. DPS Resources DIGIPASS Keys: products in this group are VASCO specific USB connected devices that can be used to generate OTPs. They also support Electronic Signature features and can extend the use of VASCO products to digital signing for a Public Key Infrastructure (PKI) environment. DIGIPASS Hardware: products in this group are VASCO specific hardware platforms pre-programmed individually with secret values. DIGIPASS Hardware does not re-use existing infrastructures or smart cards, and can therefore be implemented by any organisation. DIGIPASS Readers: products in this group include connected and unconnected models. DIGIPASS Readers combine secret values, which are stored in the smart cards, with DIGIPASS algorithms pre-programmed into the DIGIPASS reader, which also provides the user interface. These products optimize investment in smart card technology, by extending smartcard use to include OTPs and Electronic Signatures. Table 4.1. DIGIPASS family groups Virtual DIGIPASS. Virtual DIGIPASS is a mechanism where an OTP is generated by the server and sent to the User s mobile phone. In this case, a physical DIGIPASS device is not needed. The request for an OTP can be initiated via the DPS Web Services (REST or SOAP) or via the web-based administration tool. See the related documentation for details. Example 4.1. Using Virtual DIGIPASS as a Backup Authenticator Virtual DIGIPASS can be used instead of hardware DIGIPASS tokens, or as a backup mechanism when a User has misplaced their hardware DIGIPASS. Example 4.2. Using Virtual DIGIPASS as a Primary Authenticator Virtual DIGIPASS can be used as primary authenticator if the DPS-secured application is only used occasionally Assignment Restrictions An Authenticator, e.g. a Hardware DIGIPASS, can only be assigned to one person, i.e. a DPS User. A DPS User can have one or multiple User Accounts. In turn, one or more Authenticators can be assigned to a User Account. A User Account can be configured to access a single or multiple DPS-secured Applications. It is possible to use one Authenticator for multiple applications or to assign separate Authenticators per application. See Figure 4.1, DPS Authentication Flow and Resources for a graphical representation Operators and Roles An Operator is a person who can administer DPS Resources, such as Users and Accounts. The resources can be managed via the DPS Web Administrator Tool, which requires an Operator Account. The access level of an Operator is determined by his / her role. 9

14 Chapter 4. DPS Resources Operator Accounts cannot be used to authenticate for a DPS-secured application. In most cases, DPS Resources are managed via the DPS Web Services, i.e. SOAP and REST. The current DPS version supports the Administrator Role and the Reader Role. Organisation Administrators: Are allowed full control and are allowed every available access right. Organisation Readers: Can view the same objects as Administrators, but are not allowed to make any changes Summary Users who surf the Internet use online Applications of an organisation, e.g. applications provided (and hosted) by their company or application providers such as, Google, Salesforce, etc. These applications can be secured by DPS to enforce two-factor Authentication. To access a DPS-secured application, Users must authenticate. To authenticate, Users need an Authenticator, a software or hardware device which generates One-Time Passwords (OTP). A User can have several User Accounts and one or more Authenticators. When a User authenticates to access a DPS-secured application, the organisation hosting the application checks the provided credentials against DPS, which uses Policies to define the authentication work flow. A work flow dictates the steps Users must follow to successfully authenticate for a given application. Operators are special accounts used to manage DPS Resources, such as an organisation s Users and Accounts. An Operator s access level is determined by his / her Role in DPS. Figure 4.1. DPS Authentication Flow and Resources 10

15 Chapter 5. Integrating DPS 5.1. Overview In this chapter, we explain the difference between organisation-specific applications and external applications on the DPS platform. Technically speaking, both are very similar, but they present some small differences, which we explain further. For practical guidance, see the Web Administration Guide, the SOAP Howto and the REST Howto. A list of guides is provided in Section 1.2, Available Guides Organisation-Specific Applications In DPS terms, an organisation-specific application is a cloud-based service provided by an organisation for which users must authenticate. Users authenticate via a custom interface, running on a server in the cloud, provided by that organisation. User credentials are relayed to and checked by DPS, using the SOAP or REST protocol, which we explain further in this guide. Note that other protocols may be supported in the future. The application itself is designed specifically for (and possibly, but not necessarily by) the organisation and the application s parameters to communicate with DPS are tailored especially by VASCO in accordance with the organisation s guidelines and provided specifications. Any application on DPS is controlled by one or multiple policies, which we briefly explain in Section 5.4, Policies External Applications In DPS terms, an external application is almost identical to an organisation-specific application, i.e. a cloudbased service provided by an organisation for which users must authenticate. An external application differs from an organisation-specific application in that: rd The application is not controlled or designed by the organisation itself, but by a 3 party, such as Google. Organisations who want to use external applications on DPS, must adhere to the specifications and protocols used by this external application, i.e. organisations or VASCO don t have direct control over the external application. An external application must be used and implemented as is. Currently, VASCO s DPS platform offers two-factor authentication for Google Apps and Salesforce. Other external applications may be supported in the future. Both external applications use the SAML protocol, which we explain further in this guide. To access their external application(s), users can either authenticate via the DPS portal, referred to as DPSinitiated authentication or via the portal of the external application, referred to as SP-initiated authentication SP-Initiated Authentication SP-initiated or Service Provider-initiated Authentication means that users authenticate via the interface hosted by an organisation. The credentials are then securely relayed to DPS for verification DPS-Initiated Authentication With DPS-Initiated Authentication, end-users authenticate for a cloud-based application via the DPS portal: where organisation_name must be replaced by the name of your organisation. Note that holders of demo accounts must use organisation_name instead (also see Chapter 3, DPS Environments). If authentication is successful, a browser-based Single Sign-On session is started. The user is then automatically redirected to a web page where he or she can select the appropriate application. When users click on an application link, they are redirected to the site hosting the application. For information about the DPS portal, see Section 6.4, The DPS Portal. 11

16 Chapter 5. Integrating DPS The user can access any of his / her applications while the browser session is valid Supported Applications The DPS platform currently offers strong authentication and SSO for the following external applications: Google Apps Salesforce See the relevant guides for detailed information Policies Policies define the required work flows and parameters to access a DPS-secured Application. Policies are configured by VASCO as part of the DPS service contract and can be customized if necessary. Policy examples include, but are not limited to: Hardware: a hardware authenticator must be used to authenticate, e.g. a DIGIPASS. Static Password: a static password is used for authentication. Static passwords are insecure and should only be used during a DIGIPASS rollout phase. Policies that are specific to external applications, such as Google Apps and Salesforce. 12

17 Chapter 6. DPS Interfaces and Services 6.1. Overview In this chapter, we explain the interfaces and services that are available on the DPS platform, i.e. The Web Administration Tool Web services, such as the SOAP API, the REST API and SSO via SAML The DPS portal SSL/TLS Encryption 6.2. The Web Administrator Tool The Web Administration Tool is a browser-based tool that allows DPS-secured organisations to administer their DPS resources, such as Users, User Accounts and Authenticators via a dashboard (shown in the image below). Troubleshooting and reporting tools are also available. Note that typically, DPS resources are managed via the Web Services, e.g. the SOAP or REST API. The Web Administration tool can be a useful backup solution if you are experiencing some problems with SOAP or REST calls. Figure 6.1. The DPS web-based Dashboard Access to an organisation s Applications is managed by Operators who are assigned Roles, as explained in Section 4.4, Operators and Roles. Operator accounts are managed and issued by VASCO as a part of the DPS service contract. The use of the Web Administrator Tool is explained in the DPS Web Administration Guide (see Section 1.2, Available Guides ). 13

18 Chapter 6. DPS Interfaces and Services 6.3. Web Services Definition A DPS Web Service is an Application Programming Interface (API) on the DPS platform that can only be accessed over HTTPS with a secret API key. Code is executed on a system of a DPS-secured organisation, which interacts with a given DPS Web Service, using a certain protocol, e.g. the REST API. Examples of well known APIs include: the Facebook login API, the Twitter login API, etc. Currently, DPS offers Web Services that support the following protocols: SOAP REST SAML (For external applications only) Other protocols may be supported in the future The SOAP API DPS resources, i.e. Users, Accounts and Authenticators, are accessible via the DPS SOAP Web Service, referred to as the Application Service Provider Interface (ASPI). SSL/TLS encrypts all traffic between the DPS-secured organisation and DPS. SOAP calls (bindings) are explained in the SOAP Howto and the SOAP Reference Guide (see Section 1.2, Available Guides ). To create a SOAP binding over HTTPS, you must: Set up SSL/TLS handling as explained in Section 6.5, SSL/TLS Encryption. Configure IP restrictions: the IP address(es) from which users may authenticate. Typically this is the address range of the server(s) hosting the DPS-secured application. Create the SOAP binding for your application. Most programming languages include these types of bindings and tools to implement such bindings are plenty available The REST API DPS resources, i.e. Users, Accounts and Authenticators, are accessible via the DPS REST Web Service, referred to as the Application Service Provider Interface (ASPI). SSL/TLS encrypts all traffic between the DPSsecured organisation and DPS. REST calls are explained in the REST Howto and the REST Reference Guide (see Section 1.2, Available Guides ). Representational State Transfer (REST) has gained widespread acceptance across the Internet as a simpler alternative to SOAP- and Web Services Description Language (WSDL)-based Web services. REST defines a set of architectural principles by which you can design Web services that focus on the VASCO DPS resources, including how resource states are addressed and transferred over HTTPS by a wide range of clients written in different languages. REST-style architectures consist of clients and servers. Clients initiate requests to servers, i.e. DPS; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. On DPS, resources are represented in XML. A resource can be essentially any coherent and meaningful concept that may be addressed, e.g. a User, a User Account, an Authenticator, etc. Other resource representations may be supported in the future. 14

19 Chapter 6. DPS Interfaces and Services Figure 6.2. REST Concept One of the key characteristics of a RESTful Web service is the explicit use of HTTP methods in a way that follows the protocol as defined per RFC HTTP GET, for instance, is defined as a data-producing method that s intended to be used by a client application to retrieve a resource, i.e. to fetch data from DPS. REST asks developers to use HTTP methods explicitly and in a way that s consistent with the protocol definition. This basic REST design principle establishes a one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods. CRUD: Create, Read, Update and Delete In computer programming, Create, Read, Update and Delete (CRUD) are the four basic functions of persistent storage. Sometimes CRUD is expanded with the words retrieve instead of read or destroy instead of delete. It is also sometimes used to describe user interface conventions that facilitate viewing, searching, and changing information; often using computer-based forms and reports. According to this mapping: POST is used to create a REST resource on DPS GET is used to read (retrieve) a DPS REST resource PUT is used to update the state of a DPS REST resource DELETE is used to delete a DPS REST resource. To create a REST binding over HTTPS, you must: Set up SSL/TLS handling as explained in Section 6.5, SSL/TLS Encryption. Configure IP restrictions: the IP address(es) from which users may authenticate. Typically this is the address range of the server(s) hosting the DPS-secured application. Create the REST binding for your application. Most programming languages include these types of bindings and tools to implement such bindings are plenty available. For details about the REST API, see the REST How To and the REST Reference guide, which are accessible via the Help button. 15

20 Chapter 6. DPS Interfaces and Services SSO for External Applications using SAML The following applies to external applications only (see Section 5.3, External Applications ). The services on DPS can be accessed via SAML over HTTPS. In this section we provide some basic information about the SAML (Security Assertion Markup Language) protocol. For details about SAML, see the OASIS online documentation repository: SAML allows the secure exchange of authentication and authorization data between security domains, which are separate organizations or companies. DPS acts as the Identity Provider and asserts the user s identity and authentication via strong authentication mechanisms, such as a hardware DIGIPASS. Once a user is authenticated via DPS and selects a given Web Application, the user s identity as known by DPS is transparently converted into a SAML assertion. This assertion is digitally signed and encrypted to ensure the authenticity of the transaction, before being forwarded to the organisation hosting the DPS-secured application. The organisation s application server receives the assertion, verifies whether it is authentic, decrypts the contents and provides this information to the hosted application, which uses this information to authenticate the user. This is known as Single Sign-On (SSO). The SAML processes to authenticate a User are depicted in the figure below. Users can authenticate via the DPS Portal or via the authentication page of the DPS-secured application, as explained in Section 5.3.1, SP-Initiated Authentication, Section 5.3.2, DPS-Initiated Authentication and Section 6.4, The DPS Portal. Figure 6.3. SSO with SAML 1. The user requests a target resource (an application hosted by a given organisation) with a browser, by navigating to a specific URL. If a valid security context* (i.e. the user is already authenticated) already exists on the Identity Provider s side, skip steps

21 Chapter 6. DPS Interfaces and Services 2. The organisation s application server responds with a document containing URL and authentication parameter information. 3. The user agent issues a request to the SSO service running on the Identity Provider side (DPS) where the value of the SAML Request parameter is taken from the information obtained in step 2. The SSO service processes the Authentication Request and performs a security check. If the user does not have a valid security context* (see step 1), the identity provider identifies the user. 4. The SSO service validates the request and responds with a document containing authentication parameters. 5. The user agent (browser) issues a request to the assertion consumer service on the side of the organisation s application server. The value of the SAML Response is taken from the document containing authentication parameters (see step 4). 6. The assertion consumer service processes the response, creates a security context* on the organisation s side and redirects the user agent (browser) to the target resource. 7. The user agent (browser) requests the target resource from the organisation s application server (again). 8. Since a security context* exists, the application of the organisation returns the resource to the user agent (browser). A security context is the information that describes a particular user s identity and capabilities on a computer. The security context is established via a browser session The DPS Portal The DPS Portal is a URL which serves as a single entry point to access your DPS-secured external applications, such as Google Apps and Salesforce. The advantage is that you only have to remember or bookmark a single URL to authenticate for these applications. The address of the DPS Portal is: portal/your_org_name. Note that holders of demo accounts must use instead (also see Chapter 3, DPS Environments). Figure 6.4. DPS Portal Login Screen 17

22 Chapter 6. DPS Interfaces and Services 6.5. SSL/TLS Encryption Introduction DPS Web Services, i.e. SOAP and REST, allow organisations to secure their online applications with DPS. The Web Services are only accessible via HTTPS. Communications between customers and DPS are encrypted with the SSL/TLS (Security Sockets Layer) protocol. This allows two types of authentication: Server-only authentication: Authentication of the DPS platform with the organisation s application server. Mutual authentication: Authentication of the DPS platform with the organisation s application server and vice-versa. The setup of both authentication types is explained in the SOAP and REST Howtos (see Section 1.2, Available Guides ). SSL/TLS uses key pairs and certificates to encrypt and authenticate network traffic. While a detailed explanation of SSL/TLS is outside the scope of this manual, we briefly explain the relevant concepts in the next sections Keys and Certificates For Server-only Authentication, VASCO s DPS platform uses a public/private key pair with a corresponding certificate issued by VASCO. To implement Mutual Authentication, DPS and the DPS-secured organisation need a public/private key pair with corresponding certificates. The VASCO root certificate is used to: Sign certificates issued by the Web Services and sign Web Service Server certificates Validate other certificates which are being used to authenticate a party Type Use Generated by Signed by Purpose Root Server-only and Mutual authentication VASCO Self-signed Signing certificates of issuing Web Services and Server certificates Issuer Mutual tion authentica- VASCO Root Issuance of client certificates Client Mutual tion authentica- Organisation or VASCO Issuer Authentication of Organisation with DPS Server Server-only and Mutual authentication VASCO Root Authentication of DPS with Organisation Table 6.1. Web Services key pairs and certificates 18

23 Chapter 6. DPS Interfaces and Services Figure 6.5. Web Services Certificate Hierarchy Server-only Authentication The DPS-secured organisation requires no special configuration. The certificate configuration is entirely handled by VASCO Mutual Authentication Organisations can choose how to manage their public/private key pairs and certificates: Organisations can generate and manage the client public/private key pair themselves. In that case, the organisation s private key is never disclosed. (This option is recommended in a high security environment). VASCO can generate the key pair for your organisation. In that case, VASCO is in possession of the private key. This option is more convenient, but far less secure. VASCO always generates the Web Services Client certificate, even if an organisation manages its client key pair. Instructions about acquiring a Web Services client key pair and certificate is available in the SOAP and REST Howtos (see Section 1.2, Available Guides ). 19

24 Chapter 7. Use Cases 7.1. Overview In this section we explain the best practices to manage DPS resources such as Accounts, Users and Authenticators in different scenarios. DPS resources can be addressed and managed via: SOAP REST The Web Administration Tool. Other protocols may be supported in the future. The calls and resources to be used for the SOAP and REST API are provided in the respective Reference Guides, which can be accessed by clicking on Help Users and User Accounts Getting a new User Started In this scenario, we assume that a new employee is starting in your organisation. He / she needs access to your organisation s DPS-secured application(s). Depending on the application to be accessed, you ll need to follow different procedures. For organisation-specific applications (SOAP and REST) Create a new User record and provide the new employee s data. Create an Account for each DPS-secured application the employee needs to access. For external applications (Google Apps, Salesforce using SAML) Create a new User record and provide the new employee s data. Create an Account for the DPS portal application. Create a new Account using the appropriate policy. Use the login as know by the external application, e.g. Google Apps Adding additional Accounts to Existing Users In this scenario, we assume that an employee needs an additional Account for a DPS-secured application. Depending on the application to be accessed, you ll need to follow different procedures. For organisation-specific applications (SOAP and REST) Locate the employee s User record on DPS Create the appropriate SOAP / REST Account For external applications (Google Apps, Salesforce using SAML) Locate the employee s User record on DPS Create the appropriate Account, using the appropriate policy. Use the login as know by the external application, e.g. Google Apps. 20

25 Chapter 7. Use Cases Scenarios for locking Users and User Accounts Three different scenarios are possible: 1. The User temporarily doesn t need access to his DPS-secured applications, but will need access again in the future. 2. The User requires access to some, but not all of his applications. 3. The User is no longer authorized to access his applications, e.g. the employee no longer works for the organisation. In case the User doesn t require access to his / her application(s) for a long period: Locate the User Record on DPS. Flag the User as disabled. In case you need to limit the User s access to some of his / her DPS-secured applications: Locate the User s record on DPS Locate the appropriate Account(s) and disable it (them). In case the User is no longer authorized to access his applications: Locate the User Record on DPS. Delete the User Record. When a User is deleted, the life cycle status of the his/her Authenticator(s) will be changed to free. If the User s Authenticator(s) is/are lost or stolen, disable the appropriate Authenticator serial number(s) as explained in Section 7.4, Authenticator Life Cycle, before deleting the User s record. It is recommended to delete Users who are no longer authorized to access DPS-secured applications. This automatically removes their Accounts. The audit logs of a User are never deleted from DPS, regardless of whether or not a User has been deleted Removing Accounts In this scenario, we assume that the User no longer needs the account or that the User is no longer authorized to access the application. For organisation-specific applications (REST or SOAP) Locate the account record on DPS Delete the account using the appropriate call For external applications (Google Apps, Salesforce using SAML) Locate the account record on DPS Delete the account using the appropriate call An account can only be removed if only one Authenticator or Static Password is associated with that account. If more than one Authenticator is assigned, the Authenticators must be unassigned before the account can be removed (see Section 7.3, Authenticator Management ). For external applications: If access to the DPS Portal is no longer required, the Portal account may be deleted as well, as an additional security precaution. 21

26 Chapter 7. Use Cases 7.3. Authenticator Management Assigning one Authenticator to an Account See Section 7.2.1, Getting a new User Started for new users See Section 7.2.2, Adding additional Accounts to Existing Users for existing users Assigning Multiple Authenticators to a Single Account For organisation-specific applications (REST or SOAP) Follow the same steps as explained in Section 7.2.1, Getting a new User Started and Section 7.2.2, Adding additional Accounts to Existing Users for the assignment of the first DIGIPASS to the account (new user or existing user). Locate the user for which a user account was created in the first step and add a new account with an identical login, but assign a different DIGIPASS. Repeat the steps until all required DIGIPASS are assigned. For external applications (Google Apps, Salesforce using SAML) Follow the same steps as explained in Section 7.2.1, Getting a new User Started and Section 7.2.2, Adding additional Accounts to Existing Users for the assignment of the first DIGIPASS to the account (new user or existing user). Locate the user for which a user account was created in the first step and add a new portal account with an identical login, but assign a different DIGIPASS. Repeat the steps until all required DIGIPASS are assigned Configuring Virtual DIGIPASS as a Backup For this to work, the User must have an account to which a non-virtual DIGIPASS (hardware or software) has been assigned. Then an account must be added selecting the Virtual DIGIPASS policy. Integrators are advised to include an option for Users to submit a Virtual DIGIPASS OTP request via the login page of their DPS-secured application. Follow the same steps as explained in Section 7.3.2, Assigning Multiple Authenticators to a Single Account, but in step 2 assign a Virtual DIGIPASS instead Unassigning an Authenticator To unassign an Authenticator, i.e. setting an Authenticator to a free state so that it can be assigned to another User or account: Locate the account ID to which the Authenticator is assigned Delete the account ID If only one Authenticator has been assigned to the account, the account will be deleted when the Authenticator is unassigned. If the account has been assigned multiple Authenticators, the account is not deleted Client-Side Unlocking of Authenticators For security, an Authenticator is automatically locked after a user repeatedly enters the wrong Client PIN. Once an Authenticator is locked, it displays a challenge. The challenge must be submitted to DPS so that 22