Skip to content

Latest commit

 

History

History
92 lines (69 loc) · 3.4 KB

HttpAuthentication.adoc

File metadata and controls

92 lines (69 loc) · 3.4 KB
Raw

HTTP Authentication

Table of Contents

Introduction

HTTP Authentication is specified in cite:[rfc7235] and provides the overall authentication framework for a number of authentication 'schemes'.

Besides the 'Basic' HTTP Authentication Scheme (supported more for the sake of completeness and discussed in [ch-basic-authentication]), the 'Bearer' Authentication Scheme is important for securing APIs using OAuth2, covered in [ch-applications] and beyond.

Protection Spaces

The protection space determines the domain over which credentials can be automatically applied.

— RFC 7235

In the HTTP Authentication framework, a protection space governs a set of resources for which requests are authenticated.

If a request is made for a resource in a protection space, the User making the request is authenticated prior to any authorization decisions being made. The details depend on the configuration of the protection space.

In Site, a protection space is defined in a Document in the database.

If the Operation on the resource fails to be authorized, and the request does not supply valid credentials, then the request is met with a 401 Unauthorized response, along with a WWW-Authenticate header giving details of how to authenticate according to the protection spaces that the resource belongs to.

If the request contains valid credentials, yet the Operation on the resource is still not authorized, a 403 Forbidden response is returned.

Being in a protection space does not imply that a resource cannot still be publically accessible without credentials. It just means that any credentials in the request might be used when deciding if the Operation corresponding to the request’s method can be authorized. This is why a 401 response status is labelled Unauthorized rather than `Unauthenticated`. It’s possible that a resource might generate a successful response for unauthenticated users, showing only publically accessible information.

Caution

Do not rely on a protection space providing protection for your resource. You still need to write rules for how your Operations will be authorized!

Realm values

A protection space is defined by the canonical root URI of the server being accessed, in combination with the realm value if present.

— RFC 7235

Usually, a protection space is defined to span a whole domain (https://example.org) or root URI (https://foo.example.org, https://bar.example.org). In rare cases you may even want to partition a root URI into multiple protection spaces. That’s possible too, using a different realm value for each partition.

Creating a Protection Space

Since a protection space is represented as a Document, an Operation is required to create one. If one is not already set up we can create it one, as shown in Creating the Operation to establish a Protection Space.

Example 1. Creating the Operation to establish a Protection Space
link:../../test/juxt/book.clj[role=include]

We’ll grant this permission to our REPL user:

link:../../test/juxt/book.clj[role=include]
Important

Copy the code in Creating the Operation to establish a Protection Space into a REPL, edit as necessary and evaluate.