PARTNER INTEGRATION GUIDE. Edition 1.0

Transcription

1 PARTNER INTEGRATION GUIDE Edition 1.0 Last Revised December 11, 2014

2 Overview This document provides standards and guidance for USAA partners when considering integration with USAA. It is an overview of the various integration patterns practiced between USAA and partners. It is not intended to be an exhaustive list of the possibilities. The standards and patterns mentioned should provide a more efficient avenue for establishing connectivity and business capability. The guide outlines policies, standards, and technologies used to integrate securely. All four methods,,, and s are proven and secure. We have the flexibility to adapt to different requirements, and work with a variety of partners and technologies, but do have set standards and guidelines to assist integration. Intended Audience + Partners This document is a reference exhibit for existing and potential USAA partners. It is not intended to be a technical how-to guide for each integration pattern. Full user guides for each pattern are available upon agreement. Patterns s USAA Partner Guide 1

3 Depending on requirements, USAA s file transfer infrastructure can accommodate a variety of transfer styles at the edge. Data feed content and sensitivity will have an impact on the level of security required. Transformation within the endpoint is common, and EDI or XML standards are the most desirable formats. A key factor in smooth integration is the availability of schema or structured formats. These will allow for a much more efficient integration effort. DmZ Internet SFTP HTTPS AS/2 etc Partner(s) USAA Partner Guide 2

4 File Transfer Options OUTBOUND - USAA to External Partner FTP SFTP HTTP HTTPS AS/2 SSL C:D+ DATA SENSITIvITY LESS THAN RESTRICTED RESTRICTED (e.g. PII, PCI, CORPORATE) INBOUND - External Partner to USAA AS/2 FTP SFTP HTTP HTTPS C:D+ SSL DATA SENSITIvITY LESS THAN RESTRICTED RESTRICTED (e.g. PII, PCI, CORPORATE) Approved Approved with PGP USAA Partner Guide 3

5 Web-based commerce should facilitate seamless user interaction between different partner domains (e.g. to This needs to be done securely and transparently, without code development, requiring minimal maintenance. USAA s preferred method of single sign-on is achieved using the SAML 2.0 specification. USAA is configured as an Identity Provider (IdP) supporting SSO for USAA employees and members using third party applications. USAA is not currently configured as a Service Provider (SP) and does not provide a method for external partners to access USAA applications. Supported SSO Profiles Web Browser SSO Profile Assertion Query/Request Profile Supported saml 2.0 protocols Assertion Query and Request Protocol Authentication Request Protocol Logout Protocol Name Identifier Mapping Protocol Supported BINDINGS HTTP POST Supported INTERACTIONS IdP Initiated IdP Initiated with Relay State SP Initiated Service Provider Expectations USAA has separate development, test, and production federation environments. Initial creation of new federation configurations will occur in the development environment. Once development has completed, USAA will move configurations to a stable automated test environment which mimics production. After validation and sign-off have been received in the test environment a release to the production environment will be scheduled. Must support SAML 2.0. Must use one of the USAA supported SSO profiles. Must provide metadata files for each environment. Must be able to support federations from each of USAA s federation environments. USAA will provide separate metadata files for each environment. Must define all required attributes and formats required to complete the SSO. Must provide certificates from a trusted Certificate Authority to perform any required encryptions. Separate certificates are required for Production and Pre-Production environments. Certificates are typically included in the metadata files. Must provide implementation and validation support for renewal of signing and encryption certificates. USAA Partner Guide 4

6 IdP-initiated single sign-on 1. The user clicks a link to initiate the federation. 2. As the Identity Provider (IdP), USAA authenticates the user and sends a signed SAML assertion to the browser, which the browser posts to the Service Provider (SP) assertion consumer. Identity Provider (IdP) Initiated Service Provider 3. The Service Provider (SP) verifies the signed assertion, authorizes the user and redirects the browser to their resource. SP-initiated single sign-on 1. The user clicks a link to request a resource at the Service Provider (SP). 2. The Service Provider (SP) sends a signed authentication request to the browser which posts the request to the USAA federation server. Federation Server 2 1 Post Request Assertion Resource Assertion Consumer 3 Redirect to Resource 3. USAA authenticates the user and sends a signed SAML assertion to the browser, which the browser posts to the Service Provider (SP) assertion consumer. 4. The Service Provider (SP) verifies the signed assertion, logs the user in, and redirects the browser to their resource. Service Provider Service Provider (SP) Initiated Assertion Consumer Federation Server 2 1 Authentication Request Request Resource 4 Redirect to Resource 3 Post Assertion USAA Partner Guide 5

7 User Experience After SSO Seamless Experience Vs. Co-Branded Experience. Products offered by USAA imply a certain level of endorsement and service. The look and feel of pages helps users understand they are visiting and performing tasks on usaa.com. Choosing the right experience (seamless or co-branded) is crucial for third-party solutions to ensure that we meet the user s mental model and service expectations. By preserving a best-in-class member experience, we deliver on the USAA brand promise. Seamless Experience Guidance Look and Feel Visual Elements Seamless solutions have the look and feel of usaa.com. They use USAA s CSS to automatically inherit presentation changes and header and footer styles. No changes can be made to usaa.com information architecture. For example, the look, feel and organization of the USAA global nav cannot be replaced or borrowed by the third-party s navigation structure. URL Seamless solutions should use usaa.com s domain. In certain cases, an exception may be approved for the use of a usaa.com sub-domain. Seamless solutions may use existing USAA business services: Method Option 1 Sends across the header and footer, parameters and static assets (such as header footer and CSS). Option 2 Persists the authenticated session and allows the passing parameters such as member information. Used when directing to another domain. USAA Partner Guide 6

8 Co-Branded Experience Guidance Look and Feel A co-branded solution looks and feels different from usaa.com. It does not attempt to copy the design of usaa.com. The difference should be clear enough so users are aware they are no longer on usaa.com. Co-branded solutions must include: Visual Elements The USAA logo The logo must be included at the top of the page and sized no smaller than 75% and no larger than 100% of the size as seen on usaa.com. The logo must use the USAA brand color. It may be located either at the top right or top left of the page. However, the USAA logo can be adjusted if need be based on the partner s color scheme. A link back to usaa.com The link must clearly read Back to usaa.com and be no smaller than 11px in height. The link should be blue but may vary in hue according to what matches best in context. The link and icons need to be part of the global navigation so they are always accessible from any page on the third-party s site. URL Co-branded solutions do not use a sub-domain of usaa.com. Method Applications that are co-branded use a USAA service which persists the authenticated session and allows the passing parameters such as member information. Used when directing to another domain. USAA Partner Guide 7

9 USAA has a set of infrastructure components deployed to facilitate the intake of near real-time activity events into the enterprise from external partners. Business activity data may be used by business areas within USAA to perform analysis about events performed by users on partner sites. The infrastructure contains a collection of endpoints through which the partner interfaces to send the events. The service collects information directly from the web browser using JSON submitted over HTTPS to receive events submitted from third party provider web sites. Key events to this integration pattern: Schema(s) 1. Overview and approach session between USAA and partner. 2. Identify third party provider test environment. 3. Integrate with USAA to receive required data from a USAA site redirect. DmZ Endpoint(s) 4. USAA provides WSDL file or code/tag (depending on requirement). 5. Describe required values for each field exchanged via SOAP message. 6. USAA provides the credentials necessary to authenticate the web service call. 7. Partner supplies IP addresses sending data to USAA to enable request to pass through USAA. 8. Perform testing and implementation. Partner(s) manifest USAA Partner Guide 8

10 USAA supports integration via SOAP 1.1 and REST* with JAX-RS 1.1. Scenario 1: usaa is calling an external partner web service Security is achieved via either Mutual Authentication or Basic Authentication if partner does not support Mutual Authntication. USAA expects partner to provide certificate and/or credentials. Partner to provide WSDL to USAA. DmZ (XmL Gateway, etc) Scenario 2: Partner is calling a usaa web service Security is achieved only via Mutual Authentication. We do not expose services using Basic Authentication. USAA provides necessary certificate(s) which must be placed on partner s network. USAA provides WSDL to partner. Internet Partner(s) USAA Partner Guide Notes * For RESTful service integration, Mutual Authentication is preferred. USAA expects service documentation in the form of a WADL or similar description document. 9