Remote Operations Reference
DRAFT
The is an initial reference to the operations implemented by the Java-based Hub plugins in support of the SP V4 Agents and any future Agents developed by us or third parties.
This material is subject to change but is at alpha/beta level stability at this time. There will be additional operations defined for logout and probably for providing OIDC information flows such as client metadata and key sets.
- 1 General DDF Message Format
- 2 HTTP Remoting
- 3 Agent Authentication
- 4 General Operations
- 4.1 ping
- 4.2 session-cache
- 4.2.1 Create Operation
- 4.2.2 Read Operation
- 4.2.3 Update Operation
- 4.2.4 Touch Operation
- 4.2.5 Delete Operation
- 5 Handler Operations
- 5.1 session-initiator
- 5.1.1 initiator/saml2
- 5.1.2 initiator/oidc
- 5.2 token-consumer
- 5.2.1 consumer/saml2-post
- 5.2.2 consumer/saml2-post-simplesign
- 5.2.3 consumer/saml2-artifact
- 5.3 logout-initiator
- 5.1 session-initiator
General DDF Message Format
Input messages are not entirely 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, and it is always named “application”.
All messages MAY include a “txid” member that is simply a correlation ID for Hub logging purposes and is opaque otherwise.
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. |
target | unsafe_string | Recovered resource URL acquired from original Agent request or by mapping a supplied state token back into the URL. |
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 |
local_addr | string | Server 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 |
Agent Authentication
Details TBD, just parking one issue for now…
The caching support in the Hub to leverage the JSESSIONID cookie works less well unless Jetty is told to drop the node suffix from its cookie values:
jetty.sessionIdManager.workerName=
Without that, the session ID inside the app server is not a one for one match to the cookie and while Jetty sees and honors the session if the cookie contains only the partial value, it keeps reissuing a Set-Cookie header to the Agent every time with the same value (but with the worker name suffixed). Doesn’t really hurt anything.
General Operations
These are generic functions that don’t involve a specific Application and so the input does not carry an “application” member.
ping
Testing operation that returns the current epoch in seconds.
session-cache
Remote implementation of a session cache. In practice implemented via the OpenSAML StorageService API but this is not an exposed assumption of the operation.
To avoid complexity, the HTTP method is fixed as POST, as many client libraries complicate use of other methods when using request bodies.
Create Operation
Stores new sessions and returns a key for retrieval.
Read Operation
Retrieves existing sessions using the key returned by a Create. If no matching session is found, an empty response is returned.
Update Operation
Updates a session in place if it has not been updated past a specified version. If the session no longer exists, an empty response is returned.
Touch Operation
Updates a session’s last access time to the current time.
Delete Operation
Deletes a session record.
Handler Operations
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.