* refactor: max-len and printWidth to 100 * chore: ci specific pnpm version * fix: add types peer package literally get rid of types package
9.6 KiB
id | title |
---|---|
plugin-auth | Authentication Plugin |
What's an Authentication Plugin?
Is a sort plugin that allows to handle who access or publish to a specific package. By default the htpasswd
is built-in, but can
easily be replaced by your own.
Getting Started
The authentication plugins are defined in the auth:
section, as follows:
auth:
htpasswd:
file: ./htpasswd
also multiple plugins can be chained:
auth:
htpasswd:
file: ./htpasswd
anotherAuth:
foo: bar
bar: foo
lastPlugin:
foo: bar
bar: foo
If one of the plugin in the chain is able to resolve the request, the next ones will be ignored.
How to the authentication plugin works?
Basically we have to return an object with a single method called authenticate
that will recieve 3 arguments (user, password, callback
).
On each request, authenticate
will be triggered and the plugin should return the credentials, if the authenticate
fails, it will fallback to the $anonymous
role by default.
API
interface IPluginAuth<T> extends IPlugin<T> {
authenticate(user: string, password: string, cb: AuthCallback): void;
adduser?(user: string, password: string, cb: AuthCallback): void;
changePassword?(user: string, password: string, newPassword: string, cb: AuthCallback): void;
allow_publish?(user: RemoteUser, pkg: AllowAccess & PackageAccess, cb: AuthAccessCallback): void;
allow_access?(user: RemoteUser, pkg: AllowAccess & PackageAccess, cb: AuthAccessCallback): void;
allow_unpublish?(
user: RemoteUser,
pkg: AllowAccess & PackageAccess,
cb: AuthAccessCallback
): void;
apiJWTmiddleware?(helpers: any): Function;
}
Only
adduser
,allow_access
,apiJWTmiddleware
,allow_publish
andallow_unpublish
are optional, verdaccio provide a fallback in all those cases.
apiJWTmiddleware
method
Since v4.0.0
apiJWTmiddleware
was introduced on PR#1227 in order to have full control of the token handler, overriding this method will disable login/adduser
support. We recommend don't implement this method unless is totally necessary. See a full example here.
What should I return in each of the methods?
Verdaccio relies on callback
functions at time of this writing. Each method should call the method and what you returns is important, let's review how to do it.
authentication
callback
Once the authentication has been executed there is 2 options to give a response to verdaccio
.
If the authentication fails
If the auth was unsuccessful, return false
as the second argument.
callback(null, false);
If the authentication success
The auth was successful.
groups
is an array of strings where the user is part of.
callback(null, groups);
If the authentication produce an error
The authentication service might fails, and you might want to reflect that in the user response, eg: service is unavailable.
import { getInternalError } from '@verdaccio/commons-api';
callback(getInternalError('something bad message), null);
A failure on login is not the same as service error, if you want to notify user the credentails are wrong, just return
false
instead string of groups. The behaviour mostly depends of you.
adduser
callback
If adduser success
If the service is able to create an user, return true
as the second argument.
callback(null, true);
If adduser fails
Any other action different than success must return an error.
import { getConflict } from '@verdaccio/commons-api';
const err = getConflict('maximum amount of users reached');
callback(err);
changePassword
callback
If the request success
If the service is able to create an user, return true
as the second argument.
const user = serviceUpdatePassword(user, password, newPassword);
callback(null, user);
If the request fails
Any other action different than success must return an error.
import { getNotFound } from '@verdaccio/commons-api';
const err = getNotFound('user not found');
callback(err);
allow_access
, allow_publish
, or allow_unpublish
callback
These methods aims to allow or deny trigger some actions.
If the request success
If the service is able to create an user, return a true
as the second argument.
allow_access(user: RemoteUser, pkg: PackageAccess, cb: Callback): void {
const isAllowed: boolean = checkAction(user, pkg);
callback(null, isAllowed)
}
If the request fails
Any other action different than success must return an error.
import { getNotFound } from '@verdaccio/commons-api';
const err = getForbidden('not allowed to access package');
callback(err);
Generate an authentication plugin
For detailed info check our plugin generator page. Run the yo
command in your terminal and follow the steps.
➜ yo verdaccio-plugin
Just found a `.yo-rc.json` in a parent directory.
Setting the project root at: /Users/user/verdaccio_yo_generator
_-----_ ╭──────────────────────────╮
| | │ Welcome to │
|--(o)--| │ generator-verdaccio-plug │
`---------´ │ in plugin generator! │
( _´U`_ ) ╰──────────────────────────╯
/___A___\ /
| ~ |
__'.___.'__
´ ` |° ´ Y `
? What is the name of your plugin? service-name
? Select Language typescript
? What kind of plugin you want to create? auth
? Please, describe your plugin awesome auth plugin
? GitHub username or organization myusername
? Author's Name Juan Picado
? Author's Email jotadeveloper@gmail.com
? Key your keywords (comma to split) verdaccio,plugin,auth,awesome,verdaccio-plugin
create verdaccio-plugin-authservice-name/package.json
create verdaccio-plugin-authservice-name/.gitignore
create verdaccio-plugin-authservice-name/.npmignore
create verdaccio-plugin-authservice-name/jest.config.js
create verdaccio-plugin-authservice-name/.babelrc
create verdaccio-plugin-authservice-name/.travis.yml
create verdaccio-plugin-authservice-name/README.md
create verdaccio-plugin-authservice-name/.eslintrc
create verdaccio-plugin-authservice-name/.eslintignore
create verdaccio-plugin-authservice-name/src/index.ts
create verdaccio-plugin-authservice-name/index.ts
create verdaccio-plugin-authservice-name/tsconfig.json
create verdaccio-plugin-authservice-name/types/index.ts
create verdaccio-plugin-authservice-name/.editorconfig
I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.
⸨ ░░░░░░░░░░░░░░░░░⸩ ⠋ fetchMetadata: sill pacote range manifest for @babel/plugin-syntax-jsx@^7.7.4 fetc
After the install finish, access to your project scalfold.
➜ cd verdaccio-plugin-service-name
➜ cat package.json
{
"name": "verdaccio-plugin-service-name",
"version": "0.0.1",
"description": "awesome auth plugin",
...
Full implementation ES5 example
function Auth(config, stuff) {
var self = Object.create(Auth.prototype);
self._users = {};
// config for this module
self._config = config;
// verdaccio logger
self._logger = stuff.logger;
// pass verdaccio logger to ldapauth
self._config.client_options.log = stuff.logger;
return self;
}
Auth.prototype.authenticate = function (user, password, callback) {
var LdapClient = new LdapAuth(self._config.client_options);
....
LdapClient.authenticate(user, password, function (err, ldapUser) {
...
var groups;
...
callback(null, groups);
});
};
module.exports = Auth;
And the configuration will looks like:
auth:
htpasswd:
file: ./htpasswd
Where htpasswd
is the sufix of the plugin name. eg: verdaccio-htpasswd
and the rest of the body would be the plugin configuration params.
List Community Authentication Plugins
- verdaccio-bitbucket: Bitbucket authentication plugin for verdaccio.
- verdaccio-bitbucket-server: Bitbucket Server authentication plugin for verdaccio.
- verdaccio-ldap: LDAP auth plugin for verdaccio.
- verdaccio-active-directory: Active Directory authentication plugin for verdaccio
- verdaccio-gitlab: use GitLab Personal Access Token to authenticate
- verdaccio-gitlab-ci: Enable GitLab CI to authenticate against verdaccio.
- verdaccio-htpasswd: Auth based on htpasswd file plugin (built-in) for verdaccio
- verdaccio-github-oauth: Github oauth authentication plugin for verdaccio.
- verdaccio-github-oauth-ui: GitHub OAuth plugin for the verdaccio login button.
- verdaccio-groupnames: Plugin to handle dynamic group associations utilizing
$group
syntax. Works best with the ldap plugin. - verdaccio-sqlite: SQLite Authentication plugin for Verdaccio
Have you developed a new plugin? Add it here !