Spec Documentation for Identity

The identity represents both a user (references to a user are references to its identity Url) and also the centre of a group of applications (similar to the name server process in a microkernel). All applications have a single creator identity which they trust.

NOTE: All methods have two arguments which come before those listed per-method: senderIdentifier and token.

-senderIdentifier: The Url of the sending application instance (the application needs to be receiving calls at this Url) or the identifier associated with a pre-authenticated application instance. This will never change over the course of an application instance's lifespan.

-token: The next authentication key in the sequence decided upon by the most recent authorization operation between the application and the identity. Note that this generated by the calling application in the case of authorizeNewApplication or reauthorizeApplication and must be a non-empty string and the same one returned when the identity calls back to the application on application.getInFlightToken.


Methods

Method: "com.openautonomy.protocols.identity.canLoginRemotelyAsIdentity" (XML-RPC)

The basis of the distributed login system. When a server is given this key by the user agent, it calls this method on the target identity to verify that it was the source.
Returns true if the receiver agrees that they generated key.

Arguments

Returns: boolean

Method: "com.openautonomy.protocols.identity.authorizeNewApplication" (XML-RPC)

Called once by an application when it first wishes to build a trust relationship with the receiving identity.
Will call back to the sender's "application.getInFlightToken" method to verify the identity before returning. This verification is done by checking the given token (see above) against the one returned from the application. This proves that both the application and identity are talking to who they think they are (but does not imply that the identity should trust the application).
Note that this is never called by pre-authorized apps.
New applications start with a trust level of NONE and can therefore not access other applications or provide any services to other applications.

Arguments

Returns: string100

Method: "com.openautonomy.protocols.identity.reauthorizeApplication" (XML-RPC)

Called by an application when it has had a key rejected due to a progressive token mis-match.
Almost exactly the same semantics as those required for identity.authorizeNewApplication except that it doesn't set instance name or icon.

Arguments

Returns: string100

Method: "com.openautonomy.protocols.identity.advertiseApplicationCapability" (XML-RPC)

This will return true if it worked or false if the key was rejected (meaning the slow path needs to be taken).
Called by an application to inform the receiver that it wishes to offer a capability to other applications.
The implementation of the capability is completely outside this spec and can be implemented however the server and client applications agree.

Arguments

Returns: boolean

Method: "com.openautonomy.protocols.identity.setApplicationStatus" (XML-RPC)

This will return true if it worked or an error if something went wrong.
Provides a very simple way for an application to notify the user that it needs attention (or just to show the user a summary of the application's state).

Arguments

Returns: boolean

Method: "com.openautonomy.protocols.identity.requestApplicationsForCapability" (XML-RPC)

Used by one application to request the location of other applications managed by the receiver which provide the requested capability.

Arguments

Returns: fullApplicationInfoArray

Method: "com.openautonomy.protocols.identity.verifyApplicationKeyForCapability" (XML-RPC)

Called by an application providing a capability the first time another application tries to access its interface to request that the identity verify that it did hand out this authentication key and to return data about the application on the other side of the connection.

Arguments

Returns: remoteApplicationInfo

Method: "com.openautonomy.protocols.identity.getUnifiedTrustGroups" (XML-RPC)

Returns a struct describing the receiver's trust groups (both custom, and the built-in PRIVATE and TRUSTED) where the keys are the names mapping to arrays of the identity Urls. Note that the caller must have at least MIN trust to receive more than just PRIVATE and TRUSTED entries in the array.

Arguments

Returns: trustGroupMap

Method: "com.openautonomy.protocols.identity.getForeignIdentityReferralToken" (XML-RPC)

Returns a security token to be used in a one-time attempt to lookup foreign applications owned by a foreign identity.
Called by an application owned by the receiver when it wishes to request access to applications owned by another identity. It requests a token for the given foreign identity which that identity will then use to verify the ownership of the sending application.

Arguments

Returns: string100

Method: "com.openautonomy.protocols.identity.requestForeignApplicationsForCapability" (XML-RPC)

Called by an application to ask a foreign identity for applications which provided the requested capability. The $referralToken must have previous been returned by a call to getForeignIdentityReferralToken() on $foreignReferringIdentity.
Return value is the same as requestApplicationsForCapability() unless the referral fails to validate or unless the receiving identity refuses to grant access to this foreign application.
$senderIdentifier is the 'foreign' application instance trying to talk to the $receiverUrl and $authKey is the referral token returned by a previous getForeignIdentityReferralToken call made to $foreignReferringIdentity.
Called by an application which is NOT owned by the receiver to request a list of the applications it DOES own which provide the requested capability. The token passed in is the one provided by a previous call to identity.getForeignIdentityReferralToken and the receiver will call back to that initial issuer (foreignReferringIdentity) via its identity.verifyForeignReferralToken method to ensure that this was the token given out, thus allowing the receiver to know that the sender is owned by foreignReferringIdentity. Note that this does not imply that the receiver trusts foreignReferringIdentity or the sender. Furthermore, it is up to the target application to determine if it wishes to trust a foreign application.

Arguments

Returns: fullApplicationInfoArray

Method: "com.openautonomy.protocols.identity.verifyForeignReferralToken" (XML-RPC)

Called by a foreign identity after it receives a requestForeignApplicationsForCapability() call in order to verify that the referring identity did, in fact, grant this application the given $referralToken.
Return value is a tuple of (trustLevel, name) unless the referralToken is rejected.
Note that $senderIdentifier here is the Url of the sending identity who is trying to verify the token supposedly granted by the receiver and $authKey is the referral token granted by $receiverUrl in a previous getForeignIdentityReferralToken call.
Called by a foreign identity to verify that the receiver issued its given token via a previous call to identity.getForeignIdentityReferralToken made by the application identified by requestingApplicationIdentifier (requestingApplicationIdentifier claimed that the receiver owns it).

Arguments

Returns: foreignApplicationInfo

Method: "com.openautonomy.protocols.identity.addIdentityToTrustedList" (XML-RPC)

Called by an application (with MAX trust) to add the given identity to the receiver's trusted list (implicitly adds them to the TRUSTED trust group).

Arguments

Returns: boolean

Method: "com.openautonomy.protocols.identity.removeIdentityFromTrustedList" (XML-RPC)

Called by an application (with MAX trust) to remove the given identity from the receiver's trusted list (implicitly removes them from the TRUSTED trust group).

Arguments

Returns: boolean

Method: "com.openautonomy.protocols.identity.getInstalledApplicationList" (XML-RPC)

Called to request and array of the identity's applications. The content of the returned list depends on the trust level of the caller. MAX trust callers will see identifier (which, in the case of a web app is its Url), name, iconUrl, statusString, statusItemCount, statusTime. Anonymous or callers with less than MAX trust will only see: identifier, name, iconUrl.
Further, a callback URL can be sent (send empty string if not interested) which will be used if any of the returned data has changed in ways the receiver thinks the caller would want to know. Note that the caller can't rely on this link being called as the receiver is allowed to ignore it or otherwise fail to deliver it.
Keys returned in tuples: identifier, name, iconUrl, statusString (MAX trust only), statusItemCount (MAX trust only), statusTime (MAX trust only).

Arguments

Returns: installedApplicationInfoArray

Variable Types

Array types

Struct types

Map types

Primitive Types

Constrained Types