Second Life Login API Strawman
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
- *Viewer sends credentials to the Login Service #Login_Web_Service
- 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
- *Viewer requests capabilities needed for login via received seed capability. #Seed_Capability
- *(future) Viewer Polls Agent Host for messages via long-poll #poll_for_messages_Capability
- *(future) Viewer can send instant messages before being in world. #instant_message_Capability
- *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
- *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>} }