API Blueprint RFC 2: Authentication Framework
Table of Contents
This RFC proposes an authentication framework that you can use to mark resource groups, resources, actions or requests as authenticated. Along with defining a framework for creating authentication schemes.
This RFC does not propose any specific authentication schemes, those are to be created outside of this RFC.
Being able to express authentication in a machine readable way will allow tools around API Blueprint to utilise authentication.
Authentication Scheme Type Definition
Authentication schemes can be defined in an API Blueprint under an "Authentication Schemes" heading in an API Blueprint. Inside this header may be a sub-heading which specifies any named authentication types supported which may be supported by the API.
Users may extend other authentication types to define new authentication schemes.
For example, to define a named authentication scheme called "Passphrase" which inherits from another authentication scheme "Basic", we can write the following in an API Blueprint:
## Authentication Schemes ### Passphrase (Basic)
NOTE: The basic scheme is used as an example in this RFC, and is not defined within this RFC.
Under the authentication scheme heading, you may describe authentication schemes as MSON Type Sections. You may attach a description and define properties as list items.
An authentication scheme may provide a set of properties with default values.
### Passphrase (Basic) Polls API supports the Basic authentication scheme used with pre-existing user accounts.
Inside an authentication scheme, you can define responses that may be given when an authentication scheme is used. For example to indicate the response that is given when the authentication or permission of the user using authentication is incorrect.
### Passphrase (Basic) + Response 403 (application/json) + Attributes + error: `The user does not have access.`
Authenticated keyword can be used to mark a resource group, resource, or
request example to use authentication.
When the authenticated keyword is used on it's own, it will indicate that all
named authentication schemes defined in the
Authentication Schemes section
You may explictly mention a named or base authentication scheme to specify that only that scheme is supported.
+ Authenticated (Basic)
You may overide any properties defined in a base or named scheme.
+ Authenticated (Passphrase) + username: katie
You may also provide failure responses in anonymous authentication schemes.
+ Authenticated (Basic) + Response 403 (application/json) + Attributes + error: `The user does not have access.`
You specify that multiple authentication schemes are supported, using an
+ Authenticated (enum) + (Basic) + username: kyle + password: b2952d03bda09cb5f63b0162fbbee77c + (Passphrase)
If you do not need to override properties, then you may use the shorthand equivalence:
+ Authenticated (enum[Basic, Passphrase])
The authenticated keyword may be used within a resource group to indicate that all child resources, actions and requests inside the resource group support the specified authentication schemes. Any specific resource, action, or request may override the inherited authentication schemes.
Resource groups may be marked as authenticated using the following:
## Group Questions + Authenticated
## Group Questions + Authenticated (Basic) + username: kyle + password: b2952d03bda09cb5f63b0162fbbee77c
+ Authenticated (enum) + (Basic) + username: kyle + password: b2952d03bda09cb5f63b0162fbbee77c + (Named)
Resources, including all the actions and requests within the resource may be
marked as authenticated using the
Authenticated keyword as follows:
## Questions Collection [/questions] + Authenticated
## Questions Collection [/questions] + Authenticated (Basic) + username: kyle + password: b2952d03bda09cb5f63b0162fbbee77c
Actions, including all example requests within the action may be marked as
authenticated using the
Authenticated keyword as follows:
### View list of questions [GET] + Authenticated
### View list of questions [GET] + Authenticated (Basic) + username: kyle + password: b2952d03bda09cb5f63b0162fbbee77c
Request examples can be marked as authenticated by specifing an authenticated keyword inside the request as a sub-item.
+ Request + Authenticated
+ Request + Authenticated (Basic) + username: kyle + password: b2952d03bda09cb5f63b0162fbbee77c
NOTE: You may not define example responses that an authentication scheme may return within an anonymous authentication scheme inside a request example. This limitation is to avoid defining responses within a request to prevent complexity.