https://github.com/sakuraapi/auth-audience
Middleware to support JWT audience role for SakuraApi servers
https://github.com/sakuraapi/auth-audience
api express expressjs javascript jwt nodejs sakuraapi typescript
Last synced: about 1 year ago
JSON representation
Middleware to support JWT audience role for SakuraApi servers
- Host: GitHub
- URL: https://github.com/sakuraapi/auth-audience
- Owner: sakuraapi
- License: bsd-3-clause
- Archived: true
- Created: 2017-07-07T20:02:55.000Z (almost 9 years ago)
- Default Branch: develop
- Last Pushed: 2022-12-22T08:33:07.000Z (over 3 years ago)
- Last Synced: 2025-04-18T21:28:18.832Z (about 1 year ago)
- Topics: api, express, expressjs, javascript, jwt, nodejs, sakuraapi, typescript
- Language: TypeScript
- Size: 208 KB
- Stars: 1
- Watchers: 2
- Forks: 2
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# auth-audience
Middleware to support JWT audience role for SakuraApi servers
Include this as a plugin when instantiating `SakuraApi`. For example:
```
const authAudienceOptions = {
// see: IAuthAudienceOptions for all your options
};
const sapi = new SakuraApi({
// ... other stuff
plugins: [
{
options: authAudienceOptions,
order: 1,
plugin: addAuthAudience
}
]
});
```
# Install
`npm i @sakuraapi/auth-audience`
# Configuration
You'll need to setup your environment (`src/config/environment.ts`, for example) with at least the following:
```
modules.export = {
authentication: {
jwt: {
audience: "audience.somedomain.somewhere",
issuer: "issuer.somedomain.somewhere",
key: "12345678901234567890123456789012"
}
}
};
```
The `audience` is the identifier for the server on which you are implementing this plugin, it should have also been configured in your `auth-native-authority` or `auth-oauth-authority` settings.
The `issuer` is the identifier of the server that's providing the JWT credentials.
The key is the shared secret with the issuer. It's a 32 character key. Remember, if your issuer is supporting multiple audience servers, they don't have to share the same private keys -- in fact, you might not want them to.
This shouldn't need to be stated: don't commit your production private keys to your repo. Instead, inject them during deployment. How you do this is beyond the scope of this readme. This, by the way, is why you don't provide your key via the `authOptions` above. By putting it in your config files, you're able to create a config file for production that takes an environmental variable instead of having the key hard coded.
## domained Audience
There will be times when in a multi tenanted environment when you will want to have a server authenticate on those different domains. Each domain will have the 3-tuple of `audience`-`issuer`-`key`. This auth-audience plugin is able to handle multiple domains (i.e., depending on the domain in the JWT, determining if the audience is supported and if the JWT signs correctly with the secret key for that audience given the domain)
```
jwt: {
domainedAudiences: {
"field": {
audience: "audience1.somedomain.somewhere",
issuer: "issuer1.somedomain.somewhere",
key: "123"
},
"default": {
audience: "audience2.somedomain.somewhere",
issuer: "issuer2.somedomain.somewhere",
key: "456"
}
}
}
```
# Use
`auth-audience` exports `AuthAudience`. This can be used on your `@Routable` api calsses.
Some rules to keep in mind:
1. Authenticators are applied from left to right (in terms of their placement in an array).
1. Each route has an array of authenticators that is a defined as `[...route-level-authenticators, ...class-level-authenticators]`.
1. The first authenticator to succeed stops the iteration through authenticators.
1. If all authenticators fail, the first one to have failed dictates the response.
1. Authenticators can be provided alone, or as an array.
## Example 1:
```
@Routable({
authenticators: [AuthAudience, Anonymous],
baseUrl: 'someapi'
})
class SomeApi {}
```
(`Anonymous` is an authenticator exported by `@sakuraapi/api`).
Example 1 subjects all `someapi` routes to `AuthAudience`. If that fails, then it subjects the request to `Anonymous` (which will never fail). If `AuthAudience` succeeds, a JWT for the user will be available on `res.locals.jwt` (or wherever you put it if you override `onAuthorized` in your options).
## Example 2:
```
@Routable({
authenticators: AuthAudience,
baseUrl: 'someapi'
})
class SomeApi {}
```
Subjects all `someapi` routes to `AuthAudience`, if that fails the user will get a 401 or whatever you set in your options.
## Example 3
```
@Routable({
baseUrl: 'someapi'
})
class SomeApi {}
```
This just lets everything through.
## Example 4
```
@Routable({
baseUrl: 'someapi'
})
class SomeApi {
@Route({
authenticators: Anonymous
method: 'get',
path: 'handler1'
})
handler1(res, req, next) {
next();
}
@Route({
authenticators: AuthAudience
method: 'get',
path: 'handler2'
})
handler2(res, req, next) {
next();
}
}
```
Here, `someapi/handler1` route is Anonymous and will let anyone through. `someapi/handler2` route is subjected to `AuthAudience`.
## Example 5
```
@Routable({
authenticators: AuthAudience,
baseUrl: 'someapi'
})
class SomeApi {
@Route({
authenticators: Anonymous
method: 'get',
path: 'handler1'
})
handler1(res, req, next) {
next();
}
@Route({
method: 'get',
path: 'handler2'
})
handler2(res, req, next) {
next();
}
}
```
In the above example, all routes would be subjected to `AuthAudience`, but `someapi/handler1` would override that and let anyone through as Anonymous.
In this case, route `someapi/handler1` would not have a JWT injected since Anonymous would be executed before `AuthAudience`. Be careful with your ordering.
# Contributions
[](https://cla-assistant.io/sakuraapi/auth-audience)
* Sign the Contributor License Agreement (CLA)
* Fork the project; make your contribution (don't forget to write your unit-tests); do a pull request back to develop (pull updates frequently to not fall too far behind)
* Before heading off to work on something, considering collaborating first by either (1) opening an issue or (2) starting a conversation on gitter or in the Google forum that leads to back to (1)
* All work should be done against an issue (https://github.com/sakuraapi/auth-audience/issues)
* All contributions require unit-tests
* Use the linter (`npm run lint`) to verify you comply with the style guide
* Reset your changes to the docs/ directory before submitting changes - that directory is generated by TypeDoc and we only update it when we're releasing new updates. If you want to update the documentation, change the appropriate comments in the code.
# Bug Reporting
* An ideal bug report will include a PR with a unit-testing demonstrating the bug. TDBR (test driven bug reporting). :)
* Feel free to open an issue before you start working on a PR to prove / demonstrate your bug report, but please close that ticket if you find that your bug was an error on your side
# Community and Conduct
Everyone should be treated with respect. Though candor is encouraged, being mean will not be tolerated.