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

Jump to bottom

Basic Authentication Scheme #5

Merged
merged 1 commit into from
Nov 26, 2015
Merged

Basic Authentication Scheme #5

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
60 changes: 60 additions & 0 deletions draft/authentication-basic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
RFC: XXXX
Author: Kyle Fuller
Status: Draft
Created: 2015-09-22
Last Modified: 2015-09-28
---

# API Blueprint RFC XXXX: Basic Authentication Scheme

## Table of Contents

- [Abstract](#abstract)
- [Motivation](#motivation)
- [Rationale](#rationale)
- [Backwards Compatibility](#backwards-compatibility)

## Abstract

This RFC adds the "Basic" authentication scheme for the Authentication
framework proposed in RFC 0002.

## Motivation

Basic authentication is a commonly used authentication mechanism, and is part
of the HTTP/1.1 specification defined in
[RFC1945 section 11.1](http://tools.ietf.org/html/rfc1945#section-11.1).

## Rationale

The "Basic" authentication scheme is based on the model that the user
agent must authenticate itself with a user-ID and a password.

As such, a basic authentication scheme may configure two properties,
`username` and `password`. These properties indicate a sample username and
password that may be used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What exactly are we configuring here? We say properties. But we are actually configuring sample username and sample password. I don't see any mention about the values being an example.

Also, I think we should have a default example username and example password for Basic.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As per the MSON Specification, 2.3.1 Property Member Types, the properties within an MSON object are called "Properties". The wording here reflects that.

These are properties within the authentication scheme's object.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As for the sample/example, I'm not sure I follow. What would the difference between sample and example be?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mention the default values for the properties username and password, then this looks good.


For example, as a named authentication scheme:

```apib
### Auth (Basic)

+ username: kyle
+ password: b2952d03bda09cb5f63b0162fbbee77c
```

As an anonymous scheme:

```apib
+ Authenticated (Basic)
+ username: kyle
+ password: b2952d03bda09cb5f63b0162fbbee77c
```

There are no default values for the sample `username` and `password`. When
these are both unset, there is no sample credentials.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kylef Are we sure about this? Some users might want to directly use Basic simply like this:

+ Authenticated (Basic)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes they can, just because there are no defaults, doesn't mean you can't indicate that a resource/group/action/request example etc supports the basic scheme. It just represents there are not sample credentials available.

You don't need to define a sample username or password to use this scheme.

Does this make sense? Is there something I can add to make this a little clearer?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't need to define a sample username or password to use this scheme.

I understand and I agree. But we also need to think about the tools which use API Blueprint. Dredd, Documentation and others like them. Let's take the example of Dredd. User uses the Basic directly for an action. But what values will dredd use now when testing the server? If we leave this upto the tools, each one of them will have their own default values and user will start getting overwhelmed. Having a default sample username and password will avoid all this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if there is no sample values, a user should have to supply the value to use at run-time. For example:

$ dredd --user kyle:password

I disagree that we should require services to provide a sample account which is described in the blueprint (and even dictating the default username/password).

/cc @netmilk -- would love to hear your thoughts around this matter.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dredd supports basic auth already by supplying the user and password from command line as described above by @kylef and I don't see a reason why we shouldn't keep it that way. I think the mandatory sample account is not necessary. Blueprint doesn't require defaults on anything so why it should all of a sudden require it it doesn't make sense. Sure I would push users to provide values as a convenient way how to do things but not force them to.


Implementations of the Basic Authentication Scheme may provide sufficient
warnings or errors if a `username` or `password` is configured without
the counterpart.