Enterprise-grade identity, authentication, and authorization plugin for OpenCore Framework
npm install @open-core/identityEnterprise-grade identity, authentication, and authorization plugin for the OpenCore Framework.
- Architecture & Dependency Injection - Learn about constructor injection and DI.
- Authentication Modes - Details on local, credentials, and api auth.
- Principal Modes - Details on roles, db, and api authorization.
- Implementing Contracts - How to build your own IdentityStore or RoleStore.
- Multi-Strategy Authentication: Support for local, credentials, and api strategies.
- Hierarchical RBAC: Rank-based authorization and permission merging.
- Constructor Injection: Services are automatically available in your classes via DI.
- Stateless Architecture: Decoupled persistence via implementable contracts.
The recommended way to use the identity system is through Constructor Injection. The framework handles the lifecycle for you.
``ts
import { Server } from "@open-core/framework";
import { AccountService } from "@open-core/identity";
@Server.Controller()
export class MyController {
// AccountService is automatically injected
constructor(private readonly accounts: AccountService) {}
@Server.OnNet("admin:ban")
async handleBan(player: Server.Player, targetId: string) {
await this.accounts.ban(targetId, { reason: "Policy violation" });
}
}
`
1. Implement your Store (See Contracts):
`ts
import { Identity, IdentityStore } from "@open-core/identity";
class MyStore extends IdentityStore {
/ ... /
}
// Register it before installation
Identity.setIdentityStore(MyStore);
`
2. Install the Plugin:
`ts`
Identity.install({
auth: { mode: "local", autoCreate: true, primaryIdentifier: "license" },
principal: {
mode: "roles",
roles: {
admin: { name: "admin", rank: 100, permissions: ["*"] },
user: { name: "user", rank: 0, permissions: ["chat.use"] },
},
},
});
All strategies are resolved through AuthService. Configure one mode and the framework
will inject the correct provider.
Quick summary:
- local: identifies by license/steam/discord, no form.
- credentials: username/password stored on your server.
- api: delegates to an external HTTP service.
What it is: authenticates using player identifiers (license/steam/discord).
Who it is for: servers that want automatic access without forms.
`ts`
Identity.install({
auth: {
mode: "local",
primaryIdentifier: "license",
autoCreate: true,
},
// ...
});
What it is: login and registration with username/password stored on your server.
Who it is for: servers with custom UI or manual registration.
`ts`
Identity.install({
auth: {
mode: "credentials",
},
// ...
});
What it is: delegates all auth to an external HTTP service.
Who it is for: large networks with a centralized database or SSO.
`ts`
Identity.install({
auth: {
mode: "api",
primaryIdentifier: "license",
api: {
baseUrl: "https://auth.example.com",
authPath: "/auth",
registerPath: "/register",
sessionPath: "/session",
logoutPath: "/logout",
},
},
// ...
});
`ts
import { Server } from "@open-core/framework";
import { AuthService } from "@open-core/identity";
@Server.Controller()
export class AuthController {
constructor(private readonly auth: AuthService) {}
@Server.OnNet("auth:login")
async login(
player: Server.Player,
payload: { username: string; password: string },
) {
return this.auth.authenticate(player, payload);
}
@Server.OnNet("auth:register")
async register(
player: Server.Player,
payload: { username: string; password: string },
) {
return this.auth.register(player, payload);
}
}
`
The library only exports high-level components to keep your IDE suggestions clean:
- Identity: The main namespace for installation and registration.AccountService
- , RoleService: Public services for business logic.IdentityStore
- , RoleStore: Abstract contracts for persistence.IDENTITY_OPTIONS`: Token for advanced DI usage.
-
- All relevant types and interfaces.
MIT