adapt-authoring-auth 1.0.1 → 1.0.2

package/.github/workflows/new.yml

@@ -1,19 +1,15 @@
-name: Add to main project
+# Calls the org-level reusable workflow to add PRs to the TODO Board
+
+name: Add PR to Project
 
 on:
-  issues:
-    types:
-      - opened
   pull_request:
     types:
       - opened
+      - reopened
 
 jobs:
   add-to-project:
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}
+    uses: adapt-security/.github/.github/workflows/new.yml@main
+    secrets:
+      PROJECTS_SECRET: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -1,5 +1,9 @@
 {
   "documentation": {
-    "enable": true
+    "enable": true,
+    "manualPages": {
+      "auth-permissions.md": "basics",
+      "creating-auth-plugins.md": "development"
+    }
   }
 }

package/docs/auth-permissions.md

@@ -0,0 +1,280 @@
+# Authentication and permissions
+
+The Adapt authoring tool uses a token-based authentication system with role-based access control (RBAC) provided through permissions scopes. This guide covers how authentication works, how to configure authorisation, and how to manage permissions.
+
+## Authentication
+
+Authentication verifies user identity. The system supports multiple authentication methods through plugins (local username/password, OAuth providers like GitHub or Okta, etc.).
+
+### How authentication works
+
+1. User submits credentials to an auth plugin endpoint (e.g., `POST /api/auth/local`)
+2. The auth plugin validates the credentials
+3. On success, a JWT ([JSON Web Token](https://www.jwt.io/introduction#what-is-json-web-token)) is generated and returned to the client
+4. The client includes the token in subsequent requests via the `Authorization` header
+5. The server validates the token and checks permissions for each request
+
+### Request auth data
+
+Authenticated requests have auth data attached to `req.auth`:
+
+```javascript
+async myHandler (req, res, next) {
+  const {
+    user,           // The authenticated user document
+    scopes,         // Array of permission scopes
+    isSuper,        // Whether user has super privileges
+    token,          // The decoded JWT
+    userSchemaName  // Schema used for the user
+  } = req.auth
+}
+```
+
+### Making authenticated requests
+
+Include the JWT in the `Authorization` header:
+
+```
+Authorization: Bearer <token>
+```
+
+### Checking authentication status
+
+Retrieve the current user's details and permissions if authenticated (error if not):
+
+```
+GET /api/auth/check
+```
+
+### Generating tokens
+
+For API integrations etc. tokens can be generated manually with custom lifespans:
+
+> Requires the `generatetoken:auth` scope
+
+```
+POST /api/auth/generatetoken
+Content-Type: application/json
+
+{
+  "lifespan": "30d"
+}
+```
+
+### Revoking tokens
+
+To log out or invalidate sessions and revoke the current user's token:
+
+```
+POST /api/auth/disavow
+```
+
+### Disabling authentication
+
+For development only, authentication can be disabled.
+
+> **Warning:** Auth cannot be disabled in production environments. The system enforces this automatically.
+
+```javascript
+module.exports = {
+  'adapt-authoring-auth': {
+    isEnabled: false
+  }
+}
+```
+
+### Authentication errors
+
+| Error | Description |
+| ----- | ----------- |
+| `UNAUTHENTICATED` | No valid authentication provided |
+| `AUTH_TOKEN_EXPIRED` | Token has expired |
+| `AUTH_TOKEN_INVALID` | Token is malformed or tampered |
+| `ACCOUNT_DISABLED` | User account is disabled |
+| `ACCOUNT_LOCKED_TEMP` | Account temporarily locked (too many failed attempts) |
+| `ACCOUNT_LOCKED_PERM` | Account permanently locked |
+| `INVALID_LOGIN_DETAILS` | Wrong username or password |
+
+## Authorisation
+
+Authorisation determines what authenticated users are allowed to do. The system uses roles to group permissions together.
+
+### Roles
+
+Roles are collections of scopes (permissions) assigned to users. The system comes with three default roles:
+
+**authuser** — Basic authenticated user:
+- `clear:session`
+- `read:config`
+- `read:lang`
+- `read:me`
+- `write:me`
+- `disavow:auth`
+  
+**contentcreator** _extends authuser_ — Can create and manage content:
+- `export:adapt`
+- `import:adapt`
+- `preview:adapt`
+- `publish:adapt`
+- `read:assets`
+- `write:assets`
+- `read:content`
+- `write:content`
+- `read:contentplugins`
+- `read:roles`
+- `read:schema`
+- `read:tags`
+- `write:tags`
+- `read:users`
+  
+**superuser** — Full access to everything:
+- `*:*`
+  
+### Role inheritance
+
+Roles can extend other roles using the `extends` property. The child role inherits all scopes from its parent.
+
+```json
+{
+  "shortName": "contentcreator",
+  "extends": "authuser",
+  "scopes": ["read:content", "write:content"]
+}
+```
+
+In this example, `contentcreator` has all scopes from `authuser` plus `read:content` and `write:content`.
+
+### Defining custom roles
+
+Add roles via configuration in your config file:
+
+```javascript
+module.exports = {
+  'adapt-authoring-roles': {
+    roleDefinitions: [
+      {
+        shortName: 'reviewer',
+        displayName: 'Content Reviewer',
+        extends: 'authuser',
+        scopes: [
+          'read:content',
+          'read:assets',
+          'preview:adapt'
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Default roles for new users
+
+Configure which roles are assigned to new users:
+
+```javascript
+module.exports = {
+  'adapt-authoring-roles': {
+    defaultRoles: ['authuser'],
+    defaultRolesForAuthTypes: {
+      local: ['contentcreator']
+    }
+  }
+}
+```
+
+### Authorisation errors
+
+| Error | Description |
+| ----- | ----------- |
+| `UNAUTHORISED` | User lacks required permissions |
+
+## Permissions
+
+Once a user has been authorised and authenticated, the final permissions checks are performed. These are to ensure that the user has access to the specific resources they are requesting.
+Permissions control access to specific actions and resources. They are enforced in two ways:
+- Using scopes on routes
+- Specific manual checks on individual resource items
+
+### Scopes
+
+Scopes are strings in the format `action:resource` that define what a user can do in a plain human-readable way. You will find the most common actions are `read` and `write`, but there are various cases where a more specific and descriptive action is called for.
+
+Some examples are: `read:content`, `delete:assets` and `preview:adapt`.
+
+### Securing routes
+
+**Using AbstractApiModule:**
+
+When extending `AbstractApiModule`, define permissions in your route configuration:
+
+```javascript
+async setValues () {
+  this.root = 'myresource'
+  this.schemaName = 'myresource'
+  this.collectionName = 'myresources'
+  
+  this.routes = [
+    {
+      route: '/',
+      handlers: {
+        get: this.getHandler.bind(this),
+        post: this.postHandler.bind(this)
+      },
+      permissions: {
+        get: ['read:myresource'],
+        post: ['write:myresource']
+      }
+    }
+  ]
+}
+```
+
+**Using secureRoute directly:**
+
+For custom routes outside `AbstractApiModule`:
+
+```javascript
+async init () {
+  const auth = await this.app.waitForModule('auth')
+  
+  auth.secureRoute('/api/custom/action', 'post', ['custom:action'])
+}
+```
+
+**Unsecuring routes:**
+
+Some routes need to be publicly accessible (e.g., login endpoints):
+
+> **Warning:** Unsecured routes are accessible without authentication. Use sparingly.
+
+```javascript
+async init () {
+  const auth = await this.app.waitForModule('auth')
+  
+  auth.unsecureRoute('/api/public/data', 'get')
+}
+```
+
+### Access control hooks
+
+Although a user may have access to a resource, there may be occasions when more fine-grained control is necessary to filter out specific resources. In this case, you can use hooks to implement custom access control logic.
+
+The `AbstractApiModule#accessCheckHook` is called for each document returned by queries, allowing fine-grained access control:
+
+```javascript
+async init () {
+  await super.init()
+  const content = await this.app.waitForModule('content')
+  
+  // Check if user owns the document
+  content.accessCheckHook.tap((req, doc) => {
+    if (doc.createdBy.toString() !== req.auth.user._id.toString()) {
+      throw this.app.errors.UNAUTHORISED
+    }
+  })
+}
+```
+
+## Further reading
+
+- [Creating auth plugins](creating-auth-plugins.md) — How to implement custom authentication methods

package/docs/creating-auth-plugins.md

@@ -0,0 +1,192 @@
+# Creating auth plugins
+
+> Preliminary reading: [Authentication and permissions](auth-permissions.md) — Overview of the auth system
+---
+
+Auth plugins allows for implementations of different authentication methods.
+
+## Basic structure
+
+Extend `AbstractAuthModule` and implement the required methods:
+
+```javascript
+import { AbstractAuthModule } from 'adapt-authoring-auth'
+
+class MyAuthModule extends AbstractAuthModule {
+  async setValues () {
+    this.type = 'myauth'           // Unique identifier
+    this.userSchema = 'myauthuser' // Optional custom user schema
+  }
+  
+  async authenticate (user, req, res) {
+    // Verify credentials - throw on failure
+  }
+}
+```
+
+## Reference
+
+### Required values
+
+| Property | Description |
+| -------- | ----------- |
+| `this.type` | Unique identifier for the auth type (e.g., `'local'`, `'github'`) |
+
+### Optional values
+
+| Property | Default | Description |
+| -------- | ------- | ----------- |
+| `this.userSchema` | `'user'` | Schema name for validating users of this auth type - allows custom data to be added to users |
+| `this.routes` | `[]` | Additional routes for the auth plugin |
+
+### Inherited methods
+
+| Method | Description |
+| ------ | ----------- |
+| `register(data)` | Register a new user with this auth type |
+| `setUserEnabled(user, isEnabled)` | Enable or disable a user account |
+| `disavowUser(query)` | Revoke user tokens |
+| `secureRoute(route, method, scopes)` | Secure a route |
+| `unsecureRoute(route, method)` | Remove auth from a route |
+| `comparePassword(plain, hashed)` | Compare a plain password against a hash |
+
+### Hooks
+
+| Hook | Description |
+| ---- | ----------- |
+| `registerHook` | Invoked when a new user registers (mutable) |
+
+## Worked Example: GitHub OAuth
+
+We will work through an example authentication plugin using GitHub OAuth.
+
+For OAuth providers (GitHub, Okta, Google, etc.), the flow redirects users to the provider rather than validating credentials directly.
+
+### Key steps for OAuth plugins
+
+1. Extend `AbstractAuthModule` and set `this.type` to a unique identifier
+2. Add config & user schemas (if necessary)
+3. Use Passport.js with the appropriate strategy for your provider
+4. The OAuth callback should generate a token and store it in the session
+5. Mark OAuth routes as unsecured since users aren't authenticated yet
+6. Handle user registration if the OAuth profile doesn't match an existing user
+7. Add UI code for your plugin, and register it with the UI module (see [this page](ui-extensions))
+
+**Below code is for illustrative purposes only, and is not guaranteed to work without modifications**
+
+### Creating Auth Module
+
+```javascript
+import { AbstractAuthModule, AuthToken } from 'adapt-authoring-auth'
+import passport from 'passport'
+import { Strategy as GitHubStrategy } from 'passport-github2'
+
+class GitHubAuthModule extends AbstractAuthModule {
+  async setValues () {
+    this.type = 'github'
+    this.userSchema = 'githubauthuser'
+  }
+  
+  async init () {
+    await super.init()
+    const [server, users] = await this.app.waitForModule('server', 'users', 'sessions')
+    
+    this.router.expressRouter.use(passport.initialize())
+    this.router.expressRouter.use(passport.session())
+    
+    passport.use(new GitHubStrategy({
+      clientID: this.getConfig('clientID'),
+      clientSecret: this.getConfig('clientSecret'),
+      callbackURL: `//${server.getConfig('host')}:${server.getConfig('port')}${this.router.path}/callback`
+    }, async (accessToken, refreshToken, profile, done) => {
+      try {
+        // Find user by any of their GitHub emails
+        let [user] = await users.find({ 
+          $or: profile.emails.map(({ value }) => ({ email: value })) 
+        })
+        
+        if (!user && this.getConfig('registerUserWithRoles').length) {
+          user = await this.registerUser(profile)
+        }
+        
+        return done(null, user || false)
+      } catch (e) {
+        return done(e)
+      }
+    }))
+    
+    passport.serializeUser((user, done) => done(null, user))
+    passport.deserializeUser((obj, done) => done(null, obj))
+    
+    // OAuth flow: redirect to provider, then handle callback
+    this.router.addRoute({
+      route: '/',
+      handlers: { get: passport.authenticate('github', { scope: ['user:email'] }) }
+    }, {
+      route: '/callback',
+      handlers: { get: passport.authenticate('github', { failureRedirect: '/' }) }
+    }, {
+      route: '/callback',
+      handlers: { get: this.onAuthenticated.bind(this) }
+    })
+    
+    this.unsecureRoute('/', 'get')
+    this.unsecureRoute('/callback', 'get')
+  }
+  
+  async registerUser (profile) {
+    const email = profile.emails[0].value
+    const nameParts = profile.displayName.split(' ')
+    const roles = await this.app.waitForModule('roles')
+    const roleNames = this.getConfig('registerUserWithRoles')
+    const matchedRoles = await roles.find({ 
+      $or: roleNames.map(shortName => ({ shortName })) 
+    })
+    
+    return this.register({
+      email,
+      firstName: nameParts[0] || profile.displayName,
+      lastName: nameParts[1] || '',
+      roles: matchedRoles.map(r => r._id.toString())
+    })
+  }
+  
+  async onAuthenticated (req, res, next) {
+    try {
+      req.session.token = await AuthToken.generate(this.type, req.user)
+      res.redirect('/')
+    } catch (e) {
+      return next(e)
+    }
+  }
+}
+```
+
+### Adding UI login support
+
+For OAuth plugins, you may need to override the default login behaviour to redirect to the provider instead of showing a login form.
+
+Create a UI plugin:
+
+```javascript
+// plugins/myauth/index.js
+define(function (require) {
+  const Origin = require('core/origin')
+  
+  Origin.on('router:handleLogin', function () {
+    // Redirect to OAuth provider
+    window.location = window.origin + '/api/auth/myauth'
+  })
+})
+```
+
+Register the UI plugin in your module's `init` method:
+
+```javascript
+async init () {
+  await super.init()
+  
+  const ui = await this.app.waitForModule('ui')
+  ui.addUiPlugin(path.resolve(this.rootDir, 'plugins'))
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-auth",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Authentication + authorisation module for the Adapt authoring tool",
   "homepage": "https://github.com/adaptlearning/adapt-authoring-auth",
   "license": "GPL-3.0",
@@ -11,7 +11,7 @@
     "adapt-authoring-roles": "github:adapt-security/adapt-authoring-roles",
     "adapt-authoring-users": "github:adapt-security/adapt-authoring-users",
     "express-session": "1.18.2",
-    "jsonwebtoken": "9.0.2",
+    "jsonwebtoken": "9.0.3",
     "path-to-regexp": "^8.0.0"
   },
   "peerDependencies": {

package/.github/workflows/labelled_prs.yml

@@ -1,16 +0,0 @@
-name: Add labelled PRs to project
-
-on:
-  pull_request:
-    types: [ labeled ]
-
-jobs:
-  add-to-project:
-    if: ${{ github.event.label.name == 'dependencies' }}
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}