Remote Operations Reference

DRAFT

This is a starting point to document the many operations implemented for SP agents to call on the Java hub (implemented in an IdP plugin) to perform.

This material is highly subject to change.

1 General DDF Message Format
2 HTTP Remoting
3 General Operations
- 3.1 ping
- 3.2 storage
- 3.3 sealer
- 3.4 session-initiator
  - 3.4.1 initiator/saml2
- 3.5 token-consumer
  - 3.5.1 consumer/saml2-post
  - 3.5.2 consumer/saml2-post-simplesign
  - 3.5.3 consumer/saml2-artifact

General DDF Message Format

Input messages are not formally standardized, but:

Currently the agent identity is not included (it’s in the HTTP layer) but this may change.
Not all messages will include an application ID, but many do.
If the message includes a forwarded HTTP request, it will be in a structure member called “http” (see below).

Output messages are always a structure with some defined members that may or may not be present, plus any others defined by the operation.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
event	string	Always present, contains “success”, or the error event resulting from a failed operation.
cached_auth	string	If present, a value to use as a cached authentication value in a cookie agreed upon OOB (typically JSESSIONID or __Host-JSESSIONID as approproate for the deployed container). It is optional for agents to support or use this.
http	struct	If present, contains an HTTP response to relay back to the user agent. Not all operations will contain one, but usually if they do, it will be mandatory and expected by the agent.

All operations are top-level webflows defined at /idp/profile/sp/opname

Unless otherwise specified, all operations MAY return an “event” member as noted above, and a number of standard events exist for invalid input scenarios.

HTTP Remoting

When an HTTP request has to be remoted (in whole or in part), the input will contain a struct member named “http” with the following substructure:

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
scheme	string	Requested scheme (generally https or http)
hostname	unsafe_string	Requested hostname reported by web server
port	integer	Requested port
content_type	string	Value of content type header
body	unsafe_string	Body content. Nominally calling this unsafe and to be handled as bytes, but probably will end up being assumed to be UTF-8 when actually processed as data by the hub.
content_length	long integer	Value of content length header
remote_user	string	Value of REMOTE_USER internal server variable
remote_addr	string	Requesting client address as reported by web server
method	string	Requested HTTP method
uri	unsafe_string	Requested URI (the part after the scheme, host, and port
url	unsafe_string	Requested URL (including scheme, host, and port (if non-default)
query	string	Requested query string
headers	structure	Each header is populated as a member whose name is the header name and whose unsafe_string value is the header value

When an HTTP response has to be remoted, the output will contain a struct member named “http” with the following substructure:

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
redirect	unsafe_string	Redirect URL to return to client, mutually exclusive with response structure
response.data	unsafe_string	Response body
response.status	integer	HTTP response status code
headers	list	Each header is populated as a list element whose name is the header name and whose unsafe_string value is the header value

General Operations

These are generic functions that don’t involve a specific Application and so the input does not carry an “appId” member.

ping

Testing operation that returns the current epoch in seconds.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
epoch	longinteger	Current epoch in seconds

storage

Remote implementation of the StorageService API (probably will end up as a subset, TBD). The storage context values are automatically prefixed by the agent ID to avoid conflicts with other agents sharing the same storage back-end.

The requested operation is based on the HTTP method used, one of PUT, GET, POST, or DELETE, corresponding to record creation, read, update, or delete. When doing a non-versioned update, the record will be created if not found to update.

TBD: Probably will need an atomic create/read/update operation of some sort to save round trips, likely based on flag in the input.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
context	string	storage context
key	string	storage key
value	string	storage value
exp	longinteger	expiration time in seconds since the beginning of the epoch
version	longinteger	record version

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
value	string	storage value
exp	longinteger	expiration time in seconds since the beginning of the epoch
version	longinteger	record version

Event	Description

Event	Description
InputOutputError	Storage-related exception
DuplicateRecord	Attempt to create a record with the same context and key as an existing record
RecordNotFound	Missing record on read, versioned update, or delete operation
VersionMismatch	Version mismatch when attempting a versioned update operation

sealer

Remote implementation of the DataSealer API allowing agents to encrypt or decrypt private data. The agent ID is embedded in the data being encrypted to cross-check ownership.

The requested operation is based on the HTTP method used: GET signifies decryption/unwrapping and POST signifies encryption/wrapping.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
value	string	input value
exp	longinteger	expiration time in seconds since the beginning of the epoch

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
value	string	output value

Event	Description

Event	Description
MessageProcessingError	Failure performing encryption/decryption
MessageExpired	Decrypted data was expired
AccessDenied	Decrypted data was not associated with this agent

session-initiator

API to initiate a login request to an IdP on behalf of the requesting agent’s application. This is a facade for an unbounded set of subflows that implement support for particular protocols. The input contract contains some fixed inputs and variable inputs that depend on the implementation(s) of subflows available. The operation will attempt any number of initiator subflows in a defined order until one succeeds or all have failed.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
application	string	Application ID for request
state	string	A translated state token used to recover the URL to direct the user agent after processing a response to thie request being created, indicates that the state has already been generated
handler	unsafe_string	Specifies the URL for this handler in the agent in case the hub is required to initiate discovery (and thus return control to the agent afterwards)
target	unsafe_string	Used in the absence of the “state” parameter in cases in which the resource URL input to state token translation must be supplied explicitly because the “http” structure encapsulates a request to an agent handler rather than an actual resource URL
http	structure	Used in the absence of the “state” paremeter, this is a remoted request from client to provide access to input cookie(s) when handling state token translation
response_url	string or list	If a string, the value is a “universal” response URL that should handle any protocol or binding. If a list, then compatibility with legacy binding-specific endpoints is enabled. Each list element is a string node whose value is the location URL. The name of the node must be set to one of a set of legacy binding indicators that map to SAML bindings to facilitate legacy compatibility with pre-V4 endpoint layout.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
http	structure	a remoted/tunneled HTTP response to deliver to the client (including cookies, etc.)

Event	Description

Event	Description
NoPotentialFlow	No configured initiator subflows handled the request

initiator/saml2

Session initiator subflow supporting SAML 2.0, i.e., responsible for producing SAML 2.0 <AuthnRequest> messages on behalf of agents. A number of inputs are supported to influence request generation, typically based on content, but this can be disallowed on a per-Agent/Application/RelyingParty basis.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
authority	string	IdP to use, if known
entityID	string	SAML-specific name for “authority”
authnContextClassRef	list of strings	Requests that particular authentication context classes be used by the IdP.
authnContextComparison	string	One of [ exact, minimum, maximum, better ]
forceAuthn	integer	1 indicates ForceAuthn should be set to true
isPassive	integer	1 indicates IsPassive should be set to true
NameIDFormat	string	Populates `<NameIDPolicy>` element’s `Format` in request
SPNameQualifier	string	Populates `<NameIDPolicy>` element’s `SPNameQualifier` in request
attributeIndex	integer	Populates the `AttributeConsumingServiceIndex` XML attribute in request

token-consumer

API to process an authentication response on behalf of the requesting agent’s application. This is a facade for an unbounded set of subflows that implement support for particular protocols. The input contract contains some fixed inputs and variable inputs that depend on the implementation(s) of subflows available. The operation will check each enabled subflow supported by an application for usability and run the first (and only the first) subflow indicating it can handle the request.

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
application	string	application ID for request
home_url	unsafe_string	a default URL to redirect to in the event no state can be recovered
http	structure	Remoted request as per documentation

Member Name	DDF Type	Content/Definition

Member Name	DDF Type	Content/Definition
validation_errors	list	collection of error messages produced during validation, principally for helping verify behavior while testing
http	structure	a remoted/tunneled HTTP response to deliver to the client (including cookies, etc.)
session.opaque	string	opaque session data that must be stored with the client’s session and may be needed during subsequent hub operations
session.attributes	list	collection of serialized attributes extracted from token

Each “attribute” (used here in an informal sense) is serialized into the output based on its value type(s) as follows. The name of the child object is the attribute’s ID and it is a list containing the values. Each value is an unnamed object whose type depends on the original value type in Java:

StringAttributeValue (note that empty or null values here are not included)
- string
ScopedStringAttributeValue
- structure with two string members, “value” and “scope”
DateTimeAttributeValue
- long (representing epoch in seconds, corresponding to a 64-bit time_t)
ByteAttributeValue
- unsafe_string

Event	Description

Event	Description
NoPotentialFlow	No configured consumer subflows handled the request

consumer/saml2-post

consumer/saml2-post-simplesign

consumer/saml2-artifact

Token consumer subflows for each supported SAML binding. These detect compatibility via examination of the HTTP request. Inputs and outputs are as above.

Development Center