Second Life Login API Strawman

Template:Needs Translation/de Template:Needs Translation/es Template:Needs Translation/el Template:Needs Translation/fr Template:Needs Translation/he Template:Needs Translation/it Template:Needs Translation/ko Template:Needs Translation/nl Template:Needs Translation/hu Template:Needs Translation/no Template:Needs Translation/da Template:Needs Translation/sv Template:Needs Translation/tr Template:Needs Translation/pl Template:Needs Translation/pt Template:Needs Translation/ru Template:Needs Translation/th Template:Needs Translation/uk Template:Needs Translation/zh-Hans Template:Needs Translation/zh-Hant

This page is now deprecated. It is retained in the wiki for transparency and for the discussion. The login protocol is now a part of the SL Grid Open Grid Protocol doc and should be referenced there

Second Life Login API Strawman

This is a work in progress. Also see a similar Strawman by AWG: AWG_flows_login Innitial meeting with AWG to request feedback on protocol: Feedback Chat-log, 19 Feb 2008

Introduction

This page attempts to merge Authentication_Flow with Current_login_protocols and adds additional protocol changes to fit with Agent_Domain#How_login_works. The goal is to expose a protocol allowing login to a separate region domain while making incremental, small changes to the current protocol.

Summary

1. *Viewer sends credentials to the Login Service #Login_Web_Service
2. Login Service authenticates and sets up and queries for presence:
   • Queries the agent data from the Agent Store.
   • Finds an agent host, POST's agent presence checking for already online
   • grants seed capability, which lives on an agent host
3. *Viewer requests capabilities needed for login via received seed capability. #Seed_Capability
4. *(future) Viewer Polls Agent Host for messages via long-poll #poll_for_messages_Capability
5. *(future) Viewer can send instant messages before being in world. #instant_message_Capability
6. *Viewer invokes legacy_login capability #legacy_login_Capability
   • Initialization data returned by login
   • Sets up agent presence
   • Forwards location request to region domain, finding a region to rez the avatar
   • Establishes session with region host, which gives back a (region domain) seed capability to the client
7. *Viewer invokes region seed capability

Definitions

Seed Capability

The current Login Seed Capability is a Capability associated with the simulator you are logging into. It should not be confused with the #Agent_Seed_Capability proposed for the new protocols.

Agent Seed Capability

This is a newly introduced capability associated with the agent host as part of the agent domain. This is different from the previously mentioned seed-capability, which associates with the sim host as part of the region domain.

Conventions

On this page the following conventions are used:

"--" followed by text, indicates a comment until the end of line, ala the C++ "//" style comments.

< represents a value which can be substituted by an appropriate string described inside >

< represents a list of choices | separated by a vertical bar >

"..." ellipses indicates an unknown list of similar values follow

"<int>" represents an integer value

"<uuid>" represents a UUID value, e.g., 'c5853f4c-855f-4013-ce92-aabc59f1b9d8'

The remaining syntax follows (very roughly) that of Python data structures:

"in quotes is a literal string"

{ <represents a map or dictionary of one or more key>:<value pairs> } -- separated by commas

[ represents an array, of elements, separated by commas ]

'represents a string that must be quoted, but how will be implementation specific' for example in LSL "" denotes a string and " will be used in place of the single quote (').

+ means to concatenate the two parts, though how will be implementation specific, for example + can be used to concatenate strings.

Login Web Service

Client --> public Login Server: "Here is my credential, and optional agent identity desired" Second Life Login Server: https://login.agni.secondlife.com/app/login/

The login will be done using standard http/1.1 POST and the default format for all parameters in POST and RESPONSE will likely be "content-type" = "application/xml" and the actual xml format will be the text serialization of Linden Lab's XML-LLSD format. Future formats will be negotiated using standard http/1.1 Content Negotiation.

Required Parameters

   { 'credential': { 'type': 'agent',
                     'first_name': <first>,
                     'last_name': <last>,
                     'password': '$1$' + <passwd_md5> } }

OR (future)

   { 'credential': { 'type': 'account',
                     'account_name': <IBM>,
                     'password': '$1$' + <passwd_md5> } }

OR (future)

   { 'credential': { 'type': 'openid',
                     'url': <URL> } }

OR (future)

   { 'credential': { 'type': 'agent',
                     'first_name': <first>,
                     'last_name': <last>}}

which will need to a challenge from the auth system.

Optional Parameters

Optionally, specify which account you want this credential to log you into

   { 'credential': { 'type': 'agent',
                     'first_name': <first>,
                     'last_name': <last>,
                     'password': '$1$' + <passwd_md5> },
     'first_name': <first>,
     'last_name': <last> }

Response

Response Codes : Response 200 : Successful authentication.

   { 'agent seed-capability' : <url> -- agent domain seed capability] }

4xx : If this credential has more than one account linked to it, and no specific account was specified in the optional parameters, the response will list a set of accounts to choose from.

   { 'reason': 'select account',  -- reason why authentication failed
     'accounts' : [ { 'first_name' : <first>, 'last_name' : <last> },
                    { 'first_name' : <first>, 'last_name' : <last> },
                    ... ] }

4xx : Unsuccessful authentication due to need for more information.

   { 'reason': <'tos'|'critical'|'more info'>,  -- reason why authentication failed
     'redirect' : <url>  } -- URL to visit to get more information on how to proceed

Other reasons:

   * no agent - 404
   * bad identity and authentication information - 403
   * agent not enabled (banned) - 403

5xx : Server unavailable.

   { 'reason': 'generic' }

Seed Capability

Client -> Agent Host (via seed cap): "I want cap X"

• This service supports named capabilities for the agent domain requested by the client

Required Parameters

Map of named capabilities to Options

   { 'caps': {<capability name> : { 'enabled' : <'true' | 'false'> },
     <capability name> : { 'enabled' : <'true' | 'false'> },
     ... }
   }
   <- Ok, here's the cap to do X
   -or-
   <- Bzzzp, you don't get to do X

Response

Map of capability name to capability URL:

   { 'caps': {<capability name> : <url>, <capability name> : <url>, ... }}

Example: Basic Login Capabilities

POST data:

   { 'establish_presence' : { 'enabled' : 'true' },
     'inventory' : { 'enabled' : 'true' },
     'non_existent_cap' : { 'enabled' : 'false' },
     'be_in_world' : { 'enabled' : 'true' } }

Response value:

   { 'establish_presence' : <cap GO>, 'inventory' : <cap I>, 'be_in_world' : <cap CTR> }

RezAvatar Capability

This is the hypothetical proposed protocol for the future with many region domains.

RezAvatar agent host service

   {'region_url': <r_url>, 'position':  [x, y, z]}

->

   {'session_id': <s_id>, 'secure_session_id': <ssid>, 'circuit_code': <cc>,
   'seed_cap': <s_cap>, 'ip_address': <ip_address>, 'udp_port': <udp_port>, 'look_at': [lx, ly, lz]}

The RezAvatar agent host service invokes the RezAvatar region host service on behalf of the client.

RezAvatar region host service

   {'avatar_id': <a_id>, ..., 'position': [x, y, z]}

->

   {'seed_cap': <s_cap>, 'ip_address': <ip_address>, 'udp_port': <upd port>, 'circuit_code': <cc>, 'session_id': <s_id>, 'secure_session_id': <ssid>, 'look_at': [lx, ly, lz]}

or

   403 Forbidden

legacy_login Capability

This is for connecting to an existing sim.

• Viewer -> Agent Host (via cap LL): "I'd like to log in using the legacy login protocols"

Required Parameters

   { 'start': <"first" | "last" | <uri> >,
     "channel": <channel>,
     "version": <client version>,
     "platform": <"Lin" | "Mac" | "Win">
     "mac": <MAC Address>,
     "options": <array of strings>,
     "id0": <uuid>,
     "agree_to_tos": <"true" | "false" | "">,
     "read_critical": <"true" | "false" | "">,
     "viewer_digest": <uuid>,
     "options" : [array of strings] }

start check for trust against region domain, attempt to log in to this region. If it is full or not available, or the agent is not allowed, invoke region domain service to select another. "First" means home location. If home is filled then the grid will try last. If last is filled and home is set, the grid will try home. If neither works, region domain will find a region to put you on.

channel the name of the client. Used to differentiate official viewers from third party clients.

options See Optional Parameters

id0 hardware hash (based on the serial number of the first hard drive in Windows) used for uniquely identifying computers.

viewer_digest MD5 hash of the viewer executable, only relevant when the channel is set to an official Second Life viewer.

Optional Parameters

The "options" key points to an array of optional options. Zero or more of the following character strings may appear in any order in the array:

   { 'options' : <"inventory-root" | "inventory-skeleton" | "inventory-lib-root" |
     "inventory-lib-owner" | "inventory-skel-lib" | "gestures" | "event_categories" |
     "event_notifications" | "classified_categories" | "buddy_list" | "ui-config" | 
     "login-flags" | "global-textures">* }

See Optional Response for descriptions of information returned from these options

Required Response

The valid (non-error) value returned by the login call is in standard xmlrpc name, value format. The most important of these is the "Login Seed-Capability" discussed below (not to be confused with the new "seed capability" for the new login procedure):

    { "last_name" : lastname ,
     "sim_ip" : 64.129.40.58 ,
     "start_location" : last ,
     "seconds_since_epoch" : 1195447316 ,
     "message" : -=- http://blog.secondlife.com -=- Visit the Official Linden Blog for the latest world status updates! ,
     "first_name" : first_name ,
     "circuit_code" : 245160577 ,
     "sim_port" : 13005 ,
     "secure_session_id" : fdb501ca-22f1-4470-b515-2650f54b8117 ,
     "look_at" : [r-0.85717299999999996274,r0.51502899999999995906,r0] ,
     "agent_id" : d5f403c7-7981-425d-a0b5-c65a3d0a4693 ,
     "inventory_host" : inv12-mysql ,
     "region_y" : 244992 ,
     "region_x" : 247808 ,
     "seed_capability" : https://sim2054.agni.lindenlab.com:12043/cap/d373fdc9-d275-e484-3ad2-4a9b231f4e34 ,
     "agent_access" : M ,
     "session_id" : 65a7213a-723a-4fcf-baca-7b247c4b43c5 ,
     "login" : true }

Optional Response

Note: all return values are in "name: value" format as used in Python 2.5 dictionaries unless otherwise noted.

inventory-root

UUID of the agent’s root inventory folder.

{ 'inventory-root': [{'folder_id': <uuid>}] }

inventory-skeleton

Initial list of folders in agent’s inventory. Returned as an array of five-entry dictionaries. Each dictionary element describes a folder with its name, version, type, its UUID, and the UUID of the containing folder.

{'inventory-skeleton': [{'parent_id': <uuid>, 'version': <int>, 'name': <name>, 'type_default': <int>, 'folder_id': <uuid>}, .... ]}

inventory-lib-root

folder_id of library root inventory folder.

{ 'inventory-lib-root': [{'folder_id': <uuid>}] }

inventory-lib-owner

agent_id of owner for inventory lib.

{ 'inventory-lib-owner': [{'agent_id': <uuid>}] }

inventory-skel-lib

Initial list of folders in agent’s inventory. Returned as an array of five element dictionaires. Each dictionary describes a folder with its name, its UUID, the UUID of the containing folder, its type, its version.

{'inventory-skeleton': [{'parent_id': <uuid>, 'version': <int>, 'name': <name>, 'type_default': <int>, 'folder_id': <uuid>},... ]}

gestures

List of active gestures. An array of two element dictionaries with the inventory item uuid and the asset uuid.

{ 'gestures': [{'item_id': <uuid>, 'asset_id': <uuid>},...] }

event_categories

List of different event categories, mapping category id (an integer) to a category name. Returned as an array of two element dictionaries. Each dictionary describes a category’s id and it’s name.

{ 'event_categories': [{'category_id': <int>, 'category_name': <name>},...] }

event_notifications

List of events for which the agent has pending notifications. An array of eight-element dictionaries containing: event_id, event_name, event_desc, event_date, grid_x, grid_y, x_region, y_region.

{'events': [{"event_id":<uuid>, "event_name"<name>,"event_desc":<string>, "event_date":<date>, "grid_x":<float>, "grid_y":<float>, "x_region":<float>, "y_region":<float>}, ...]}

classified_categories"

List of classifieds categories, mapping category id (an integer) to a category. Returned as an array of two element dictionaries with a category’s id and it’s name.

{ 'event_categories': [{'category_id': <int>, 'category_name': <name>},...] }

buddy-list

List of friends with granted and given rights masks. Returned as an array of three-element dictionaries with riend’s agent id, granted rights mask, given rights mask.

{ 'buddy-list':[{'buddy_id': <uuid>', 'buddy_rights_given': <int>, 'buddy_rights_has': <int>}, ....] }

ui-config

list of UI enabled/disabled states, currently: allow_first_life ('Y' or 'N') for teens.

{ 'ui-config': {'allow_first_life': if allow first life} }

login-flags

Several flags about the state of the agent.

{ 'login-flags': {'stipend_since_login': <'Y'|'N'>, 'ever_logged_in': <'Y'|'N'>, 'gendered': <'Y'|'N'>, 'daylight_savings': <'Y'|'N'>} }

global-textures

The asset ids of several global textures.

{ 'global-textures': {'sun_texture_id': <uuid>, 'moon_texture_id': <uuid>, 'cloud_texture_id': <uuid>} }