Authorization

We will be creating a Authorization system based on Account Types, User Types, User Roles and Capabilities. More information is outlined below:

Authorization System Documentation

Overview

This document outlines the authorization system for the application, detailing the structure and usage of account types, user types, user roles, and capabilities. This system ensures that actions such as creating users, managing user types, and other sensitive operations are restricted to authorized users only.

Base URL

https://{branch}.urapolku.fi/api/authorization

Core Concepts

Account Types

Description: Account types define the high-level categories of users within the system. There are three account types: Admin, Candidate, and Employer/Company.

User Types

Description: User types are tags that signify the department or job function of a user within the system, like Founder, Marketer, Sales, Recruiter, etc.

User Roles

Description: User roles represent the permission level a user has within the system. Predefined roles are Owner, Editor, and Viewer. A role of 'Customized' is assigned when an Owner modifies the default set of capabilities for a user.

Capabilities

Description: Capabilities are specific actions a user is permitted to perform within the application, such as creating or removing users and user types.

Endpoints

List Capabilities

Endpoint: GET /capabilities

Description: Retrieves a list of all capabilities available in the system.

Response:

[
  {
    "id": 1,
    "action": "Create Users"
  },
  {
    "id": 2,
    "action": "Remove Users"
  }
  // ... other capabilities
]

Assign Capability to Role

Endpoint: POST /user-roles/{roleId}/capabilities

Description: Assigns a new capability to a user role.

Payload:

{
  "capabilityId": 3
}

Response: A successful operation will return the updated user role with the new list of capabilities.

Create User Type

Endpoint: POST /user-types

Description: Creates a new user type.

Payload:

{
  "tag": "Recruiter"
}

Response: The created user type object.

User Authorization Check

Endpoint: POST /check

Description: Checks if a user has the capability to perform a certain action.

Payload:

{
  "userId": 123,
  "action": "Create Users"
}

Response: A boolean result indicating if the action is authorized.

Security and Authentication

All requests to the authorization API must include a valid authentication token. The token should be passed as an HTTP Authorization header.

Example:

Authorization: Bearer YOUR_AUTH_TOKEN

Error Handling

The API will return standard HTTP status codes to indicate the success or failure of a request. For example:

• 200 OK - The request was successful.

• 400 Bad Request - The request could not be understood or was missing required parameters.

• 403 Forbidden - The user does not have necessary permissions for the action.

• 404 Not Found - The requested resource was not found.

• 500 Internal Server Error - There was an error on the server and the request could not be completed.

Best Practices

• Always validate the user’s permissions at the server-side before performing any action.

• Use secure, HTTPS connections to protect sensitive data in transit.

• Regularly audit and review your roles and capabilities to ensure they align with your security policies.

Conclusion

This document provides a blueprint for the authorization structure within the application. Proper implementation and adherence to the guidelines set forth in this document will ensure a robust and secure authorization mechanism. As final example I will add a swagger example API as a starting point to go off of:

openapi: 3.0.0
info:
  title: Authorization API
  description: API for managing user authorization based on account types, user types, user roles, and capabilities.
  version: "1.0.0"
servers:
  - url: https://development.urapolku.fi/api/authorization
    description: Development server
paths:
  /capabilities:
    get:
      summary: List all capabilities
      operationId: listCapabilities
      tags:
        - Capabilities
      responses:
        '200':
          description: An array of capabilities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Capability'
  /user-roles/{roleId}/capabilities:
    post:
      summary: Assign capability to a user role
      operationId: assignCapabilityToRole
      tags:
        - User Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignCapabilityRequest'
      responses:
        '200':
          description: Role updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRole'
  /user-types:
    post:
      summary: Create a new user type
      operationId: createUserType
      tags:
        - User Types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserTypeRequest'
      responses:
        '201':
          description: User type created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserType'
  /check:
    post:
      summary: Check user authorization
      operationId: checkUserAuthorization
      tags:
        - Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationCheckRequest'
      responses:
        '200':
          description: Authorization check result
          content:
            application/json:
              schema:
                type: boolean
components:
  schemas:
    Capability:
      type: object
      properties:
        id:
          type: integer
        action:
          type: string
    AssignCapabilityRequest:
      type: object
      required:
        - capabilityId
      properties:
        capabilityId:
          type: integer
    UserRole:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/Capability'
    CreateUserTypeRequest:
      type: object
      required:
        - tag
      properties:
        tag:
          type: string
    UserType:
      type: object
      properties:
        id:
          type: integer
        tag:
          type: string
    AuthorizationCheckRequest:
      type: object
      required:
        - userId
        - action
      properties:
        userId:
          type: integer
        action:
          type: string