# Runtime Configuration

This plugin's runtime configuration is expected in section auth of your application's configuration. When complying with suggested filesystem layout for a Hitchy application, there should be a file config/auth.js in your application exposing this section similar to this:

module.exports = {
	auth: {
		...
	},
};

The following parameters are supported there:

# config.auth.prefix

This optional string controls shared prefix of routes set up implicitly for providing basic authentication support. Its default is /api/auth resulting in routes /api/auth/login, /api/auth/current etc.

Implicit routing setup can be disabled on providing boolean false as prefix here.

# config.auth.admin

Provides name and/or password of admin user to create initially when no user with administration privileges has been found in local database. This optional parameter is an object consisting of properties

  • role selecting name of role granting full access to any associated user (default: admin),
  • name selecting name of user to create on start of application if there is no user associated with that role (default: admin) and
  • password providing password of that user to be created in clear text (default: nimda).
module.exports = {
	auth: {
		admin: {
			name: "jane.doe",
			password: "my5ecr3t"
		},
	},
};

TIP

Environment variables HITCHY_ADMIN_NAME, HITCHY_ADMIN_PASSWORD and HITCHY_ADMIN_ROLE can be used to override any configuration provided here to e.g. support container-driven setups.

# config.auth.roles

Lists role names to create on boot if missing in local database. This list is empty by default.

module.exports = {
	auth: {
		roles: [ "guest", "customer", "manager" ],
	},
};

# config.auth.authorizations

This section grants or revokes access on named resources to/from users and/or roles. These authorizations are loaded on application start before reading custom rules from local database.

TIP

Authorizations read from local database may replace authorizations given in runtime configuration.

It is an object-style hierarchy mapping resource names into names of users and/or roles access on selected resource is granted to or revoked from.

module.exports = {
    auth: {
        authorizations: {
            "backup": "@managers",
            "backup.export": "-@noobs",
            "backup.import": "+@admins, -john.doe"
        },
    },
};

Lists of users and roles can be provided as strings using comma for separation as illustrated above. Actual array are supported, too:

module.exports = {
    auth: {
        authorizations: {
            "backup": [ "@managers" ],
            "backup.export": [ "-@noobs" ],
            "backup.import": [ "+@admins", "-john.doe" ],
        },
    },
};

Names of resources can be grouped by shared prefixes:

module.exports = {
    auth: {
        authorizations: {
            backup: {
                people: [ "@managers" ],
                sub: {
                    export: [ "-@noobs" ],
                    import: [ "+@admins", "-john.doe" ],
                },
            }
        },
    },
};

Resource names concatenate path segments separated by period from each other. Common prefixes can be stripped off when nesting authorizations as demonstrated before. Nesting requires provision of users and roles moved into separate property named people.

For improved readability, people list may be replaced with separate lists for users and roles as well as with lists grant and revoke grouping authorizations accordingly:

module.exports = {
    auth: {
        authorizations: {
            backup: {
                grant: [ "@managers" ],
                sub: {
                    export: {
                        revoke: [ "@noobs" ]
                    },
                    import: {
                        users: [ "-john.doe" ],
                        roles: [ "+admins" ]
                    },
                },
            }
        },
    },
};

# config.auth.strategies

This optional object maps unique names of supported authentication strategies into related implementations for use with Passport (opens new window).

const { OAuthStrategy } = require( "passport-oauth" );

module.export = {
    auth: {
        strategies: {
            oauth: new OAuthStrategy( options, localUserSelectorFn ),
        },
    },
};

Any strategy listed here will be picked up on integrating Passport with Hitchy's request routing. When implementing policy-based authenticating requests, name of either strategy must be picked in request's parameter strategy:

module.exports = function() {
    const { login } = this.runtime.policy.Authentication;
    
    return {
        routes: {
            "GET /login/:strategy": login()
        }
    };
};

If request parameter is missing, configured default strategy is used.

Provide a custom local strategy in property local here to prevent built-in local strategy from being used. Omit this configuration to rely on that built-in local strategy for authenticating users against local database, only.

# config.auth.defaultStrategy

This optional string names strategy to use by default. Defaults to local itself.

Any custom strategy named here must be set up properly.