Remote Operations Reference
- Scott Cantor
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 |
|---|---|---|
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 |
|---|---|---|
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 |
|---|---|---|
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.
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.
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.
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.
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.
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.
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.