Second Life Login API Strawman
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:
- The syntax follows [very roughly] that of Python data structures
- "--" followed by text, indicates a comment until the end of line, ala the C++ "//" style comments.
- { <represents a map or dictionary of one or more key>:<value pairs> } -- separated by commas
- "in quotes is a literal string"
- [ represents an array, of elements, separated by commas ]
- < represents a list of choices | separated by a vertical bar >
- < represents a value which can be substituted by an appropriate string described inside >
- '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/
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 * bad identity and authentication information * agent not enabled (banned)
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': region_url, 'position': [x, y, z]}
->
{'session_id': xxx, 'secure_session_id', ssid, 'circuit_code': cc,
'seed_cap': xxx, 'ip_address': xxx, 'udp_port': xxx, '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', ..., 'position': [x, y, z]}
->
{'seed_cap': xxx, 'ip_address': xxx, 'udp_port': xxx, 'circuit_code': xxx, 'session_id': session_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
inventory-root UUID of the root inventory folder in the client's inventory window
{'inventory-root' => {folder_id' => 'UUID of Folder ID'} }
inventory-skeleton "starter kit" inventory: name, folder_id, parent_id, type_default, version of all folders
{'inventory-skeleton' => {'name, folder_id, parent_id'},{'name, folder_id, parent_id'} ,{'name, folder_id, parent_id'} .... }
inventory-lib-root folder_id of library root inventory folder
{'inventory-lib-root' => 'folder_id'}
inventory-lib-owner agent_id of owner for inventory lib
{'inventory-lib-owner' => {'agent_id' => 'agent id uuid '}}
inventory-skel-lib LL supplied library of inventory items: same as inventory-skeleton, except global inventory
{'inventory-skeleton' => {'f.name, f.folder_id, f.parent_id, f.type_default, f.version '},
{'f.name, f.folder_id, f.parent_id, f.type_default, f.version'} ,
{'f.name, f.folder_id, f.parent_id, f.type_default, f.version'} .... }
gestures list of item_id, asset_id pairs for active gestures
{'gestures' => {gesture item_id, gesture asset_id}
{gesture item_id, gesture asset_id}
{gesture item_id, gesture asset_id} ....}
event_categories list of different event categories
{'event_categories' => {category_id (int), category_name(string)},
{category_id (int), category_name(string)},
{category_id (int), category_name(string)},
{category_id (int), category_name(string)}....}
event_notifications list of events for which you have notifications
{'gestures' => [event_id, event_name,event_desc, event_date, grid_x, grid_y, x_region, y_region ]
[event_id, event_name,event_desc, event_date, grid_x, grid_y, x_region, y_region ]
[event_id, event_name,event_desc, event_date, grid_x, grid_y, x_region, y_region ] ....}
classified_categories" return a list of classifieds categories
{'event_categories' => {[category_id (int), category_name(string)],
[category_id (int), category_name(string)],
[category_id (int), category_name(string)],
[category_id (int), category_name(string)]....}
buddy-list agent_id, granted rights and given rights of everyone that is your buddy
{'buddy-list' => {buddy_id, buddy_rights_has, buddy_rights_given},
{buddy_id, buddy_rights_has, buddy_rights_given},
{buddy_id, buddy_rights_has, buddy_rights_given},....}
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 if set, return 'stipend_since_login', 'ever_logged_in', 'gendered', and 'daylight_savings' values
{'login-flags' => {'stipend_since_login' => $stipend_since_login,
'ever_logged_in' => $ever_logged_in,
'gendered' => $gendered,
'daylight_savings' => $daylight_savings
}}
global-textures Texture UUIDs for global textures
{'global-textures' => {'sun_texture_id' => $sun_texture_id,
'moon_texture_id' => $moon_texture_id,
'cloud_texture_id' => $cloud_texture_id
}}