How opendaylight/aaa works
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.