# opendaylight/aaa architecture

> Architecture diagram of the GitHub repository opendaylight/aaa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opendaylight/aaa
- Repository: https://github.com/opendaylight/aaa

## Overview

##### Project Type & Purpose
- This is a pluggable, modular AAA (Authentication, Authorization, Accounting) framework for the OpenDaylight (ODL) platform.
- It provides Java‐based APIs, OSGi/Blueprint components, web (HTTP/RESTCONF) integration via servlets/filters, CLI tools, and an H2‐backed identity store.

##### Top-Level Architectural Components
a. API Layer (Java interfaces)
- aaa-authn-api: Core AAA API (AuthenticationService, IdMService, Claims, Credentials)
- aaa-encrypt-service/api, aaa-password-service/api, aaa-cert/api, aaa-shiro/api, token-auth-realm modules
b. Service Implementations
- aaa-encrypt-service/impl: Encrypt/decrypt service via OSGi configurator
- aaa-password-service/impl: Password‐hashing service, OSGi config/bootstrap
- aaa-cert/impl: Certificate‐management and MD-SAL provider
- aaa-shiro/impl: Apache Shiro integration (Realms, Filters, WebEnvironment)
- aaa-tokenauthrealm: Default TokenAuthRealm (H2 store)
- aaa-idm-store-h2: H2‐backed local identity store (Users, Roles, Domains, Grants)
- aaa-filterchain: Customizable filter‐chain adapter for Shiro filters
- aaa-jetty-auth-log-filter: Jetty Servlet Filter for authentication logging
c. Web Layer
- web/api: WebContext, WebServer & security adapter interfaces
- web/impl-jetty: Jetty‐based WebServer implementation
- web/impl-osgi: OSGi Whiteboard WebServer implementation
- web/servlet-*: Generic Servlet API & Jersey2 helpers
- web/testutils: HTTP client & test support
d. CLI Tools
- aaa-cli-jar: Fat JAR wrapper for CLI
- aaa-cli: Command implementations for domains, users, roles, certs
e. Runtime & Packaging
- features/: Karaf feature definitions for each module
- karaf/: Karaf‐specific packaging
- parent/ pom.xml: BOM and module aggregation
- artifacts/: POM for publishing artifacts
- docs/: Sphinx/ReadTheDocs documentation
- dependency-check/: Security/dep-update automation

##### Key Relationships & Data Flows
- HTTP Request enters via WebServer (Jetty or OSGi).
- WebContextSecurer installs Shiro’s SecurityManager and FilterChain.
- JettyAuthenticationLogFilter logs authentication attempts.
- Shiro FilterChain invokes:
- AuthenticationListener → AuthenticationService (API) → Realm(s) (TokenAuthRealm, MdsalRealm, LDAPRealm, etc.)
- TokenAuthRealm/MdsalRealm call into IdentityStore (H2 store or external IdP).
- Upon successful authentication, a session cookie is issued.
- Authorization is enforced by MDSALDynamicAuthorizationFilter based on policies stored in MD-SAL.
- Certificate & Encryption services can be invoked by other modules via their OSGi‐exported APIs.
- CLI tools communicate directly with API layer to bootstrap or manage identity data.

##### Architectural Patterns & Principles
- API/Impl separation: Clear Java interface modules vs. OSGi/Blueprint implementation modules.
- OSGi/Blueprint: Each service is published via OSGi service registry; configured via Blueprint XML.
- Plugin/Extension: Shiro Realms and Filters are pluggable; custom adapters via aaa-filterchain.
- Karaf Features: Each logical module has a corresponding feature for granular installation.
- Micro‐modules: Single responsibility for encryption, password hashing, cert management, ID store.

- Configuration points (Blueprint XML, Karaf features).
- External dependencies: LDAP, Keystone, MD-SAL datastore.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients & Tools"
        CLI["CLI (aaa-cli-jar / aaa-cli)"]:::cli
        curl["curl (HTTP Client)"]:::external
    end

    subgraph "Web/API Layer"
        WebServer["WebServer Interface"]:::web
        JettyWebServer["JettyWebServer"]:::web
        WhiteboardWebServer["WhiteboardWebServer"]:::web
        JettyAuthLogFilter["JettyAuthenticationLogFilter"]:::web
        ShiroFilterChain["ShiroFilterChain (AAAFilterChain)"]:::web
    end

    subgraph "Core AAA Services"
        AuthService["AuthenticationService"]:::core
        EncryptionAPI["AAAEncryptionService API"]:::core
        EncryptionImpl["AAAEncryptionServiceImpl"]:::core
        PasswordAPI["PasswordHashService API"]:::core
        PasswordImpl["DefaultPasswordHashService"]:::core
        CertAPI["ICertificateManager API"]:::core
        CertImpl["CertificateManagerService"]:::core
        TokenRealm["TokenAuthRealm"]:::core
    end

    subgraph "Persistence & External IdPs"
        H2Store["IdentityStore (H2)"]:::db
        MDSAL["MD-SAL Datastore"]:::db
        LDAP["LDAP"]:::db
        Keystone["Keystone (External IdP)"]:::db
    end

    curl --> WebServer
    WebServer --> JettyAuthLogFilter
    JettyAuthLogFilter --> ShiroFilterChain
    ShiroFilterChain --> AuthService
    AuthService --> TokenRealm
    TokenRealm --> H2Store
    AuthService --> LDAP
    AuthService --> Keystone
    AuthService --> MDSAL

    EncryptionImpl --> MDSAL
    PasswordImpl --> MDSAL
    CertImpl --> MDSAL

    CLI --> AuthService
    CLI --> H2Store

    click AuthService "https://github.com/opendaylight/aaa/tree/master/aaa-authn-api"
    click EncryptionAPI "https://github.com/opendaylight/aaa/blob/master/aaa-encrypt-service/api/src/main/java/org/opendaylight/aaa/encrypt/AAAEncryptionService.java"
    click EncryptionImpl "https://github.com/opendaylight/aaa/blob/master/aaa-encrypt-service/impl/src/main/java/org/opendaylight/aaa/encrypt/impl/AAAEncryptionServiceImpl.java"
    click PasswordAPI "https://github.com/opendaylight/aaa/blob/master/aaa-password-service/api/src/main/java/org/opendaylight/aaa/api/password/service/PasswordHashService.java"
    click PasswordImpl "https://github.com/opendaylight/aaa/blob/master/aaa-password-service/impl/src/main/java/org/opendaylight/aaa/impl/password/service/DefaultPasswordHashService.java"
    click CertAPI "https://github.com/opendaylight/aaa/blob/master/aaa-cert/src/main/java/org/opendaylight/aaa/cert/api/ICertificateManager.java"
    click CertImpl "https://github.com/opendaylight/aaa/blob/master/aaa-cert/src/main/java/org/opendaylight/aaa/cert/impl/CertificateManagerService.java"
    click ShiroFilterChain "https://github.com/opendaylight/aaa/blob/master/aaa-filterchain/src/main/java/org/opendaylight/aaa/filterchain/filters/AAAFilterChain.java"
    click JettyAuthLogFilter "https://github.com/opendaylight/aaa/blob/master/aaa-jetty-auth-log-filter/src/main/java/org/opendaylight/aaa/filter/JettyAuthenticationLogFilter.java"
    click WebServer "https://github.com/opendaylight/aaa/blob/master/web/api/src/main/java/org/opendaylight/aaa/web/WebServer.java"
    click JettyWebServer "https://github.com/opendaylight/aaa/blob/master/web/impl-jetty/src/main/java/org/opendaylight/aaa/web/jetty/JettyWebServer.java"
    click WhiteboardWebServer "https://github.com/opendaylight/aaa/blob/master/web/impl-osgi/src/main/java/org/opendaylight/aaa/web/osgi/WhiteboardWebServer.java"
    click TokenRealm "https://github.com/opendaylight/aaa/blob/master/aaa-shiro/impl/src/main/java/org/opendaylight/aaa/shiro/realm/TokenAuthRealm.java"
    click CLI "https://github.com/opendaylight/aaa/blob/master/aaa-cli-jar/src/main/java/org/opendaylight/aaa/cli/jar/Main.java"
    click H2Store "https://github.com/opendaylight/aaa/blob/master/aaa-idm-store-h2/src/main/java/org/opendaylight/aaa/datastore/h2/H2Store.java"

    classDef web fill:#cfe2f3,stroke:#0366d6,color:#0366d6;
    classDef core fill:#d1e7dd,stroke:#1e7e34,color:#1e7e34;
    classDef db fill:#fff3cd,stroke:#d39e00,color:#d39e00;
    classDef cli fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8f9fa,stroke:#adb5bd,color:#212529;
```
