Koas security checks if a request matches the security requirement of an operation. For example, given the following partial OpenAPI document:
Koas security checks if a request matches the security requirement of an operation. For example,
given the following partial OpenAPI document:
``yaml`
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
cookieAuth:
type: apiKey
in: cookie
name: key
oauth2:
type: oauth2
scopes:
email: Read the user’s email address.
profile: Get the user’s profile.
paths:
/me:
get:
security:
- basicAuth: []
cookieAuth: []
- oauth2:
- profile
Koas security will make sure the user is either authenticated using HTTP basic authentication
and a cookie named key, or using OAuth2. The first authentication requirement specified in
the document wins.
`sh`
npm install koa koas-core koas-security
`js
const Koa = require('koa');
const { koas } = require('koas-core');
const { security } = require('koas-security');
const api = require('./api.json');
const app = new Koa();
app.use(
koas(api, [
security({
// User getters
}),
]),
);
`
This middleware sets the users and clients variables in the Koa context. These are mappings ofuser
security requirements to authenticated users and OAuth2 clients respectively. Also andclient are set to match a single user and client. Since most API calls only require a single
authentication method at a time, this can be used for convenience.
Koas security takes a mapping of security requirement keys to user get functions. The signature
depends on the type of authentication.
The function accepts the API key, and should return the user that is authenticated using that key.
| scheme | Description |
| -------- | ---------------------------------------------------------------------------------------------------------- |
| basic | The function accepts the username and password, and should return the user that matches these credentials. |bearer
| | The function accepts the bearer access token, and should return the user that matches these credentials. |
The function accepts the access token, and should return a tuple which consists of the user and the
authenticated OAuth2 client.
When using TypeScript, the Clients and Users interfaces can be augmented to map security scheme
to custom types. For example:
`typescript
declare module 'koas-security' {
interface Users {
basicAuth: User;
cookieAuth: User;
oauth2: User;
}
interface Clients {
oauth2: {
type: 'oauth2';
scopes: ('email' | 'profile')[];
};
}
}
``