Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

explain impossibility of using email addresses with colons in them for HTTP Basic auth #1246

Merged
merged 1 commit into from
Oct 27, 2024
Merged

explain impossibility of using email addresses with colons in them for HTTP Basic auth #1246

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -628,6 +628,8 @@ tags:
Standard HTTP Basic Authentication is allowed, but **strongly discouraged**. This is because the server must verify your password with every single request, which is very slow to compute: typically, this will add hundreds of milliseconds to each request. For some one-off tasks and in cases where there is no other choice, it is reasonable to choose Basic authentication, but wherever possible we strongly encourage the use of any other authentication method.

In addition, because credentials are sent in plaintext as part of the request, **the server will only accept Basic auth over HTTPS**. If your ODK Central server is set up over plain HTTP, it will not accept Basic auth.

Furthermore, authenticating using accounts with email addresses with a colon (":") in them is not possible.
- name: App User Authentication
x-parent-tag: Authentication
description: |-
Expand Down Expand Up @@ -978,6 +980,8 @@ paths:

As given by [the standard](https://en.wikipedia.org/wiki/Basic_access_authentication), the text following the `Basic` marker here is a base64 encoding of the credentials, provided in the form `email:password` (in this example `my.email.address@getodk.org:my.password`).

Because the colon symbol (":") is used as a separator, authenticating using an email address containing a colon is not possible. This is a general limitation of this authentication method; it is not specific to ODK Central.

Unlike the standard, we do not require the client to first send an unauthenticated request and retry the request only after receiving a `WWW-Authenticate` response, and in fact we will never send the `WWW-Authenticate` header. This is mostly because, as noted above, we generally discourage the use of this authentication method, and would rather not advertise its use openly. As a result, if you wish to use Basic Authentication, directly supply the header on any request that needs it.

_(There is not really anything at `/v1/example2`; this section only demonstrates how generally to use Basic Authentication.)_
Expand Down