# altioobv/altioo-oauth-server architecture

> Architecture diagram of the GitHub repository altioobv/altioo-oauth-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/altioobv/altioo-oauth-server
- Repository: https://github.com/altioobv/altioo-oauth-server

## Overview

Altioo OAuth Server adds OAuth 2.1 authorization to iTop: a client discovers or is configured with the server, registers when permitted, sends a person through iTop login and consent, then exchanges the authorization code for tokens backed by an iTop personal token. Refresh and revocation maintain the connection, which the person can inspect or end in iTop. Major areas include discovery, REST/MCP resources, registration, authorization, token/grant lifecycle, and account interfaces. Some controller and service internals are unsampled; uncertain links are omitted.

Main entry points: [`src/Controller/AuthorizationController.php`](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/AuthorizationController.php) (Authorization consent), [`src/Controller/Router.php`](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/Router.php) (Route dispatcher), [`src/Controller/TokenController.php`](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/TokenController.php) (Token endpoint), [`src/Controller/RegistrationController.php`](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/RegistrationController.php) (Client registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entry"]
  node_entrypoint["Module entry<br/>[index.php]"]
  node_router["Route dispatcher<br/>[Router.php]"]
  node_http["HTTP responses<br/>[Http.php]"]
end

subgraph group_protocol["OAuth protocol"]
  node_metadata["Discovery metadata"]
  node_registration["Client registration"]
  node_authorization["Authorization consent"]
  node_token_endpoint["Token endpoint"]
end

subgraph group_lifecycle["Connection lifecycle"]
  node_registrations["Registration records<br/>[Registrations.php]"]
  node_accounts["Account access checks<br/>[Accounts.php]"]
  node_grants["Grant lifecycle<br/>[Grants.php]"]
  node_personal_tokens["iTop personal tokens<br/>[PersonalTokens.php]"]
  node_cleanup["Grant cleanup<br/>[CleanUpProcess.php]"]
end

subgraph group_account["Account interfaces"]
  node_connections["My Account connections"]
  node_portal_connections["Portal connections"]
  node_connections_endpoint["Connection actions"]
end

subgraph group_policy["Resource policy"]
  node_config["Server configuration<br/>[Config.php]"]
  node_resource_policy["Resource and scope policy"]
  node_scope_rules["Scope rules<br/>[ScopePolicy.php]"]
  node_redirect_policy["Redirect URI policy"]
end

node_client(("OAuth client"))
node_itop_user(("iTop user"))
node_mcp["altioo-mcp resource"]
node_rest["iTop REST API"]

node_client -->|"calls endpoints"| node_entrypoint
node_entrypoint -->|"dispatches to"| node_router
node_router -->|"routes discovery"| node_metadata
node_router -->|"routes registration"| node_registration
node_router -->|"routes authorization"| node_authorization
node_router -->|"routes tokens"| node_token_endpoint
node_router -->|"routes disconnect"| node_connections_endpoint
node_router -->|"formats errors"| node_http
node_metadata -->|"reads settings"| node_config
node_metadata -->|"describes resource"| node_resource_policy
node_registration -->|"checks callbacks"| node_redirect_policy
node_registration -->|"limits registrations"| node_registrations
node_registration -->|"reads settings"| node_config
node_registration -->|"returns client details"| node_http
node_authorization -->|"authenticates person"| node_itop_user
node_authorization -->|"checks callback"| node_redirect_policy
node_authorization -->|"selects resource"| node_resource_policy
node_authorization -->|"checks account"| node_accounts
node_authorization -->|"reads settings"| node_config
node_authorization -->|"redirects with code"| node_client
node_token_endpoint -->|"validates client"| node_authorization
node_token_endpoint -->|"checks account"| node_accounts
node_token_endpoint -->|"ends reused grant"| node_grants
node_token_endpoint -->|"issues and rotates"| node_personal_tokens
node_token_endpoint -->|"reads settings"| node_config
node_token_endpoint -->|"returns token response"| node_http
node_config -->|"configures scopes"| node_scope_rules
node_grants -->|"deletes owned token"| node_personal_tokens
node_cleanup -->|"ends expired grants"| node_grants
node_cleanup -->|"cleans tokens"| node_personal_tokens
node_connections -->|"lists active grants"| node_grants
node_connections -->|"describes scopes"| node_authorization
node_portal_connections -->|"reuses connection view"| node_connections
node_connections_endpoint -->|"withdraws grant"| node_grants
node_itop_user -->|"views connections"| node_connections
node_itop_user -->|"ends connection"| node_connections_endpoint
node_mcp -->|"accepts issued tokens"| node_personal_tokens
node_rest -->|"accepts issued tokens"| node_personal_tokens
node_client -->|"requests access"| node_mcp
node_client -->|"requests access"| node_rest

click node_entrypoint "https://github.com/altioobv/altioo-oauth-server/blob/main/index.php"
click node_router "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/Router.php"
click node_http "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Http.php"
click node_metadata "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/MetadataController.php"
click node_registration "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/RegistrationController.php"
click node_authorization "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/AuthorizationController.php"
click node_token_endpoint "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/TokenController.php"
click node_config "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Config.php"
click node_resource_policy "https://github.com/altioobv/altioo-oauth-server/blob/main/src/ProtectedResource.php"
click node_scope_rules "https://github.com/altioobv/altioo-oauth-server/blob/main/src/ScopePolicy.php"
click node_redirect_policy "https://github.com/altioobv/altioo-oauth-server/blob/main/src/RedirectUriPolicy.php"
click node_registrations "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/Registrations.php"
click node_accounts "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/Accounts.php"
click node_grants "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/Grants.php"
click node_personal_tokens "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/PersonalTokens.php"
click node_cleanup "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/CleanUpProcess.php"
click node_connections "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Hook/MyAccountConnections.php"
click node_portal_connections "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Hook/PortalConnections.php"
click node_connections_endpoint "https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/ConnectionsController.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_router,node_http,node_client,node_itop_user toneBlue
class node_metadata,node_registration,node_authorization,node_token_endpoint toneAmber
class node_registrations,node_accounts,node_grants,node_personal_tokens,node_cleanup,node_rest toneMint
class node_connections,node_portal_connections,node_connections_endpoint toneRose
class node_config,node_resource_policy,node_scope_rules,node_redirect_policy,node_mcp toneIndigo
```

## Components

### HTTP entry

- [Module entry](https://github.com/altioobv/altioo-oauth-server/blob/main/index.php): `index.php`
- [Route dispatcher](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/Router.php): `src/Controller/Router.php`
- [HTTP responses](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Http.php): `src/Http.php`

### OAuth protocol

- [Discovery metadata](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/MetadataController.php): `src/Controller/MetadataController.php`
- [Client registration](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/RegistrationController.php): `src/Controller/RegistrationController.php`
- [Authorization consent](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/AuthorizationController.php): `src/Controller/AuthorizationController.php`
- [Token endpoint](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/TokenController.php): `src/Controller/TokenController.php`

### Connection lifecycle

- [Registration records](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/Registrations.php): `src/Service/Registrations.php`
- [Account access checks](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/Accounts.php): `src/Service/Accounts.php`
- [Grant lifecycle](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/Grants.php): `src/Service/Grants.php`
- [iTop personal tokens](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/PersonalTokens.php): `src/Service/PersonalTokens.php`
- [Grant cleanup](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Service/CleanUpProcess.php): `src/Service/CleanUpProcess.php`

### Account interfaces

- [My Account connections](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Hook/MyAccountConnections.php): `src/Hook/MyAccountConnections.php`
- [Portal connections](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Hook/PortalConnections.php): `src/Hook/PortalConnections.php`
- [Connection actions](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Controller/ConnectionsController.php): `src/Controller/ConnectionsController.php`

### Resource policy

- [Server configuration](https://github.com/altioobv/altioo-oauth-server/blob/main/src/Config.php): `src/Config.php`
- [Resource and scope policy](https://github.com/altioobv/altioo-oauth-server/blob/main/src/ProtectedResource.php): `src/ProtectedResource.php`
- [Scope rules](https://github.com/altioobv/altioo-oauth-server/blob/main/src/ScopePolicy.php): `src/ScopePolicy.php`
- [Redirect URI policy](https://github.com/altioobv/altioo-oauth-server/blob/main/src/RedirectUriPolicy.php): `src/RedirectUriPolicy.php`

### Other components

- **OAuth client**
- **iTop user**
- **altioo-mcp resource**
- **iTop REST API**

## Connections

- OAuth client → Module entry: calls endpoints (evidence: `README.md`)
- Module entry → Route dispatcher: dispatches to (evidence: `index.php`)
- Route dispatcher → Discovery metadata: routes discovery (evidence: `src/Controller/Router.php`)
- Route dispatcher → Client registration: routes registration (evidence: `src/Controller/Router.php`)
- Route dispatcher → Authorization consent: routes authorization (evidence: `src/Controller/Router.php`)
- Route dispatcher → Token endpoint: routes tokens (evidence: `src/Controller/Router.php`)
- Route dispatcher → Connection actions: routes disconnect (evidence: `src/Controller/Router.php`)
- Route dispatcher → HTTP responses: formats errors (evidence: `src/Controller/Router.php`)
- Discovery metadata → Server configuration: reads settings (evidence: `src/Controller/MetadataController.php`)
- Discovery metadata → Resource and scope policy: describes resource (evidence: `src/Controller/MetadataController.php`)
- Client registration → Redirect URI policy: checks callbacks (evidence: `src/Controller/RegistrationController.php`)
- Client registration → Registration records: limits registrations (evidence: `src/Controller/RegistrationController.php`)
- Client registration → Server configuration: reads settings (evidence: `src/Controller/RegistrationController.php`)
- Client registration → HTTP responses: returns client details (evidence: `src/Controller/RegistrationController.php`)
- Authorization consent → iTop user: authenticates person (evidence: `src/Controller/AuthorizationController.php`)
- Authorization consent → Redirect URI policy: checks callback (evidence: `src/Controller/AuthorizationController.php`)
- Authorization consent → Resource and scope policy: selects resource (evidence: `src/Controller/AuthorizationController.php`)
- Authorization consent → Account access checks: checks account (evidence: `src/Controller/AuthorizationController.php`)
- Authorization consent → Server configuration: reads settings (evidence: `src/Controller/AuthorizationController.php`)
- Authorization consent → OAuth client: redirects with code (evidence: `README.md`)
- Token endpoint → Authorization consent: validates client (evidence: `src/Controller/TokenController.php`)
- Token endpoint → Account access checks: checks account (evidence: `src/Controller/TokenController.php`)
- Token endpoint → Grant lifecycle: ends reused grant (evidence: `src/Controller/TokenController.php`)
- Token endpoint → iTop personal tokens: issues and rotates (evidence: `src/Controller/TokenController.php`)
- Token endpoint → Server configuration: reads settings (evidence: `src/Controller/TokenController.php`)
- Token endpoint → HTTP responses: returns token response (evidence: `src/Controller/TokenController.php`)
- Server configuration → Scope rules: configures scopes (evidence: `src/Config.php`)
- Grant lifecycle → iTop personal tokens: deletes owned token (evidence: `src/Service/Grants.php`)
- Grant cleanup → Grant lifecycle: ends expired grants (evidence: `src/Service/CleanUpProcess.php`)
- Grant cleanup → iTop personal tokens: cleans tokens (evidence: `src/Service/CleanUpProcess.php`)
- My Account connections → Grant lifecycle: lists active grants (evidence: `src/Hook/MyAccountConnections.php`)
- My Account connections → Authorization consent: describes scopes (evidence: `src/Hook/MyAccountConnections.php`)
- Portal connections → My Account connections: reuses connection view (evidence: `src/Hook/PortalConnections.php`)
- Connection actions → Grant lifecycle: withdraws grant (evidence: `src/Controller/ConnectionsController.php`)
- iTop user → My Account connections: views connections (evidence: `README.md`)
- iTop user → Connection actions: ends connection (evidence: `README.md`)
- altioo-mcp resource → iTop personal tokens: accepts issued tokens (evidence: `README.md`)
- iTop REST API → iTop personal tokens: accepts issued tokens (evidence: `README.md`)
- OAuth client → altioo-mcp resource: requests access (evidence: `README.md`)
- OAuth client → iTop REST API: requests access (evidence: `README.md`)
