Auth Auth Ident v3.2

Authentication /Authorization / IdentificationSDK

http://bos.ea.com

Version 3.2a

ConfidentialFor use by EA.com developers onlyLevel: Family

Published October , 2001

EA.comElectronic Arts209 Redwood ShoresParkwayRedwood City, CA 94065 Copyright © 2001, EA.com. All rights reserved. No part of this documentation may be reproduced in any

form or by any means or used to make any derivative work (such as translation, transformation, oradaptation) without written permission from EA.com.

EA.com reserves the right to revise this documentation and to make changes in content from time totime without obligation on the part of EA.com to provide notification of such revision or change.

EA.com provides this documentation without warranty, term, or condition of any kind, either implied orexpressed, including, but not limited to, the implied warranties, terms or conditions of merchantability,satisfactory quality, and fitness for a particular purpose. EA.com may make improvements or changes inthe product(s) and/or the program(s) described in this documentation at any time.

Unless otherwise indicated, EA.com registered trademarks are registered in the United States and mayor may not be registered in other countries.

EA.com, the EA.com logo, is a registered trademark of EA.com. EA GAMES, the EA GAMES logo, andEA SPORTS, the EA SPORTS logo, are trademarks or registered trademarks of Electronic Arts in theU.S. and/or other countries.

Adobe and Acrobat Reader are registered trademarks of Adobe Systems, Inc.

Windows is a registered trademark and Windows NT is a trademark of Microsoft Corporation in the U.S.and other countries.

Other brand and product names may be registered trademarks or trademarks of their respective holders.

Table of Contents

Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiShortened Heading Examples Including Method Declaration Descriptionvii

Instance Methods Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . viiSample of Instance Method Description . . . . . . . . . . . . . . . . . . viii

Generalized Syntax Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiGame Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Auth/Auth/Ident APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Auth/Auth/Ident APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Authorize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2AuthLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Product Ticketing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Authenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3AuthUserStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Platform Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Feature List and Version History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Implementation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7External Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7EA.com Service IDs and GameTech Product IDs . . . . . . . . . . . . . . . . . . 7Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Ticket Expiration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Use Cases & Flow Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Client/Server Non-Browser Launched Game. . . . . . . . . . . . . . . . . . . . . 11Product Ticketing: Massively Multiplayer Login, Shard Selection . . . . . 12Product Ticketing: Launch to Web Site During Game Play . . . . . . . . . . 14Client/Server Browser-Launched Game . . . . . . . . . . . . . . . . . . . . . . . . 15Client-Only Browser Launched Game . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Auth/Auth/Ident SDK v3.2a iii EA.com Confidential, Level: Family

Table of Contents

Client-Only Browser Launched Game with Score Reporting . . . . . . . . 17Browser Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Entitlement Reverification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Integration Instructions "Cookbook" with API Reference . . . . . . . . . . . 21Authorize API Integration Instructions. . . . . . . . . . . . . . . . . . . . . . . . . . 21Authorize API for C++ Implementation (Win32) . . . . . . . . . . . . . . . . . . 21

Header Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 21Authorize API Integration Steps for C++ Implementation (Win32)22Authorize API Reference for C++ Implementation (Win32) . . . 24Interface IAuthorizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Interface IEAUserContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Interface INVPair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Authorize API C++ Code Sample. . . . . . . . . . . . . . . . . . . . . . . 31

Authorize API for Java Implementation. . . . . . . . . . . . . . . . . . . . . . . . . 34Integration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Authorize API Reference for Java Implementation . . . . . . . . . 36Interface EAUserContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Class Authorize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Class AuthorizeException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Authorize API Java Code Example . . . . . . . . . . . . . . . . . . . . . 41

Authorize API C++ Implementation (Solaris, Linux) . . . . . . . . . . . . . . . 42Header Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 42Integration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Authorize API Reference for C++ Implementation (Solaris, Linux)45Interface INVPairList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Authorize API C++ Code Sample. . . . . . . . . . . . . . . . . . . . . . . 48

AuthLogin API Integration Instructions . . . . . . . . . . . . . . . . . . . . . . . . . 49AuthLogin API for C++ Implementation (Win32) . . . . . . . . . . . . . . . . . . 49

Header Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 49Integration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49AuthLogin API Reference for C++ Implementation (Win32). . . 52Class Authorizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Class EAAuthLoginResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55AuthLogin API C++ Code Example . . . . . . . . . . . . . . . . . . . . . 58

Product Ticketing API Integration Instructions . . . . . . . . . . . . . . . . . . . 62Product Ticketing API for Java Implementation . . . . . . . . . . . . . . . . . . 62

Integration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Product Ticketing API Reference for Java Implemenation. . . . 63Class AuthorizeException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Class ProductTicket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Product Ticketing API Code Example for Java Implementation 66

Product Ticketing API C++ Implementation (Solaris, Linux) . . . . . . . . . 67Header Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 67Integration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Auth/Auth/Ident SDK v3.2a iv EA.com Confidential, Level: Family

Table of Contents

Product Ticketing API Reference for C++ Implementation (Solaris,Linux) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

AuthUserStatus API Integration Instructions . . . . . . . . . . . . . . . . . . . . . 70AuthUserStatus API Java Implementation . . . . . . . . . . . . . . . . . . . . . . . 70

Integration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70AuthUserStatus API Reference for Java Implementation . . . . . 71Class AAIUserStatusClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Class AAIUserStatusNotFoundException. . . . . . . . . . . . . . . . . 74Class AAIUserStatusSystemException. . . . . . . . . . . . . . . . . . . 74AuthUserStatus API Java Code Example. . . . . . . . . . . . . . . . . 75

Auth/Auth/Ident SDK v3.2a v EA.com Confidential, Level: Family

Table of Contents

Auth/Auth/Ident SDK v3.2a vi EA.com Confidential, Level: Family

Documentation Conventions

Shortened headings are used for constructors, methods, functions, and destructors.

Shortened Heading Examples Including Method DeclarationDescription

Instance Methods Summary

Return Type Method Short Description

EAUserContext authorize(String, String, String)This method contacts theAuthorization service and presents auser context ID.

Auth/Auth/Ident SDK v3.2a vii EA.com Confidential, Level: Family


Sample of Instance Method Description

This method contacts the Authorization service and presents a user context ID.

Syntax: EAUserContext authorize(String contextId, String serviceId, String url)

Method Return Type: EAUserContextA class containing methods to retrieve the contents of the user context (see Class EAUserContext).

Argument: String contextId

A Java String containing an opaque handle to this user’s current game session.

Argument: String serviceId

A Java String containing the EA.com identifier of the game.

Argument: String url

A Java String containing the URL of the Authorization and Authentication service.

Note: The AuthorizeException class is thrown if the service cannot be contacted for some reason. SeeAuthorizeException below.

authorize(String, String, String)

Auth/Auth/Ident SDK v3.2a viii EA.com Confidential, Level: Family


Unless otherwise noted in the text, this guide follows these documentation conventions:

Generalized Syntax Expressions

This general style of writing may be used in our documentation:

Convention Description

Courier New fontHighlights code, program messages and filenames.

Italic typeUsed selectively for emphasis and also as aplaceholder described below.

Bold text Used selectively for emphasis.

< placeholder > or placeholder

The reader is to replace the < placeholder > withan appropriate value. Angle brackets are usedwhen italic type cannot be added to thedocumentation.

copy < filename > a:

[ < item > ]The item in the square brackets is optional.

print [ < filename > ]

< first > | < second > | < third >

The reader must choose one from the listseparated by "pipes".

us_location = true | false

< first > . . .

You must provide at least one of the items beforethe "...".

copy < filename > ...

[ < first > . . . ]The optional item can be repeated.

copy [ file < filename > ... ]

Auth/Auth/Ident SDK v3.2a ix EA.com Confidential, Level: Family


Auth/Auth/Ident SDK v3.2a x EA.com Confidential, Level: Family

History

Game Capability

Feature ReleaseNumber Delivery Date

Authorize (Java, Win32, Solaris); supports Java andC++

1.0 Q2 2000

Authenticate (Java) 1.0 Q2 2000

AuthLogin (Win32); supports Shockwave 1.5 Q3 2000

AuthUserStatus (Java); added standalone gameclient login and game server authorization

2.0 Q4 2000

Authorize (Linux) 2.0 Q2 2001

Product Ticketing (Java, Linux, Solaris) 3.0 Q3 2001

Unix server components wrapped in kCOM 3.0 Q3 2001

AuthLogin returns error strings; interface revision 3.0 Q3 2001

AuthLogin wrapped in kCOM 3.0 Q3 2001

AuthUserStatus able to generate metrics ID 3.1 Q3 2001

Proxy support (IE, MS Windows configured only) 3.2 Q3 2001

Greater error granularity Q4 2001

AuthLogin error help Web pages Q4 2001

"Save my password" for AuthLogin Q4 2001

Auth/Auth/Ident SDK v3.2a xi EA.com Confidential, Level: Family

History

Documentation

Version Author Reviewed By ReleaseDate

v2.0 S. Keller, K. Holman,D. Nair

S. Keller 2/22/01

v3.0 S. Davuluri, D. Nair S. Davuluri 5/18/01

v3.1 S. Davuluri, K.Holman, D. Nair

S. Davuluri 5/30/01

v3.2 S. Davuluri, K.Holman, D. Nair

S. Davuluri 9/13/01

v3.2a L. Smith, K. Holman L. Smith 10/01

Auth/Auth/Ident SDK v3.2a xii EA.com Confidential, Level: Family

Frequently Asked Questions

What platforms does Auth/Auth/Ident support?

• Windows 95, 98 and NT for C and C++ development environments

• Java for cross-platform development environments

• Solaris and Linux for game server libraries

What are the system requirements for Auth/Auth/Ident?

Refer to the EA.com Platform Requirements document.

What do I receive with the Auth/Auth/Ident SDK?

You will receive a Programming Guide that includes C, C++ and Java APIs with usageexamples.

What tools do I need to develop with the Auth/Auth/Ident SDK?

Microsoft Visual C++ Ver. 6.0 and Microsoft Service Pack 3.

What components do I need that are not included in the SDK?

You must have WinINet.

What about security?

• The browser-game component uses an opaque, randomly generated "ticket" so thatno user specific information is available.

• The standalone login component uses HTTP (Hyper Text Transfer Protocol) tocommunicate with EA.com so that all data is encrypted.

• Communication from game servers to EA.com is on a secure back channel that is notvisible to the public Internet.

Auth/Auth/Ident SDK v3.2a xiii EA.com Confidential, Level: Family

Frequently Asked Questions

Auth/Auth/Ident SDK v3.2a xiv EA.com Confidential, Level: Family

1Auth/Auth/Ident APIs

Overview

The Auth/Auth/Ident (AAI) system provides authentication, authorization, and identification servicesto game systems, or to other EA.com subsystems.

• Authentication – Ensures the person using the service is the account holder

• Authorization – Ensures the account being used is entitled to use the service

• Identity – Provides information on the account holder

The Auth/Auth/Ident system is a ticketing mechanism. The EA.com Auth/Auth/Ident coreinfrastructure creates a ticket in a database and issues a context ID, a long GUID-like string that is thereference to the ticket (think of it as the ticket number or ticket handle). The context ID is given tothe Web browser or game client. This context ID can then be passed around in various ways beforethe context ID is ultimately submitted back again to the EA.com Auth/Auth/Ident infrastructure forverification (also known as ticket cracking). The context ID is then matched to a ticket andinformation regarding the identity of the EA.com member is then returned.

The Auth/Auth/Ident system is very flexible and can be used in a variety of ways

• Supports either Client/Server games or Client-Only games

• Support for Java (applets) or Win32 (Active-X) browser games

• Support for Win32 non-browser game clients

• Supports transition from EA.com to other Web sites

• Supports transition from game server to Web sites

Please refer to the Auth/Auth/Ident flow diagrams and implementation instructions for furtherclarification of how a game is integrated with Auth/Auth/Ident <link within doc to the first diagram>.

Auth/Auth/Ident SDK v3.2a 1 EA.com Confidential, Level: Family

Auth/Auth/Ident APIs


Authorize

Authorize is the API for cracking or verifying a context ID and receiving identity information.

When a context ID is verified, the ticket is marked as used in the EA.com ticket database. The contextID cannot be reused for authorization purposes. Each ticket is valid for one game play.

However, the ticket can be reused with the Authenticate API to later again retrieve the identityinformation; see the Authenticate API for details.

The Authorize API also provides a portion of the integration with the EA.com Metrics system byindicating the beginning of game play when the ticket is cracked. See the Metrics documentation formore detail <link to BoS>.

AuthLogin

The AuthLogin API combines authentication (checking the member name and password) withchecking that the player is entitled to play a particular game (verifying subscription status and thecorrect entry of registration codes). The API is intended to operate on the player’s machine.

The member name and password are transmitted securely via SSL (Secure Socket Layer) (same asHTTPS).

For game clients that are not launched from the EA.com registration page, this is the front door to thegame. As such, error conditions must be handled carefully to help the player troubleshoot login orentitlement problems.

AuthLogin also provides a portion of the integration with the EA.com Metrics system by indicatingthe beginning of a game session when the ticket is issued (for Web based games, this is handled bythe Web game launch mechanism). See the Metrics documentation for more detail <link to BoS>.

Product Ticketing

The Product Ticketing API (also known as the Productized Ticketing API) provides the ability for atrusted server component to obtain additional tickets once game play has begun. This allows the gameto use Auth/Auth/Ident to pass the player from one portion of the game infrastructure to another.Additionally, these tickets can be used to pass the player to the EA.com Web site (or Satellite WebSite) and have the player automatically logged into the Web site.

For example, the Product Ticketing API can pass a player from a shard selector to a game shard, fromthe game shard back to the shard selector, or from a game server to a Web site.



These additional product tickets can also contain game specific data. This data can be used in avariety of ways. For example, the ticket for handing a player from a shard selector to a game shardcan contain the name of the persona that the player selected for game play.

In either use of the Product Ticketing API (game component transfers or Web site automatic login),a product ticket will not be issued if the original ticket for game play has expired or if it has not beenused with the Authorization API. Additionally, the first ticket must be valid at the time the productticket is used with the Authorize API.

This security requirement ensures that at some time prior to obtaining or using the product ticket, theplayer has supplied their EA.com member name and password to the EA.com infrastructure. Thisprotects the EA.com services and other games against backdoor access from a single game title.

Note: Ticket expiration can result in errors in the creation and use of product tickets - the game codemust expect these error and re-authenticate the player in these circumstances (likely using theAuthLogin API).

Authenticate

The Authenticate API has a somewhat misleading name. It does not perform any authentication task;it only verifies that at some point in the past, the player was authenticated. The Authenticate API willcheck that a ticket exists, has already been used, and will return the identity data.

The intended use is for systems such as score reporting. It is used to ensure the player reporting thescore actually played the game and provide the score reporting system with the player identity for thescore record.

Note: Ticket expiration may limit the usefulness of the Authenticate API. See the Ticket Expirationsection for details <link within doc>.

AuthUserStatus

The AuthUserStatus API provides a simple facility for a trusted game server to verify that the playeris still entitled to play the game. It was intended for games that may allow extended play sessions toperiodically check that the player has not cancelled their subscription. Please refer to the GlobalPetitioning System documentation for information regarding how account suspension iscommunicated to the game <link to BoS>.



Platform Availability

Following is a table outlining the various Auth/Auth/Ident components, the platforms for which theyare available, and the compilers supported.

API Function Win32 Java Linux Solaris

Authorize Validates a ticket andreturns user identity data

MicrosoftVisual Studio6.0

JDK 1.2.2 GCC 2.9.3 SunWrokShop5.0

AuthLogin Verifies password andentitlement status andcreates a ticket

MicrosoftVisual Studio6.0

Notcurrentlyavailable

Linuxgameclients notsupported

Solarisgameclients notsupported

ProductTicketing

Creates additional ticketsfrom an existing ticket;allows for custom ticketdata

Not availablefor securityreasons

JDK 1.2.2 GCC 2.9.3 SunWorkShop5.0

Authenticate Revalidates a ticket andreturns user identity data

Not currentlyavailable

JDK 1.2.2 GCC 2.9.3 SunWorkShop5.0

AuthUserStatus

Verifies entitlement statuswithout a ticket

Not availablefor securityreasons

JDK 1.2.2 Notcurrentlyavailable

Notcurrentlyavailable



Feature List and Version History

Feature ReleaseNumber Delivery Date

Authorize (Java, Win32, Solaris) 1.0 Q2 2000

Authenticate (Java) 1.0 Q2 2000

AuthLogin (Win32) 1.5 Q3 2000

AuthUserStatus (Java) 2.0 Q4 2000

Authorize (Linux) 2.0 Q2 2001

Product Ticketing (Java, Linux, Solaris) 3.0 Q3 2001

Unix server components wrapped in kCOM 3.0 Q3 2001

AuthLogin returns error strings; interface revision 3.0 Q3 2001

AuthLogin wrapped in kCOM 3.0 Q3 2001

AuthUserStatus able to generate metrics ID 3.1 Q3 2001

Proxy support (IE, MS Windows configured only) 3.2 Q3 2001

Greater error granularity Q4 2001

AuthLogin error help Web pages Q4 2001

"Save my password" for AuthLogin Q4 2001




2Implementation Details

External Dependencies

The Windows Auth/Auth/Ident client APIs, Authorize and AuthLogin, require Wininet.dll, theInternet Explorer network communication component.

All non-Java components, client and server, require kCOM, a lightweight platform-independentcomponent technology, similar to Microsoft COM.

EA.com Service IDs and GameTech Product IDs

Auth/Auth/Ident depends on the EA.com concepts of Service IDs and Gametech Product IDs forconfigurations regarding entitlement and security.

Each Service has:

• Specific Entitlement Requirements

Does using this service require that the member pay for an EA.com subscription? Does usingthis service require that the member enter a product registration code (CD key)? Can AOLmembers who have not registered for EA.com accounts use this service?

• Distinct Optional Ticket Data Configuration

The inclusion of additional customer profile information must be configured on a per-Servicebasis. See the integration instructions for Authorize <link within doc> or contact your TD orGIE for details.

• Game Launch URL

For Web-based games, the ticket is generated through the use of a generic servlet (see the WebDevelopment Platform documentation for information on Web game launch <LINK>). Eachservice has a configuration that specifies the Web page to which the customer should bedirected to after the ticket is generated, typically the page hosting the game object.

• Discrete Metrics

In order to subdivide the game metrics using the EA.com Metrics system, separate ServiceIDs must be used.


Implementation Details

• Ticket Lifespan

The time before the ticket expires is also specified for each Service ID. See the section onticket expiration for more detail <LINK>.

When a ticket is requested, the Service for which it is to be used must be specified. The entitlementrequirements are checked before the ticket is issued. When a context ID is submitted, a Product IDmust be specified. The EA.com Auth/Auth/Ident infrastructure looks up the ticket, and checkswhether the Service ID used in the creation of the ticket is associated with the Product ID specifiedin the use of the Authorize API. Authorization is successful only if an association is found.

There can be more than one Service ID associated with a single Product ID. This allows for membersmeeting different entitlement requirements to connect to common game infrastructure. For example,a demo player can connect the same game server as a subscriber player. The game server can use acommon Product ID for Authorization as long as both the Service ID configured for the demo versionof the game and the Service ID configured for the subscription version of the game both map to thatcommon Product ID.

Security

The key security assumption of Auth/Auth/Ident is similar to any ticketing system. The ticket isissued to a particular party. It is assumed that the party using a ticket is the same as the party to whomthe ticket was issued.

Several security measures have been included in the design of Auth/Auth/Ident:

• The context ID is a randomly generated string used only as a reference to a database record.No information is contained within the context ID.

• The context ID is a 17 digit hexadecimal string. This prevents brute force guessing of contextIDs.

• The matching of a Product ID used to authorize the ticket with the Service ID (used togenerate the ticket) ensures that the ticket cannot be used for a purpose other than for whichit was intended. See the Service ID and Product ID section <LINK> for more detail.

• A context ID can be used for authorization only once.

• Although it is possible to modify the Product ID submitted for authorization by a Client-Onlygame, it is no more difficult to modify the game client to bypass the authorization entirely.

• For Web games, the context ID is typically transmitted as part of the page request sequence.Although this subjects the Auth/Auth/Ident system to a “man in the middle” style of attack,the attacker must not only intercept the context ID, but also use it before the legitimate player.It is possible to transmit the context ID using SSL; this would introduce security dialogs inthe Web browser concerning the transition to and from a secure Web page.

• For non-Web games, the transmission of the member screen name and password, as well asthe returning context ID, uses SSL. It is up to the game to transmit the context ID from thegame client to game server in such a manner as to not compromise the game security.



• The SSL key length is identical to that available for the Internet Explorer browser on the clientmachine, up to 128 bit keys.

Ticket Expiration

When a ticket is created, the Service configuration dictates the lifespan of the ticket. This lifespan ismarked from the time of ticket creation. For EA.com infrastructure performance as well as securityreasons, it is desirable to have this value as low as reasonable for the specific game title.

For games that use the ticket only for game authorization, the ticket timeout should be greater thanthe time expected for game install, patch update, launch, communication initiation and whatever elsehappens between the time the ticket is issued and the time it is authorized.

For games that use the ticket for score reporting purposes (or other use of the Game Telemetry System<LINK>), the ticket timeout must be greater than the expected game session duration. If the ticket isexpired when the score is reported, the game results will be discarded.

For games that expect to use the Product Ticketing API, the ticket timeout must be long enough toensure that product tickets can be issued. See the Product Ticketing API section for more detail <linkwithin doc>.




3Use Cases & Flow Diagrams

Client/Server Non-Browser Launched Game

Refer to Client/Server Massively Multiplayer Game Archetype Variation <LINK>

Game Examples: Majestic, Motor City Online, Earth & Beyond, The Sims Online

• The game client prompts the player for EA.com member name and password.

• The game client uses the AuthLogin API to submit the member name and password, alongwith the service ID designating the specific game.

• If the player is correctly authenticated and properly entitled to play the specified game, a ticketis created in the ticket database and the corresponding context ID is returned.

• If the player is not correctly authenticated or properly entitled, an error is returned fromAuthLogin. An error message to be presented to the player is available as is a URL to whichthe player should be directed for further information or for problem resolution.

• The game client should then transmit the context ID to the game server as part of the initialcommunication.

• The game server calls the Authorize API to submit the context ID for verification.


Use Cases & Flow Diagrams

The EA.com Auth/Auth/Ident service uses the context ID to retrieve the ticket from the ticketdatabase, returning the player identity information to the game server along with theverification of proper authentication and authorization.

Product Ticketing: Massively Multiplayer Login, ShardSelection

Refer to Client/Server Massively Multiplayer Game Archetype Variation <LINK>

Games Examples: The Sims Online


• The game client calls the AuthLogin API to submit the member name and password, alongwith the service ID designating the specific game.



• The game client should then transmit the context ID to the game shard selector as part of theinitial communication.

• The shard selector uses the Authorize API to submit the context ID for verification.

• The EA.com Auth/Auth/Ident service uses the context ID to retrieve the ticket from the ticketdatabase, returning the player identity information to the game server along with theverification of proper authentication and authorization.

TicketDatabase

Pass context ID

Submit context ID

Gam e Client

Gam e ServerEA.Com

AAI ServicesAuthorize

APIAuthorization

& Identity

AuthLoginAPI

Submit member name& password

Receive context ID



• Using the identity returned from Auth/Auth/Ident, player-specific information (availablepersonas) as wells as general information (shard status) is presented to the player. Then,player would then decide to connect to a specific shard.

• The shard selector calls the Product Ticketing API to request a context ID valid for game playat the shard. The shard selector may also submit custom game specific data to be inserted intothe ticket.

• The resulting context ID is returned to the game client, which is then directed to connect tothe game shard server.

• The game client should then transmit the context ID to the game shard server.


• The EA.com Auth/Auth/Ident service uses the context ID to retrieve the ticket from the ticketdatabase, returning the player identity information to the game server, verification of properauthentication and authorization, as well as the custom game specific data submitted by theshard selector.

(3 ) P asscon text ID "A "

(4 ) S ubm itcon text ID "A "

G am eC lien t

S hardS e lec to r

G am eS erver

A uthorizeA P I

T icketD atabase

(1) S ubm it m em ber nam e& password(2 ) R ece ive

con text ID "A "

(7 ) R ece ive context ID "B "

(8 ) P asscontext ID "B "

A u thLoginA P I

A uthorizeA P I

(11 ) A uthen tica tion ,Iden tity , custom data

(9) P asscontext ID "B "

P roductizedT icketing A P I

E A E nterp rise

(10 ) S ubm itcontext ID "B "

(6 ) requestcon text ID "B "

w ith custom da ta

(5 ) A uthen tica tion& Iden tity



Product Ticketing: Launch to Web Site During Game Play

Game Examples: None currently, Majestic planned


• The game client calls the AuthLogin API to submit the member name and password, alongwith the service ID designating the specific game.






• During game play, the user may wish to visit the Web site. The game server calls the ProductTicketing API to request a context ID valid for site authentication.

• The resulting context ID is returned to the game client, which is then directed to launch theWeb browser with a specific URL format.

• The game client should then transmit the context ID to the game shard server.


• The EA.com Auth/Auth/Ident service uses the context ID to retrieve the ticket from the ticketdatabase, returning the player identity information to the game server, verification of proper



authentication and authorization, as well as the custom game specific data submitted by theshard selector.

Client/Server Browser-Launched Game

Refer to Client/Server General Web Client Game Archetype <link>

Game Examples: No Current Examples

• The player logs into the EA.com Web site using their member name and password.

• The Web developer uses the EA.com Web Development Platform API to produce the Webpage that embeds the game client. The Web page will contain a context ID as part of theHTML returned to the browser. Please refer to the game launch portion of the WebDevelopment Platform API documentation for more detail on how the context ID is generated<link to BoS>.

• The context ID is passed to the game client as a parameter for the embedded object.



(3 ) P a s sc o n te x t ID "A "

(4 ) S u b m itc o n te x t ID "A "

G a m eC lie n t

G a m eS e rve r

A u th o rizeA P I

T ic k e tD a ta b a s e

(1 ) S u b m it m e m b e r n a m e& p a s s w o rd(2 ) R e c e iv e

c o n te x t ID "A "

(7 ) R e c e iv e c o n te x t ID "B "

(8 ) P a s sc o n te x t ID "B "

A u th L o g inA P I

E A .c o mW e b S ite

(9 ) P a s sc o n te x t ID

"B " o n U R L

P ro d u c tize dT ic k e t in g A P I

E A E n te rp ris e

(6 ) re q u e s tc o n te x t ID "B "

w ith c u s to m d a ta

(5 ) A u th e n tic a t io n& Id e n ti ty

W e bB ro w s e r

(1 1 ) V a lid a te t ic k e t

(1 0 ) P a s sc o n te x t ID "B "

o n U R L




Client-Only Browser Launched Game

Refer to Client-Only Browser (Hi-Q Single Player) Game Archetype <LINK>

Game Examples: Bunny Luv


• The Web developer uses the EA.com Web Development Platform API to produce the Webpage that embeds the game client. The Web page will contain a context ID as part of theHTML returned to the browser. Please refer to the game launch portion of the WebDevelopment Platform API documentation for more detail on how the context ID is generated<link to BoS>.

• The context ID is passed to the game client as a parameter for the embedded object.

• The game client then calls the Authorize API to submit the context ID for verification.


TicketDatabase

Pass context ID

Submit context ID

G am e Client

Gam e ServerEA.Com

AAI ServicesAuthorize

APIAuthorization

& Identity

Receivecontext ID

W eb BrowserPass context ID



Note: Auth/Auth/Ident used in this method ensures only a limit amount of security. It is possible tohack the game client to bypass Auth/Auth/Ident. It is not possible to completely prevent the gameclient from operating independent of the EA.com service.

Client-Only Browser Launched Game with Score Reporting

Refer to Client-Only Browser (Hi-Q Single Player) Game Archetype <LINK>

Game Examples: GTS (EA.com infrastructure) <LINK>

• Authorization for game play operates identical to other browser-launched, client-only games.

• When game play is complete, the score information can be transmitted along with the contextID.

• The score reporting system calls the Authenticate API with the same context ID that was usedfor game play authorization.

• The EA.com Auth/Auth/Ident service uses context ID to retrieve the ticket again, verifies thatthe ticket has already been used for game play authorization, and returns the player identityinformation.

TicketDatabase

Submit context ID

Gam e Client

EA.ComAAI Services

AuthorizeAPI

Authorization& Identity

Receivecontext ID

W eb BrowserPass context ID



• The score reporting system verifies that the data returned matches the player and game forwhich a score was reported.

Browser Redirection

Examples: Pogo.com, EA.com Message Boards


• The Web developer uses the EA.com Web Development Platform API to generate a browserredirection. The redirection URL will contain the context ID as either a HTTP GET or POSTparameter. Please refer to the game launch portion of the Web Development Platform APIdocumentation for more detail on how the context ID is generated <link to BoS>.

• The external Web server calls the Authorize API to submit the context ID for verification.

T icke tD atabase

Subm it con text ID

G am e C lient

E A .C omAA I S ervices

AuthorizeA P I

A uthoriza tion& Iden tity

R ece ivecon text ID

W eb B rowserPass context ID

A uthenticateAP I

S core R eportingS ystem

S ubm it scorewith con text ID

Submit con text ID

R eva lida tion & Identity



• The EA.com Auth/Auth/Ident service uses the context ID to retrieve the ticket from the ticketdatabase, returning the member identity information to the Web server along with theverification of proper authentication and authorization.

Entitlement Reverification

Examples: Majestic, Harry Potter Online (Designed, Not Yet Implemented)

• The member does not have to be currently playing the game.

• The game server uses the AuthUserStatus API to request entitlement status for a specifiedEA.com member name and specified EA.com service ID.

• The EA.com Auth/Auth/Ident system will check whether the member is currently entitled toplay the game, including verifying subscription is in good standing.

• It is possible to request an EA.com Metrics ID as well. This would theoretically allow for theAuthUserStatus API to be used for game sessions that do not require EA.com authentication.Please consult the GIE or TD before using any implementation of this nature.

T ic k e tD a t a b a s e

S u b m i t c o n t e x t I D" E x t e r n a l"

W e b S e r v e rE A . C o m

A A I S e r v ic e sA u t h o r iz e

A P IA u t h o r i z a t i o n

& I d e n t i t y

W e b B r o w s e r

R e d i r e c t w i t hc o n t e x t I D

U s e rD a ta b a s e

S u b m itm e m b e r n a m e

G a m e C lie n t

G a m e S e rv e rE A .C o m

A A I S e rv ic e sA u th U s e rS ta tu s

A P IE n t i t le m e n t

s ta tu s




4Integration Instructions "Cookbook" withAPI Reference

Authorize API Integration Instructions

Authorize API for C++ Implementation (Win32)

The C/C++ Authorize client API can be used by ActiveX or Netscape plug-in games, and isimplemented as a kCOM shared component that can be called from both C++ and straight C. The C/C++ implementation of the Authorization service for browser-based game clients consists of thefollowing interfaces:

• IAuthorizer

• IEAUserContext

• INVPair

In order to use the C++ Authorize client, you must first install the latest kCOM <LINK> package inyour development environment.

Header Files and Directories

This file contains the following files:

• authclient.h

• authauth.lib

• authauth.dll

It also contains a directory called kCOM/includes, which contains header files required byauthclient.h.


Integration Instructions "Cookbook" with API Reference

Authorize API Integration Steps for C++ Implementation (Win32)

1. Include the header file authclient.h in your source. Ensure that the directory containing thekCOM headers is also included in your project.

2. Link your executable against authauth.lib (or call LoadLibraryEx() to explicitly loadthe.dll file). When you install your program, you must install authauth.dll and ensure yourprogram can find it at run time.

3. Your code needs to call AuthorizationLib_GetAuthorizer() to obtain an Authorizerobject (technically returning a pointer to an object that implements the IAuthorizer interface).

4. Next, call the Authorize() method of that object. That method requires three pieces ofinformation.

5. The result code should be checked to ensure that Authorize was able to contact the EA.com Auth/Auth/Ident service and able to construct an object to return.

Context ID (or ticket) The context ID is typically passed into the browser game through a <param> or similartag on the Web page. The context ID is generated as part of the Web game launchmechanism. The context ID is currently a string less than 32 characters in length.

Product ID This string should not be configured on the Web page, but instead should be hard-codedinto the game. The product ID is assigned by the GIE or TD and is part of the security thatprevents the use of tickets for a purpose other than for which they were created. Theproduct ID string has no fixed maximum length, but is generally less than 32 characters inlength.

Service URL This is the URL of the servlet used for authorization. Because each EA.com QAenvironment has a different URL, this URL is typically passed into the browser gamethrough a <param> or similar tag. The Web page derives this value from anenvironment setting in the Web application infrastructure. The URL is currently less than32 characters in length.



6. In a normal operation, the call to Authorize returns an object implementing the IEAUserContextinterface. This object contains an indication of whether the player is authorized for game play;this indication is obtained by calling IEAUserContext.IsValid(). Other methods provideaccess to identity information about the customer, but the results of these methods are undefinedif IEAUserContext.IsValid() returns false. The most commonly used ticket data fieldsare as follows:

Unless otherwise specified, to retrieve the value, first use GetContextData() to retrieve thename-value-pair list of the ticket data elements and then use GetNamedValue() to retrieve thespecific value.

Additional member profile information may be present if it the Auth/Auth/Ident infrastructure isconfigured to include this information for the specific title. Contact your TD or GIE if you requireprofile information for game play. For the use of profile information for demographic profiling orother reporting purposes, alternative methods are available. Contact your TD or GIE for how tocorrelate game data against EA.com profile data.

UserAlias Screen formatted screen name of the member. Use GetUserAlias() to retrieve the UserAlias. The maximum length is currently 16 characters.

UserName Normalized screen name (all lower case, no spaces). The maximum length is currently 16characters.

UserID EA.com member ID. We recommend that this value be used as the primary key for all datastorage associated with the player. This allows for the possibility of screen name changes in thefuture.

For AOL guest players, the value of UserID is null.

MetricsID Used if the game server implements the EA.com Metrics API. If the game uses this API, theMetrics ID must be stored during the game play session as it will be used to report thetermination of game play. The metrics ID is currently less than 45 characters.

ProductID Game specific information associated with a product ticket. See the implementation on ProductTicketing and associated flow diagrams for more information on product tickets <link>. UseGetProductData() to retrieve the product data.

ServiceID Contains the EA.com Service ID <LINK up in doc> used to create the ticket.

GTProductID EA.com Product ID used to Authorize the context ID.



Authorize API Reference for C++ Implementation (Win32)

The C/C++ client API is used by ActiveX or Netscape plug-in games, and is implemented as a kCOMshared component that can be called from both C++ and straight C.

The following interfaces are documented below:

• IAuthorizer

• IEAUserContext

• INVPair

Interface IAuthorizer

This is the interface used by clients to verify if a user context is valid.

Instance Method Summary


IEAUserContext* Authorize(const char *,const char *, const char *,kcom::Result&)

Contacts the Authorization service andpresents a context ID.



Instance Method

Contacts the Authorization service and presents a context ID.

Syntax: IEAUserContext* Authorize(const char * inContextId, const char *inServiceId, const char *inUrl, kcom::Result& outResult) throw()

Method Return Type: IEAUserContext*A pointer to the interface containing methods to retrieve the contents of the user context (see interfaceIEAUserContext). This interface pointer remains valid until the user calls Release() for it. EA.comrecommends that you assign it to a kcom::auto_interface<IEAUserContext> so Release() will becalled for you automatically.

Argument: const char *inContextId

A pointer to a string containing an opaque handle to this user’s current game session.

Argument: const char *inServiceId

A pointer to a string containing the EA.com identifier of the game.

Argument: const char *inUrl

A pointer to a string containing the URL of the Authorization and Authentication service.

Argument: kcom::Result& outResult

This variable is a reference to a variable of type kcom::Result which will receive the result code.

Exceptions: None

Note: outResult& is a reference to a kcom::Result code, which can be converted to an exception by callingkcom::ThrowIfFailed(), or evaluated by calling kcom::ResultSucceeded().

Authorize(const char *, const char *,const char *, kcom::Result&)



Interface IEAUserContext

This interface provides access to the contents of the user context retrieved by a call toIAuthorizer::Authorize().


Instance Methods

Retrieves any application-specific information from the context. This information is in the form of a sequence ofread-only name-value pairs, accessible through the INVPair interface.

Syntax: kcom::ISequence<const INVPair>* GetContextData() const throw()

Method Return Type: kcom::ISequence<const INVPair>*

The name-value pairs as entries in a kcom::ISequence of INVPair objects.

Exceptions: None

Note: If your game requires a database containing user information, the value for the key "UserAlias" can be retrievedfrom the hashtable to use as your database index. UserAlias is a version of the user’s screen name that is single-case andhas no spaces. It is also used as the index in EA.com’s database.


kcom::ISequence<const INVPair>* GetContextData() Retrieves any application-specificinformation from the context.

const char* GetProductData() Retrieves any application-specificinformation data stored in aproduct ticket.

const char* GetServiceID() Retrieves the product ID thatcorresponds to this context.

const char* GetReasonCode() Retrieves a text description of thereason the user context is invalid.

const char* GetUserAlias() Retrieves the user’s screen name.

bool8 IsValid() Finds out if a context is valid.

GetContextData()



This method retrieves any application-specific data stored in a product ticket. This is only used by back-end servers.

Syntax: const char* GetProductData() const throw()

Method Return Type: const char*

Exceptions: None

Retrieves the product ID that corresponds to this context.

Syntax: const char* GetServiceID() const throw()


A string containing the service ID. This pointer is only valid until Release() is called on the EAUserContextobject. You must copy it to local storage if you want to keep it available. EA.com recommends constructing astd::string with it as follows:

std::string aliasString(context->GetServiceID())

Exceptions: None

Retrieves a text description of the reason the user context is invalid.

Syntax: const char* GetReasonCode() const throw()


A string containing the reason code. It will be an empty string ("") if the user context is valid. This pointer is onlyvalid until Release() is called on the EAUserContext object, so you must copy it to local storage if you wantto keep it available. EA.com recommends constructing a std::string with it as follows:

std::string myReason(context->GetReasonCode())

Exceptions: None

GetProductData()

GetServiceID()

GetReasonCode()



Retrieves the user’s screen name.

Syntax: const char* GetUserAlias() const throw()


A string containing the user’s screen name. This pointer is only valid until Release() is called on theEAUserContext object, so you must copy it to local storage if you want to keep it available. EA.com recommendsconstructing a std::string with it as follows:

std::string aliasString(context->GetUserAlias())

Exceptions: None

Retrieves the user’s screen name.

Syntax: bool8 IsValid() const throw()

Method Return Type: bool8Returns true if the contents of the context are valid.

Exceptions: None

Note: The return values of all other accessor methods, except GetReasonCode(), are invalid if this method returnsfalse.

GetUserAlias()

IsValid()



Interface INVPair

This interface encapsulates the concept of a name-value pair of strings.


Instance Methods

Retrieves the name of this name-value pair.

Syntax: const char* GetContextData() throw()


A pointer to a string containing the name. It should be copied into local storage if the application wants to keep thisdata for longer than the lifetime of the NVPair object, until Release() is called for that object.

Exceptions: None

Retrieves the value part of this name-value pair.

Syntax: const char* GetValue() throw()


A pointer to a string containing the value. It should be copied into local storage if the application wants to keep thisdata for longer than the lifetime of the NVPair object, until Release() is called for that object.

Exceptions: None


const char* GetName() Retrieves the name of this name-value pair.

const char* GetValue() Retrieves the value part of this name-value pair.

void SetName(char*) Sets the name part of the name-value pair.

void SetValue(char*) Set the value part of this name-value pair.

GetName()

GetValue()



Sets the name of this name-value pair.

Syntax: void SetName(const char* name) throw()

Method Return Type: void

Argument: const char* name

The name of this name-value pair that might be truncated if the string exceeds the internal limit.

Exceptions: None

Sets the value of this name-value pair.

Syntax: void SetValue(const char* value) throw()


Argument: const char* value

The value of this name-value pair that might be truncated if the string exceeds the internal limit.

Exceptions: None

SetName(const char*)

SetValue(const char*)



Authorize API C++ Code Sample

The following code sample, for browser-based games, is from the testAuthorization.cppfile in the kcomClient1.5.zip file.

// ============================================================// authorizationTest.cpp// Test code used to ensure that authorization client component// works correctly.// 3/25/00 Ed Zavada// ============================================================

#include "authclient.h"#include <iostream>

using namespace kcom;using namespace ea::authorization;using namespace std;

#ifdef K_MSVC#pragma warning(disable:4800 4290)// don't want MSVC's performance warning#endif

void TestAuthorize(char* contextid, char *serviceid, char *authSrvUrl)throw (std::exception);

int main(int argc, char *argv[]){

// holders for datachar contextid[64];char serviceid[64];char authSrvUrl[128];

if (argc > 3)strcpy(authSrvUrl, argv[3]);

elsestrcpy(authSrvUrl, "http://gmwestdev1.ea.com:8081/authorize");

if (argc > 2)strcpy(serviceid, argv[2]);

elsestrcpy(serviceid, "GT_TEST_GAME");

if (argc > 1)strcpy(contextid, argv[1]);

elsestrcpy(contextid, "12047:42");

try



{TestAuthorize(contextid, serviceid, authSrvUrl);

}catch (std::exception e){

cerr << "exception occurred: " << e.what();}

return 0;}

void TestAuthorize(char* contextid, char *serviceid, char *authSrvUrl)throw (std::exception)

{// -------------------------------------------------------------// C++ test

cout << "Beginning Test\n\n";kcom::auto_interface<IAuthorizer> auth(AuthorizationLib_GetAuthorizer());

if (!auth.valid()){

cerr << "Failed to initialize AuthorizationLib!\n";return;

}

// check the server to see if the context is authorizedkcom::Result kr;kcom::auto_interface<IEAUserContext> ctx( auth->Authorize(contextid,

serviceid, authSrvUrl, kr) );

if (kcom::ResultFailed(kr)){

cerr << "Failed to Authorize EAUserContext. Result code = " << kr << "\n";}else if (ctx->IsValid()){

cout << "user = " << ctx->GetUserAlias() << " ";cout << "service = " << ctx->GetServiceID() << "\n";kcom::auto_interface<INVPairList> seq(ctx->GetContextData());ea::int32 idx = seq->Reset();const INVPair* p;

while ((p = seq->Next(idx)) != 0){

auto_interface<const INVPair> pair(p);cout << pair->GetName() << " = " << pair->GetValue() << "\n";

}const char* s = seq->GetNamedValue("name");

if (s)



{cout << "Looked up value for [name] is ["<<s<<"]\n";

}}else{ // !ctx->IsValid()

cerr << "Invalid User Context: " << ctx->GetReasonCode() << "\n";}// end C++ Test// -------------------------------------------------------------

}



Authorize API for Java Implementation

The Java Authorize client API can be used by applet or client/server games with Java servercomponents. The Java implementation of the Authorization consists of the following client classes inthe specified package. The specified package also contains helper classes, but no direct use of theseis necessary.

Package: com.ea.enterprise.authauth.javaclient

• Interface EAUserContext

• Class Authorize

• Class AuthorizeException

Note: The game code should never access any of the supporting classes directly, only through theinterfaces. This allows EA.com to modify the implementation of the client classes without affectingthe game code.

Integration Steps

1. For applets, ensure that the Auth/Auth/Ident class files are included in the game JAR. For Javagame servers, ensure that the class files or JAR are in the classpath.

2. Call the Authorize.authorize() method. That method requires three pieces ofinformation.

Context ID (or ticket) For applets, the context ID is typically passed into the game through a <param> or similartag on the Web page. The context ID is generated as part of the Web game launchmechanism. For Java server games, the context ID will be passed from the game client to thegame server using a game-specific method. Note that for an applet client game with a Javagame server, the context ID may be passed to the applet as a <param> and then transmitter tothe game server. The context ID is a Java String.

Product ID For browser applet games, this string should not be configured on the Web page, but insteadshould be hard-coded into the game. For Java game servers, the product ID can be set in aconfiguration file or other convenient manner. The product ID is assigned by the GIE or TDand is part of the security that prevents the use of tickets for a purpose other than for whichthey were created.

Service URL This is the URL of the servlet used for authorization. Because each EA.com QA environmenthas a different URL it needs to be set per environment. For browser applet games, this URLis typically passed into the browser game through a <param> or similar tag. The Web pagederives this value from an environment setting in the Web application infrastructure. ForJava game servers, the service URL can be set in a configuration file or other convenientmanner.



3. Catch the AuthorizeException in the event that Authorize was able to contact the EA.com Auth/Auth/Ident service and able to construct an EAUserContext object.

4. In normal operation, the call to Authorize.authorize returns an object implementing theEAUserContext interface. This object contains an indication of whether the player is authorizedfor game play; this indication is obtained by calling EAUserContext.isValid(). Othermethods provide access to identity information about the customer, but the results of thesemethods are undefined if EAUserContext.isValid() returns false. The most commonlyused ticket data fields are as follows:

Unless otherwise specified, to retrieve the value, use getContextData() to retrieve the hashtableof the ticket data elements.


UserAlias Screen formatted screen name of the member. Use getUserAlias() toretrieve the User Alias.

UserName Normalized screen name (all lower case, no spaces).

UserID EA.com member ID. We recommend that this value be used as the primary keyfor all data storage associated with the player. This allows for the possibility ofscreen name changes in the future.


MetricsID Used if the game server implements the EA.com Metrics API. If the game usesthis API, the Metrics ID must be stored during the game play session, as it will beused to report the termination of game play.

ProductData Game specific information associated with a product ticket. See implementationon Product Ticketing and associated flow diagrams for more information onproduct tickets <link to doc>. Use getProductData() to retrieve theproduct data.

ServiceID Contains the EA.com Service ID used to create the ticket.

GTProductID Contains the EA.com Product ID used to Authorize the context ID.



Authorize API Reference for Java Implementation

Interface EAUserContext


This class provides access to the contents of the user context retrieved by a call toAuthorize.authorize().


Instance Methods

This method retrieves any application-specific information from the context. This information is in the form of name-value pairs as Strings.

Syntax: Hashtable getContextData()

Method Return Type: HashtableContains the name-value pairs.

Exceptions: None

Note: If an unformatted version of the user’s screen name is needed for a database index, obtain this information fromthe hashtable using the key "UserAlias".


Hashtable getContextData() Retrieves any application-specific information from thecontext.

String getProductData() Retrieves any application-specific data stored in a productticket.

String getReasonCode() Retrieves a text description of the reason why the user contextis invalid.

String getServiceID() Retrieves the service ID that corresponds to this context.

String getUserAlias() Retrieves the user’s screen name.

boolean isValid() Returns true if the contents of the context are valid.

getContextData()



This method retrieves any application-specific data stored in a product ticket. This is only used by back-end servers.

Syntax: String getProductData()

Method Return Type: String

Exceptions: None

Retrieves a text description of the reason why the user context is invalid.

Syntax: String getReasonCode()

Method Return Type: StringContains the reason code. This String is empty if the EAUserContext is valid.

Exceptions: None

Retrieves the service ID that corresponds to this context.

Syntax: String getServiceID()

Method Return Type: StringContains the service ID.

Exceptions: None

getProductData()

getReasonCode()

getServiceID()



Retrieves the user’s screen name. It is the Formatted User Alias, with capitalization and spacing specified by the user.

Syntax: String getUserAlias()

Method Return Type: StringContains the screen name.

Exceptions: None

Checks if user context is valid.

Syntax: boolean isValid()

Method Return Type: booleanIndicates true if the contents of the context are valid.

Note: The return values of all other accessor methods, except getReasonCode(), are invalid if this method returnsfalse.

getUserAlias()

isValid()



Class Authorize


This is used by clients to verify whether a user context is valid.


Instance Methods

This method contacts the Authorization service and presents a user context ID.

Syntax: EAUserContext authorize(String contextId, String serviceId,String productID, String version, String url)

Method Return Type: EAUserContextA class containing methods to retrieve the contents of the user context (see Class EAUserContext).

Argument: String contextId

A Java String containing an opaque handle to this user’s current game session.

Argument: String serviceId

A Java String containing the EA.com identifier of the game.

Argument: String productId

A Java String containing the product ID of the game.

Argument: String version

A Java String containing the version of the authorize API.


A Java String containing the URL of the Authorization and Authentication service.

Note: The AuthorizeException class is thrown if the service cannot be contacted for some reason. SeeAuthorizeException below.


EAUserContextauthorize(String, String, String,

String, String)This method contacts the Authorization

service and presents a user contextID.

authorize(String, String, String, String, String)



Class AuthorizeException


Syntax: public class AuthorizeException extends Exception

This class encapsulates errors in communication and invalid requests to the Authentication service.

Constructor Summary

Constructor

Syntax: AuthorizeException(String msg)

A String containing a description of the reason for the exception.

Constructor Short Description

AuthorizeException(String) Contains a description of the reason for the exception.



Authorize API Java Code Example

<need to get it>



Authorize API C++ Implementation (Solaris, Linux)

The C/C++ Authorize client API can be used by native-code game servers on Linux and Solaris andis implemented as a kCOM shared component that can be called from both C++ and straight C. TheC/C++ implementation of the Authorization service for native-code game servers consists of thefollowing interfaces:

• IAuthorizer

• IEAUserContext

• INVPair

• INVPairList

Also included is an implementation of the kCOM IComponentFactory interface that provides amechanism for creating Authorizer objects.


The package contains the following files:

• IAuthorizer.h

• IEAUserContext.h

• INVPair.h

• INVPairList.h

• libauthauth.so

Note: In order to use the C++ Authorize client, you must first install the latest kCOM <LINK>package in your development environment.

Integration Steps

1. Include the header file IAuthorizer.h in your source. Ensure that the directory containingthe kCOM headers is also included in your project.

2. Ensure that the location of libauthauth.so is included in the LD_LIBRARY_PATH of theexecution environment for the game server.

3. Your code needs to call AuthorizationLib_GetComponentFactory() to obtain anAuthorizer factory object.

4. Then call IComponentFactory->MakeObject, specifying that an object with theIAuthorizer interface is to be created.

(IAuthorizer*)factory->MakeObject(IAuthorizer::InterfaceID, kr);



5. Next, call the Authorize() method of the Authorizer object. That method requires threepieces of information.

6. The result code should be checked to ensure that Authorize was able to contact the EA.com Auth/Auth/Ident service and able to construct an object to return.

Context ID (or ticket) The context ID is typically passed into the browser game through a <param> orsimilar tag on the Web page. The context ID is generated as part of the Web gamelaunch mechanism. For a non-Web game, the context ID will be generated throughthe use of the AuthLogin API. The context ID is currently a string less than 32characters in length.

Product ID The product ID can be set in a configuration file or other convenient manner. Theproduct ID is assigned by the GIE or TD and is part of the security that prevents theuse of tickets for a purpose other than for which they were created.

Service URL This is the URL of the servlet used for authorization. Because each EA.com QAenvironment has a different URL, the service URL should be set in a configurationfile or other convenient manner.



7. In normal operation, the call to Authorize returns an object implementing the IEAUserContextinterface. This object contains an indication of whether the player is authorized for game play;this indication is obtained by calling IEAUserContext.IsValid(). Other methods provideaccess to identity information about the customer, but the results of these methods are undefinedif IEAUserContext.IsValid() returns false. The most commonly used ticket data fieldsare as follows:

Unless otherwise specified, to retrieve the value, first use GetContextData() to retrieve thename-value-pair list of the ticket data elements and then use GetNamedValue() to retrieve thespecific value.


8. Release the Authorizer object.

UserAlias Screen formatted screen name of the member. Use GetUserAlias() to retrieve theUser Alias. Max length is currently 16 characters.

UserName Normalized screen name (all lower case, no spaces). Max length is currently 16characters.

UserID UserID is the EA.com member ID. We recommend that this value be used as the primarykey for all data storage associated with the player. This allows for the possibility ofscreen name changes in the future.


MetricsID Used if the game server implements the EA.com Metrics API. If the game uses this API,the Metrics ID must be stored during the game play session as it will be used to report thetermination of game play. The Metrics ID is currently less than 45 characters.

ProductData Game specific information associated with a productized ticket. See implementation onProduct Ticketing and associated flow diagrams for more information on product tickets.Use GetProductData() to retrieve the product data.

ServiceID Contains the EA.com Service ID used to create the ticket.

GTProductID Contains the EA.com Product ID used to Authorize the context ID.



Authorize API Reference for C++ Implementation (Solaris, Linux)

The C/C++ client API is used by ActiveX or Netscape plug-in games, and is implemented as a kCOMshared component that can be called from both C++ and straight C.

Use the links below to view the Interface details previously documented in this chapter.

• IAuthorizer <link within doc>

• IEAUserContext <link within doc>

• INVPair <link within doc>

• INVPairList

Interface INVPairList

<Lars to check this as in the previous doc this was Class NVPairList. chg’d the sentence below - seered>

INVPairList contains a list of name-value pairs. Also, this class contains methods that provide accessto objects of type INVPair.



const char * getNamedValue(char *) A call to retrieve a string containing the value of aparticular name-value pair.

bool isEmpty() A call to determine whether the list is empty.

NVPair * next() Acts as an iterator through the list of name-value pairs.

NVPair * prev() Acts as an iterator through the list of name-value pairs.

void reset() A call to set the internal list pointer to the beginning ofthe list.

size_t size() A call to determine the number of elements in the list.



Instance Methods

A call to retrieve a string containing the value of a particular name-value pair.

Syntax: const char *getNamedValue(const char *key)

Method Return Type: const char *

Returns a string containing the value of a particular name-value of a particular name-value pair. This is NULL if thename represented by the key argument is not in the list.

Argument: const char *key

A string containing the name to look up.

Exceptions: None

A call to determine whether the list is empty.

Syntax: bool isEmpty()

Method Return Type: boolReturns a Boolean value indicating whether the list is empty.

Exceptions: None

Acts as an iterator through the list of name-value pairs.

Syntax: NVPair *next()

Method Return Type: NVPair *

Returns A pointer to an NVPair object containing a single name-value pair. This pointer will be NULL if the listinternal pointer is past the end or beginning of the list, respectively.

Exceptions: None

getNamedValue(char *)

isEmpty()

next()



Acts as an iterator through the list of name-value pairs.

Syntax: NVPair *prev()

Method Return Type: NVPair *

Returns A pointer to an NVPair object containing a single name-value pair. This pointer will be NULL if the listinternal pointer is past the end or beginning of the list, respectively.

Exceptions: None

Sets the internal list pointer to the beginning of the list.

Syntax: void reset()


Exceptions: None

A call to determine the number of elements in the list..

Syntax: size_t size()

Method Return Type: size_tContains the number of elements in the list.

Exceptions: None

prev()

reset()

size()



Authorize API C++ Code Sample

Use the link below to view the code sample previously documented in this chapter.

<link within doc>



AuthLogin API Integration Instructions

AuthLogin API for C++ Implementation (Win32)

The C/C++ AuthLogin client API can be used game clients that are not launched from a Web pageand require authentication independent from the EA.com Web site. The API is implemented as akCOM shared component that can be called from both C++ and straight C. The C/C++implementation of the AuthLogin service for stand-alone and non-browser game clients consists ofthe following interfaces:

• IAuthorize

• IEAAuthLoginResult



This file contains the following files:

• authlogin.h

• authlogin.lib

• authlogin.dll

Integration Steps

1. Include the header file authlogin.h in your source. Ensure that the directory containing thekCOM headers is also included in your project.

2. Link your executable against authlogin.lib (or call LoadLibraryEx() to explicitlyload the.dll file). When you install your program, you must install authlogin.dll and ensureyour program can find it at run time.

3. Your code needs to call AuthorizationLib_GetAuthorize() to obtain an Authorizeobject (technically returning a pointer to an object that implements the IAuthorize interface).

4. Prompt the player for member name and password.



5. Next, call the GetTicketSync() method of that object. That method requires five pieces ofinformation, with two more items being optional but recommended.

6. Verify that GetTicketSync returned a valid pointer.

7. In normal operation, the call to GetTicketSync returns an object implementing theIEAAuthLoginResult interface. This object contains an indication of whether the player isauthenticated and authorized for game play; this indication is obtained by callingIEAAuthLoginResult.IsValid(). If the object is valid, the methodIEAAuthLoginResult.GetContextID() can be used to retrieve the context ID. The game clientshould then transmit the context ID to the game server as part of the initial communication.

Member Screen Name Submit the EA.com member screen name entered by the player.

Password Submit the EA.com password entered by the player.

Service ID The EA.com service ID for which the product ticket should be issued. Thisshould be configured on the client in a manner conveniently updated ifrequired by future game revisions.

Service Hostname (URL base) This is the hostname for the AuthLogin service. Because each EA.com QAenvironment has a different hostname, this should be configured on the clientin a manner conveniently changed if the client is to be able to support testingagainst multiple environments with minimal changes.

Service Servlet Name (URL path) This is the name of the servlet used for AuthLogin. This should be configuredon the client in a manner conveniently updated if required by future gamerevisions.



8. If the object is not valid, the object will contain information indicating the failure condition. Thefollowing method can be used to retrieve further information:

9. Release the Authorize object.

Error Text Use the method IEAAuthLoginResult.GetReasonText() to retrieve anerror text string that indicates the cause of the failure. This string shouldbe presented to the player to help them diagnose the failure. The errortext is configured as part of the EA.com service and is global to allgames. However, the text is localized into the language correspondingto the URL used to contact the AuthLogin service in the GetTicketSyncinvocation; www.ea.com returns English error strings, de.ea.comreturns German error strings, etc. Note that the strings are currently inthe process of being translated. Consult your GIE for the status for aspecific language. The strings are currently limited to 255 characters.

Error URL Use the method IEAAuthLoginResult.GetReasonURL() to retrieve theURL to an informative Web page to help the player diagnose their ownproblem without contacting customer support. Currently these URLsare not supported as the pages are still under design. Contact your GIEfor the current status of these pages.

Error Code Use the method IEAAuthLoginResult.GetReasonCode() to retrieve theerror code string, as detailed in the AuthLogin Error Codes document<LINK>. These codes can be used to present custom error messages orWeb page links, if desired.



AuthLogin API Reference for C++ Implementation (Win32)

Used for standalone games (e.g., PC-CD games), the C++ API is a little different than using a C++class. You must first obtain a pointer to an Authorizer class, then use that class to access the service.You cannot directly instantiate an Authorizer object, nor can you delete it. The API provides a factorymethod for creating an instance of the class, and the class itself has a Release method which is usedinstead of deleting the object.

• Authorizer

• EAAuthLoginResult

Class Authorizer

This is the class used by clients to verify if a user context is valid.

Syntax: class Authorizer : public kcom::simple_object<IAuthorize>



IEAAuthLoginResult* GetTicketSync(const char *,const char *, const char *)throw()

Synchronous call to retrieve aticket.

Note: This method isdepreciated.

IEAAuthLoginResult* GetTicketSync(const char *,const char *, const char *,const char *, const char *)throw()

Synchronous call to retrieve aticket.

Note: This is the updatedmethod.



Instance Methods

Synchronous call to retrieve a ticket; synchronous ticket retrieval.

Syntax: IEAAuthLoginResult* GetTicketSync(const char *inUsername,const char *inPassword, const char *inServiceId) throw()

Method Return Type: IEAAuthLoginResult*Returns a pointer to an object of type IEAAuthLoginResult.

Argument: const char *inUsername

The user’s login name.

Argument: const char *inPassword

The user’s password.


A string containing the Service Id for the game.

Exceptions: Throws a <enter the type of exception> exception when <descr>.

Note: This method is deprecated. Do not use it. This method reads the AuthLoginBaseService andthe AuthLoginServerURL from the registry.

GetTicketSync(const char *, const char *, const char *)



Synchronous call to retrieve a ticket; synchronous ticket retrieval.

Syntax: IEAAuthLoginResult* GetTicketSync(const char *inUsername,const char *inPassword, const char *inServiceId,const char *inAuthLoginBaseService, const char *inAuthLoginServer)throw()

Method Return Type: IEAAuthLoginResult *

Returns a pointer to an object of type IEAAuthLoginResult.

Argument: const char *inUsername


Argument: const char *inPassword

The user’s password.


A string containing the Service Id for the game.

Argument: const char *inAuthLoginServer

A string containing the URL for the login server. Example www.ea.com.

Argument: const char *inAuthLoginBaseService

A string containing the name of the login servlet. Example AuthLogin.


Note: This method will not read the AuthLoginBaseService and the AuthLoginServerURL from theregistry. It will use the values passed in.

GetTicketSync(const char *, const char *, const char *, const char *, const char *)



Class EAAuthLoginResult

This class provides access to the results of the call to GetTicketSync.


Instance Methods

Call to retrieve a ticket.

Syntax: const char* GetContextID() const thow()




const char* GetContextID() const throw() Call to retrieve a ticket.

const char* GetReasonCode() const throw() Call to retrieve an error code.

const char* GetReasonText() const throw() Call to retrieve the reason text.

const char* GetReasonURL() const throw() Call to retrtrieve the reason URL.

bool8 IsValid() const throw() Returns true if the call to retrieve aticket succeeds.

GetContextID() const throw()



Call to retrieve an error code.

Syntax: const char* GetReasonCode() const throw()



Call to retrieve the reason text.

Syntax: const char* GetReasonText() const throw()



Returns true if the call to retrieve a ticket succeeds.

Syntax: const char* GetReasonURL() const throw()



Note: The page that this URL points to has not been implemented. Please do not use this at this time. <check this out>

GetReasonCode() const throw()

GetReasonText() const throw()

GetReasonURL() const throw()



Call to retrtrieve the reason URL.

Syntax: boolean IsValid() const throw()

Method Return Type: boolean<descr>


IsValid() const throw()



AuthLogin API C++ Code Example

The following is an example using the C++ interface for embedded standalone games.

/////////////////////////////////////

// testauth.cpp

//

// Test the AuthLogin in-game client

// using C++

//

// Author: Sailesh Davuluri

// History:

// 02-May-2001Created

// -------------------------------------

// Copyright (c) 2001 EA.com

// -------------------------------------

#include <windows.h>

#include <iostream>

#include <authlogin.h>

#include "testauth.h"

int main(int argc, char *argv[])

{

int ret = 0;

TestAuth *auth = new TestAuth();

(void) strcpy(auth->username, "saileshd");

(void) strcpy(auth->password, "welcome");

(void) strcpy(auth->serviceID, "2138");

ret = auth->test();

delete auth;

return ret;

}

// -----------------------------------



// constructor

TestAuth::TestAuth()

{

strcpy(contextID, "");

strcpy(password, "");

strcpy(username, "");

strcpy(serviceID, "");

}

int TestAuth::test()

{

// create an authorizer

ea::authauth::IAuthorize *iauth = ea::authauth::AuthLoginLib_GetAuthorize();

if (iauth == NULL)

return ea::authauth::IAUTHORIZE_INVALID;

// a return code

ea::int32 r = ea::authauth::IAUTHORIZE_SUCCESS;

// -------------------------------------------------------------

// synchronous method

// -------------------------------------------------------------

// kcom::auto_interface<IEAAuthLoginResult>

ea::authauth::IEAAuthLoginResult *result = ( iauth->GetTicketSync(username,password, serviceID, contextID) );

if (result->IsValid())

{

std::cout << "GetTicketSync() success: Ticket: " << result->GetContextID()<< std::endl;

}

else

{



std::cout << "GetTicketSync() failure: ReasonCode: " << result->GetReasonCode() << " ReasonText: " << result->GetReasonText() << " ReasonURL: "<< result->GetReasonURL() << std::endl;

}

ea::authauth::IEAAuthLoginResult *result2 = ( iauth->GetTicketSync(username,password, serviceID) );

if (result2->IsValid())

{

std::cout << "GetTicketSync() success: Ticket: " << result2->GetContextID()<< std::endl;

}

else

{

std::cout << "GetTicketSync() failure: ReasonCode: " << result2->GetReasonCode() << " ReasonText: " << result2->GetReasonText() << " ReasonURL: "<< result2->GetReasonURL() << std::endl;

}

ea::authauth::IEAAuthLoginResult *result3 = ( iauth->GetTicketSync(username,password, serviceID, "AuthLogin", "ea1.str.ea.com") );

if (result3->IsValid())

{

std::cout << "GetTicketSync() success: Ticket: " << result3->GetContextID()<< std::endl;

}

else

{

std::cout << "GetTicketSync() failure: ReasonCode: " << result3->GetReasonCode() << " ReasonText: " << result3->GetReasonText() << " ReasonURL: "<< result3->GetReasonURL() << std::endl;

}

// -------------------------------------------------------------

// release the interface

// -------------------------------------------------------------



iauth->Release();

return r;

}



Product Ticketing API Integration Instructions

Product Ticketing API for Java Implementation

The Java Product Ticketing client API should be used by Java game servers. The Java implementationof Product Ticketing consists of the following client classes in the specified package. The specifiedpackage also contains helper classes, but no direct use of these is necessary.


• Class ProductTicket

• Class AuthorizeException

Integration Steps

1. Ensure that the class files or JAR are in the classpath.

2. Call the ProductTicket.getProductTicket() method. That method requires five pieces ofinformation.

3. Catch the AuthorizeException in the event thatgetProductTicket()was able to contact theEA.com Auth/Auth/Ident service or that a ticket could not be created.

4. In normal operation, the call to getProductTicket() returns a Java String that contains thecontext ID of the product Ticket. This context ID should be passed via the client to the correctcomponent that will authorize the player.

Member Screen Name Submit the EA.com member screen name for which the ticket is to be created.

Context ID of the original ticket Product tickets require that the context ID of the ticket used for Authorizationmust be submitted in order to receive the product ticket. If this ticket isexpired or otherwise invalid, the product ticket will not be created. It is theresponsibility of the game developer to store the context ID between the timeof initial Authorization and the call to getProductTicket(). Thecontext ID is a Java String.

Service ID EA.com service ID for which the product ticket should be issued. This maybe identical to the service ID for the original ticket, but not necessarily.

Product ID This is the product specific information that should be included in the ticketdata. This is a Java string. The limit is currently 2000 characters, but thismust include the standard ticket data. A safe limit may only be 1500characters.

Service URL This is the URL of the Product Ticket servlet. Because each EA.com QAenvironment has a different URL it needs to be set per environment andshould be set in a configuration file or other convenient manner.



Product Ticketing API Reference for Java Implemenation

Class AuthorizeException


Syntax: public class AuthorizeException extends Exception

This class encapsulates errors in communication and invalid requests to the Authentication service.

Constructor Summary

Constructor

Syntax: AuthorizeException(String msg)



AuthorizeException(String) Contains a description of the reason for the exception.



Class ProductTicket


This class is a helper class to create an EA.com Product ticket. It is a static class requiring noinstantiation.

Syntax: public class ProductTicket

Class Method Summary


static String

getProductTicket(String,String, String,String, String,String) throwsAuthorizeException

Retrieves the contents of a ticket from anAuthorization service.



Class Method

This method

Syntax: public static String getProductTicket(String username, String contextID,String productID, String serviceID, String productData,String ProductTicketServeletURL) throws AuthorizeException

Method Return Type: static String

Returns the ticketID and the ticket location.

Argument: String username

A String representing the EA.com username for which the ticket is to be created.

Argument: String contextID

A String representing the ticket ID and location of the ticket to crack.

Argument: String productID

A String representing the product ID used to create the ticket.

Argument: String serviceID

A String representing the service ID used to create the ticket.

Argument: String productData

The optional game specific data stored in the ticket.

Argument: String ProductTicketServletURL

The URL String of the ProductTicket servlet.

Exceptions: If the input parameters are invalid, or if there is a communication error with the Authorization service,this method throws an AuthorizeException.

getProductTicket(String, String, String, String, String, String) throwsAuthorizeException



Product Ticketing API Code Example for Java Implementation



Product Ticketing API C++ Implementation (Solaris, Linux)

The C++ Product Ticket client API is intended for use by native-code game servers on Linux andSolaris and is implemented as a kCOM shared component. The C/C++ implementation of the ProductTicket service for native-code game servers is included in the package with Authorize and consistsof the following interfaces:

• IAuthorizer

• IEAUserContext

• INVPair

• INVPairList

Also included is an implementation of the kCOM IComponentFactory interface that provides amechanism for creating Authorizer objects.


The package contains the following files:

• IAuthorizer.h

• IEAUserContext.h

• INVPair.h

• INVPairList.h

• libauthauth.so


Integration Steps

1. Include the header file IAuthorizer.h in your source. Ensure that the directory containingthe kCOM headers is also included in your project.

2. Ensure that the location of libauthauth.so is included in the LD_LIBRARY_PATH of theexecution environment for the game server.

3. Your code needs to call AuthorizationLib_GetComponentFactory() to obtain anAuthorizer factory object.

4. Then, call IComponentFactory->MakeObject, specifying that an object with theIAuthorizer interface is to be created.

(IAuthorizer*)factory->MakeObject(IAuthorizer::InterfaceID, kr);



5. Next, call the getProductTicket() method of the Authorizer object. That method requires fivepieces of information..

6. The result code should be checked to ensure that getProductTicket was able to contact theEA.com Auth/Auth/Ident service and received a ticket.

7. In normal operation, the call to getProductTicket() returns a string that contains the context ID ofthe product Ticket. This context ID should be passed via the client to be sent to the other gamecomponent that will authorize the player or to be used in the construction of a URL with whichthe client would launch a browser.

8. 8. Release the Authorizer object.

UserName Submit the EA.com username for which the ticket is to be created.

Context ID of the original ticket Product tickets require that the context ID of the ticket used for Authorizationmust be submitted in order to receive the product ticket. If this ticket isexpired or otherwise invalid, the product ticket will not be created. It is theresponsibility of the game developer to store the context ID between the timeof initial Authorization and the call to getProductTicket(). Thecontext ID is a Java String.


Product ID This is the product specific information that should be included in the ticketdata. This is a Java string. The limit is currently 2000 characters, but thismust include the standard ticket data. A safe limit may only be 1500characters.

Service URL This is the URL of the Product Ticket servlet. Because each EA.com QAenvironment has a different URL it needs to be set per environment andshould be set in a configuration file or other convenient manner.



Product Ticketing API Reference for C++ Implementation (Solaris, Linux)

Use the links below to view the Interface details previously documented in this chapter.

• IAuthorizer <link within doc>

• IEAUserContext <link within doc>

• INVPair <link within doc>

• INVPairList <link within doc>

Code Example

Use the link below to view the code sample previously documented in this chapter.

<link within doc>



AuthUserStatus API Integration Instructions

AuthUserStatus API Java Implementation

The Java AuthUserStatus client API should be used by Java game servers. The Java implementationof AuthUserStatus consists of the following client classes in the specified package. The specifiedpackage also contains helper classes, but no direct use of these is necessary.


• Class AAIUserStatusClient

• Class AAIUserStatusNotFoundException

• Class AAIUserStatusSystemException

Integration Steps

1. Ensure that the class files or JAR are in the classpath.

2. Create a new AAIUserStatusClient object.

3. Call the method AAIUserStatusClient.setServletUrl() to set the URL of theAuthUserStatus servlet. Because each EA.com QA environment has a different URL it needs tobe set per environment and should be set in a configuration file or other convenient manner.

4. Call the method AAIUserStatusClient.getUserStatus() to verify that the specifieduser is entitled to the specified service. That method requires two pieces of information..

5. In normal operation, the getUserStatus() method returns a Boolean indicating whether the user isentitled to the service.

6. Catch the AAIUserStatusNotFoundException andAAIUserStatusSystemException in the event that a failure occured.

Member Screen Name Submit the EA.com member screen name for which the ticket is to be created.




AuthUserStatus API Reference for Java Implementation• Class AAIUserStatusClient

• Class AAIUserStatusNotFoundException

• Class AAIUserStatusSystemException

Class AAIUserStatusClient


This class is a helper class to create an EA.com Product ticket. It is a static class requiring noinstantiation.

Note: The methods for this class are presented in order of use rather than alphabetically.

Syntax: public class AAIUserStatusClient


ReturnType Method Short Description

void setServletURL(String) Sets the URL of the user status servlet.

boolean

getUserStatus(String,String) throwsAAIUserStatusNotFoundException,AAIUserStatusSystemException

Retrieves the status of a particular user.

boolean

getUserStatus(String, String,String) throwsAAIUserStatusNotFoundException,AAIUserStatusSystemException

Retrieves the status of a particular user.

Note: Consult the TD or GIE before usingthis method

String getMetricID()

<descr>

Note: Consult the TD or GIE before usingthis method.



Instance Methods

This method sets the URL of the user status servlet.

Syntax: public void setServletUrl(String url)

Method Return Type: static String

Returns the ticketID and the ticket location.


The base servlet URL. <br> e.g., "http://www.backend.ea.com/AAIUserStatus".

This method retrieves the status of a particular user.

Syntax: public boolean getUserStatus(String name, String serviceid) throwsAAIUserStatusNotFoundException, AAIUserStatusSystemException

Method Return Type: booleanIndicates whether the user is subscribed to the service. Returns True if subscribed, False if not subscribed.

Argument: String name


Argument: String serviceid

A String Service ID of the service for which subscription information is desired.

Exceptions: Throws AIUserStatusNotFoundException if <descr>.

Exceptions: Throws AAIUserStatusSystemException if <descr>.

setServletURL(String)

getUserStatus(String, String) throws AAIUserStatusNotFoundException,AAIUserStatusSystemException



This method retrieves the status of a particular user.

Note: Consult the TD or GIE before using this version of the method.

Syntax: public boolean getUserStatus(String name, String serviceid,String metricInfo) throws AAIUserStatusNotFoundException,AAIUserStatusSystemException

Method Return Type: booleanIndicates whether the user is subscribed to the service. Returns True if subscribed, False if not subscribed.

Argument: String name


Argument: String serviceid

A String Service ID of the service for which subscription information is desired.

Argument: String metricInfo

<descr>

Exceptions: Throws AIUserStatusNotFoundException if a user is not found.

Exceptions: Throws AAIUserStatusSystemException if there is a system error.

<descr>

Note: Consult the TD or GIE before using this method.

Syntax: public String getMetricID()

Method Return Type: String<descr>

getUserStatus(String, String, String) throws AAIUserStatusNotFoundException,AAIUserStatusSystemException

getMetricID()



Class AAIUserStatusNotFoundException

This class is an Exception that signifies if a user is not found.


Syntax: public class AAIUserStatusNotFoundException extends java.lang.Exception

Constructor Summary

Constructor

Syntax: public AAIUserStatusNotFoundException(String msg)


Class AAIUserStatusSystemException

This class is an Exception that signifies a system error.


Syntax: public class AAIUserStatusSystemException extends java.lang.Exception

Constructor Summary

Constructor

Syntax: public AAIUserStatusSystemException(String msg)



AAIUserStatusNotFoundExeption(String) An exception that signifies if a user is not found.


AAIUserStatusSystemExeption(String) An exception that signifies a system error.


Documents

Auth Auth Ident v3.2