OpenID

OpenID HTTP Authentication

This page describes a small adaptation of the OpenID Authentication protocol that uses HTTP Authentication mechanisms as its transport.

This protocol is intended to be used for non-browser-based protocols, such as "Send A Message", where the caller can potentially be a non-human agent authenticating as itself. It is not intended to replace conventional OpenID Authentication in the "sign-on" case.

Contents

Terminology

Caller
The agent making the request.

Service Endpoint
The agent accepting the request.

Service Endpoint RP
The component of the Service Endpoint that acts as an OpenID Relying Party.

This specification also uses terms from the OpenID Authentication Specification with the same meaning.

Message Formats

Messages are sent via the X-OpenID-Authenticate header in conjunction with HTTP authentication headers.

For requests, this looks like the following: 

    Authorization: OpenID
    X-OpenID-Authenticate: ns="http://specs.openid.net/auth/2.0", field1="value", field2="value"

For responses, a 401 Unauthorized status is returned and the following headers are included: 

    WWW-Authenticate: OpenID realm="some string"
    X-OpenID-Authenticate: ns="http://specs.openid.net/auth/2.0", field1="value", field2="value"

Note that the "realm" in the WWW-Authenticate header is that defined and required by the HTTP specification, not an OpenID Authentication trust realm. Trust realms are not used by this protocol since they are only relevant for the redirect-based OpenID Authentication with its return_url.

The "ns" field is always present with the given value to indicate that OpenID Authentication 2.0 is the protocol in use.

OpenID Authentication extensions can also be used with this protocol, by encoding their key-value pairs using the above syntax and using the same namespacing mechanism used in OpenID Authentication, though omitting the "openid." prefix on the key names.

TODO: Define the syntax of X-OpenID-Authenticate more formally.

Protocol Flow

The protocol flow is very similar to that of normal OpenID Authentication, but uses HTTP Authentication as a transport rather than the mixture of direct HTTP requests and the "redirect dance".

Initial Plain Request (Optional)

For callers that support a variety of authentication mechanisms, they may first wish to make a plain request with no authentication credentials. The Service Endpoint will then respond with a 401 Unauthorized response and the following headers: 

    WWW-Authenticate: OpenID realm="some string"
    X-OpenID-Authenticate: ns="http://specs.openid.net/auth/2.0"

This may be returned in conjunction with WWW-Authenticate headers specifying other HTTP authentication schemes. The Caller is then free to choose from the available schemes the most suitable for this transaction. Obviously only if the "OpenID" scheme is selected does this protocol continue.

Note: The "realm" given here is the one defined in the HTTP specification, not the OpenID trust realm. Trust realms are not used with this protocol because it does not do a "redirect dance" and thus there is no return_to URL to trust.

(Open Issue: is that "ns" thing declaring what version the endpoint supports? If so, what would we do if a new OpenID version came out and the RP needed to declare support for both?)

Association Request

If the caller has not interacted with this service endpoint before, it must first attempt to associate with the service endpoint. This is done by making a request to the service endpoint the following additional argument:

claimed_id
(optional) The identifier that the caller wishes to authenticate as.

The Service Endpoint RP must now do discovery on the claimed identifier and optionally associate with its OP as described in OpenID Authentication Draft 11 sections 7.3 and 8 respectively. If an association has been formed, the Service Endpoint RP will now have an assoc_handle value for the OP, which it returns as part of the response. If the Service Endpoint RP is going to use stateless mode ("dumb mode") then it does not return an assoc_handle. The response is a 401 Unauthorized response containing the following additional arguments:

assoc_handle
(optional) The assoc_handle that resulted from the association between the Service Endpoint RP and the OP, if any.

Compute Assertion

Now that the caller has the assoc_handle (if needed), the caller must obtain an assertion signature. How this is done is outside of the scope of this protocol, but in the case where a non-human agent is authenticating as itself it may act as its own OP and thus compute the signature internally.

An application acting on behalf of a user might use the Signature Request Protocol to obtain a signature from the user's OP, if the OP supports that protocol.

The caller must somehow obtain or compute all of the information necessary to make the next request as described in the following section.

Authenticated Request

The caller now repeats its initial request with the following X-OpenID-Authenticate arguments:

claimed_id
The identifier that the caller wishes to authenticate as.

identity
The OP-local identifier that was used to authenticate the user.

response_nonce
The response_nonce field as described in OpenID Authentication 2.0 Draft 11 section 10.1.

invalidate_handle
The invalidate_handle field as described in OpenID Authentication 2.0 Draft 11 section 10.1.

assoc_handle
The assoc_handle field used to sign the assertion.

signed
Comma-separated list of these request fields that were used to make up the signature. Must include at least "identity,claimed_id,return_to,assoc_handle,response_nonce,request_uri". Note that request_uri is a special computed field described below and not a standard request argument.

sig
Base 64 encoded signature calculated as specified in OpenID Authentication 2.0 Draft 11 Section 6

When recieving this request, the Service Endpoint RP must verify the signature as in a standard OpenID Authentication 2.0 request, either by making use of the association shared secret in stateful mode or doing a check_authentication request in stateless mode, and if it succeeds authentication has been successful. If it fails, the Service Endpoint responds as it did in the Association Request phase described above.

Note that the Service Endpoint RP MUST ensure that the given claimed_id does indeed declare the given OP-local identifier, either by doing discovery at this stage or by having retained discovery results from the association phase.

The request_url Value

The "signed" field as described above includes a special value request_uri which is not directly included in the request arguments but is computed as follows, based on the caller's request: 

   request_uri = ""
   
   if ({Caller is making an HTTPS request})
      request_uri .= "https://"
   else
      request_uri .= "http://"
   
   request_uri .= {contents of HTTP "Host" header}
   request_uri .= {whatever path string was given after the method in the HTTP request}
   return request_uri

This ensures that the signature cannot be replayed to make requests for other URLs.

Distinguishing Request Types

When the Service Endpoint recieves a request with the appropriate "Authenticate" header, it must determine whether it is an Association Request or an Authenticated Request. If the "sig" field is present, it is to be processed as an Authentication Request. If the "sig" field is absent, it is to be processed as an Association Request.

Caching Association Handles

A caller MAY cache and re-use an assoc_handle for subsequent requests with the same claimed_id, thus allowing it to skip the Association Request phase and make an Authenticated Request directly. If the assoc_handle used is no longer valid, as described above the Service Endpoint will respond as for an Association Request, including a new assoc_handle which should be used to make a repeated Authenticated Request.

Retrieved from "http://wiki.openid.net/OpenID_HTTP_Authentication"