François' Blog

OAuth 2.0 Authorization Server Discovery

Published on 2015-07-31

Introduction

Currently an OAuth client is supposed to know the Authorization Server (AS) that is used by a particular Resource Server (RS). This blog post proposes a discovery mechanism where the client only needs to know the location of the RS.

The RS chooses the AS it will use. There is no point for the client to know what the AS is beforehand. It can also change at any point at the RS's discretion. As far as I know there is no standardized way of doing this.

Proposal

Currently, the WWW-Authenticate header is sent back by the RS if no Authorization header is provided by the client or if it uses an invalid or expired token. If the client sends an "unauthenticated" request, i.e. without the Authorization header, like shown below:

POST /endpoint HTTP/1.1
Host: rs.example.org
Content-Type: application/x-www-form-urlencoded

foo=bar

In most cases this will not succeed, although in some it might if out-of-band authorization was already establish, e.g. using Kerberos in enterprise networks. However, in most scenarios this request will not be allowed. Currently the response would be like this:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer 
    realm="Phubble"

Now, the OAuth Bearer specification provides for specifying the OAuth scope required for performing a certain action, e.g. the scope https://micropub.net/scope#create is required to be able to perform the operation. This field is then included in the WWW-Authenticate header to tell the client which scope to request:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer 
    realm="Phubble",
    scope="https://micropub.net/scope#create"

Now, for discovery of the AS I propose two new key-value pairs: authorization_endpoint and token_endpoint. This will allow the client to select the correct AS:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer 
    realm="Phubble",
    scope="https://micropub.net/scope#create",
    authorization_endpoint="https://as.example.org/authorize",
    token_endpoint="https://as.example.org/token"

This proposal thus solves two issues: the discovery of the AS and the discovery of the required scope for a particular action on the RS's endpoint.

References

History