OWIN Common Keys

Author: OWIN Working Group.

Last updated: 12 March 2015


  1. Overview
  2. Key usage guidelines
  3. Naming conventions
  4. Value conventions
  5. Capabilities announcement and detection
  6. Common keys

1. Overview

This document contains guidelines for adding functionality to OWIN based servers or application via additional keys in the IDictionary collections (e.g. the request environment or the startup properties). This includes naming conventions, value conventions, and a list of know common keys and their semantics.

These guidelines and keys are provided independently of the OWIN specification as the list of common keys below is expected to grow independently of the OWIN standard.

The following guidelines apply to the keys and values specifically listed below, as well as for custom keys and values defined by individual implementations.

2. Key usage guidelines

The IDictionary collections can be used to extend the OWIN interface with additional functionality.

3. Naming conventions

The IDictionary collections are open and mutable for storing arbitrary data. To avoid collisions between components, the following key naming conventions SHOULD be honored.

4. Value conventions

5. Capabilities announcement and detection

It is important for applications to be able to determine if a specific feature is supported by the current server or middleware. The following pattern is recommended for announcing and detecting feature/extension support.

6. Common keys

Keys and values listed here are those that are anticipated to be common across multiple implementations, but are not strictly required for basic operations.

Key Type Startup Shutdown Request Description
ssl.ClientCertificate X509Certificate     X The client certificate provided during HTTPS SSL negotiation.
server.RemoteIpAddress String     X The IP Address of the remote client. E.g. or ::1
server.RemotePort String     X The port of the remote client. E.g. 1234
server.LocalIpAddress String     X The local IP Address the request was received on. E.g. or ::1
server.LocalPort String     X The port the request was received on. E.g. 80
server.IsLocal Boolean     X Was the request sent from the same machine? E.g. true or false.
host.TraceOutput TextWriter X   X A tracing output that may be provided by the host.
host.Addresses IList<IDictionary<string, object>> X     A list of per-address server configuration. The following keys are defined with string values: scheme, host, port, path.
server.Capabilities IDictionary<string, object> X   X Global capabilities that do not change on a per-request basis. See Section 5 above.
server.OnSendingHeaders Action<Action<object>, object>     X Allows the caller to register an Action callback that fires as a last chance to modify response headers, status code, reason phrase, or protocol. The object parameter is an optional state object that will passed to the callback.
server.OnInit Action<Func<Task>> X     An Action<Func<Task>> that allows middleware to register a callback that the server will call once when initializing.
server.OnDispose CancellationToken   X   A CancellationToken that represents when the server is disposing.
websocket.*   X   X See the WebSocket extension.
sendfile.*   X   X See the SendFile extension.
opaque.*   X   X See the Opaque extension.