Overview¶Authentication, Authorization and Accounting (AAA) is a term for a framework controlling access to resources, enforcing policies to use those resources and auditing their usage. These processes are the fundamental building blocks for effective network management and security. Show
Authentication provides a way of identifying a user, typically by having the user enter a valid user name and valid password before access is granted. The process of authentication is based on each user having a unique set of criteria for gaining access. The AAA framework compares a user’s authentication credentials with other user credentials stored in a database. If the credentials match, the user is granted access to the network. If the credentials don’t match, authentication fails and access is denied. Authorization is the process of finding out what an authenticated user is allowed to do within the system, which tasks can do, which API can call, etc. The authorization process determines whether the user has the authority to perform such actions. Accounting is the process of logging the activity of an authenticated user, for example, the amount of data a user has sent and/or received during a session, which APIs called, etc. Terms And Definitions¶AAAAuthentication, Authorization and Accounting. TokenA claim of access to a group of resources on the controller. DomainA group of resources, direct or indirect, physical, logical, or virtual, for the purpose of access control. UserA person who either owns or has access to a resource or group of resources on the controller. RoleOpaque representation of a set of permissions, which is merely a unique string as admin or guest. CredentialProof of identity such as user name and password, OTP, biometrics, or others. ClientA service or application that requires access to the controller. ClaimA data set of validated assertions regarding a user, e.g. the role, domain, name, etc. IdPIdentity Provider. Quick Start¶Building¶Get the code: git clone https://git.opendaylight.org/gerrit/aaa Build it: cd aaa && mvn clean install Installing¶AAA is automatically installed upon installation of odl-restconf, but you can install it yourself directly from the Karaf console through the following command: feature:install odl-aaa-shiro Pushing changes¶The following are basic instructions to push your contributions to the project’s GIT repository: git add . git commit -s # make changes, add change id, etc. git commit --amend git push ssh://{username}@git.opendaylight.org:29418/aaa.git HEAD:refs/for/master AAA Framework implementations¶Since Boron release, the OpenDaylight’s AAA services are based on the Apache Shiro Java Security Framework. The main configuration file for AAA is located at “etc/shiro.ini” relative to the OpenDaylight Karaf home directory. Known limitations¶The database (H2) used by ODL AAA Authentication store is not-cluster enabled. When deployed in a clustered environment each node needs to have its AAA user file synchronized using out of band means. How to enable AAA¶AAA is enabled through installing the odl-aaa-shiro feature. The vast majority of OpenDaylight’s northbound APIs (and all RESTCONF APIs) are protected by AAA by default when installing the +odl-restconf+ feature, since the odl-aaa-shiro is automatically installed as part of them. How to disable AAA¶Edit the “etc/opendaylight/datastore/initial/config/aaa-app-config.xml” file and replace the following: with Then, restart the Karaf process. How application developers can leverage AAA to provide servlet security¶Previously the servlet’s web.xml was edited to add the AAAShiroFilter. This has been replaced with programmatic initialization. The Neutron project uses this new style the Neutron blueprint.xml and Neutron WebInitializer.java are helpful references. AAA Realms¶AAA plugin utilizes the Shiro Realms to support pluggable authentication & authorization schemes. There are two parent types of realms:
OpenDaylight contains five implementations:
Note More than one Realm implementation can be specified. Realms are attempted in order until authentication succeeds or all realm sources are exhausted. Edit the securityManager.realms = $tokenAuthRealm property in shiro.ini and add all the realms needed separated by commas. TokenAuthRealm¶How it works¶The TokenAuthRealm is the default Authorization Realm deployed in OpenDaylight. TokenAuthRealm uses a direct authentication mechanism as shown in the following picture: TokenAuthRealm direct authentication mechanism¶ A user presents some credentials (e.g., username/password) directly to the OpenDaylight controller token endpoint /oauth2/token and receives an access token, which then can be used to access protected resources on the controller. How to access the H2 database¶The H2 database provides an optional front-end Web interface, which can be very useful for new users. From the KARAF_HOME directory, you can run the following command to enable the user interface: java -cp ./data/cache/org.eclipse.osgi/bundles/217/1/.cp/h2-1.4.185.jar org.h2.tools.Server -trace -pg -web -webAllowOthers -baseDir `pwd` You can navigate to the following and login via the browser: ODLJndiLdapRealm¶How it works¶LDAP integration is provided in order to externalize identity management. This configuration allows federation with an external LDAP server. The user’s OpenDaylight role parameters are mapped to corresponding LDAP attributes as specified by the groupRolesMap. Thus, an LDAP operator can provision attributes for LDAP users that support different OpenDaylight role structures. ODLJndiLdapRealmAuthNOnly¶How it works¶This is useful for setups where all LDAP users are allowed equal access. KeystoneAuthRealm¶How it works¶This realm authenticates OpenDaylight users against the OpenStack’s Keystone server. This realm uses the Keystone’s Identity API v3 or later. KeystoneAuthRealm authentication/authorization mechanism¶ As can shown on the above diagram, once configured, all the RESTCONF APIs calls will require sending user, password and optionally domain (1). Those credentials are used to authenticate the call against the Keystone server (2) and, if the authentication succeeds, the call will proceed to the MDSAL (3). The credentials must be provisioned in advance within the Keystone Server. The user and password are mandatory, while the domain is optional, in case it is not provided within the REST call, the realm will default to (Default), which is hard-coded. The default domain can be also configured through the shiro.ini file (see the AAA User Guide). The protocol between the Controller and the Keystone Server (2) can be either HTTPS or HTTP. In order to use HTTPS the Keystone Server’s certificate must be exported and imported on the Controller (see the Certificate Management section). Authorization Configuration¶OpenDaylight supports two authorization engines at present, both of which are roughly similar in behavior:
Note The preferred mechanism for configuring AAA Authentication is the MDSAL-Based Dynamic Authorization. Read the following section. Shiro-Based Static Authorization¶OpenDaylight AAA has support for Role Based Access Control (RBAC) based on the Apache Shiro permissions system. Configuration of the authorization system is done off-line; authorization currently cannot be configured after the controller is started. The Authorization provided by this mechanism is aimed towards supporting coarse-grained security policies, the MDSAL-Based mechanism allows for a more robust configuration capabilities. Shiro-based Authorization describes how to configure the Authentication feature in detail. Note The Shiro-Based Authorization that uses the shiro.ini URLs section to define roles requirements is deprecated and discouraged since the changes made to the file are only honored on a controller restart. Shiro-Based Authorization is not cluster-aware, so the changes made on the shiro.ini file have to be replicated on every controller instance belonging to the cluster. The URL patterns are matched relative to the Servlet context leaving room for ambiguity, since many endpoints may match (i.e., “/restconf/modules” and “/auth/modules” would both match a “/modules/**” rule). MDSAL-Based Dynamic Authorization¶The MDSAL-Based Dynamic authorization uses the MDSALDynamicAuthorizationFilter engine to restrict access to particular URL endpoint patterns. Users may define a list of policies that are insertion-ordered. Order matters for that list of policies, since the first matching policy is applied. This choice was made to emulate behavior of the Shiro-Based Authorization mechanism. A policy is a key/value pair, where the key is a resource (i.e., a “URL pattern”) and the value is a list of permissions for the resource. The following describes the various elements of a policy:
This an example on how to limit access to the modules endpoint: HTTP Operation: put URL: /restconf/config/aaa:http-authorization/policies headers: Content-Type: application/json Accept: application/json body: { "aaa:policies": { "aaa:policies": [ { "aaa:resource": "/restconf/modules/**", "aaa:permissions": [ { "aaa:role": "admin", "aaa:actions": [ "get", "post", "put", "patch", "delete" ] } ] } ] } } The above example locks down access to the modules endpoint (and any URLS available past modules) to the “admin” role. Thus, an attempt from the OOB admin user will succeed with 2XX HTTP status code, while an attempt from the OOB user user will fail with HTTP status code 401, as the user user is not granted the “admin” role. Accounting Configuration¶Accounting is handled through the standard slf4j logging mechanisms used by the rest of OpenDaylight. Thus, one can control logging verbosity through manipulating the log levels for individual packages and classes directly through the Karaf console, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations, the default levels exposed do not provide much information about AAA services; this is due to the fact that logging can severely degrade performance. All AAA logging is output to the standard karaf.log file. For debugging purposes (i.e., to enable maximum verbosity), issue the following command: log:set TRACE org.opendaylight.aaa Enable Successful/Unsuccessful Authentication Attempts Logging¶By default, successful/unsuccessful authentication attempts are NOT logged. This is due to the fact that logging can severely decrease REST performance. It is possible to add custom AuthenticationListener(s) to the Shiro-based configuration, allowing different ways to listen for successful/unsuccessful authentication attempts. Custom AuthenticationListener(s) must implement the org.apache.shiro.authc.AuthenticationListener interface. Certificate Management¶The Certificate Management Service is used to manage the keystores and certificates at the OpenDaylight distribution to easily provides the TLS communication. The Certificate Management Service managing two keystores:
The Certificate Management Service stores the keystores (OpenDaylight & Trust) as .jks files under configuration/ssl/ directory. Also the keystores could be stored at the MD-SAL datastore in case OpenDaylight distribution running at cluster environment. When the keystores are stored at MD-SAL, the Certificate Management Service rely on the Encryption-Service to encrypt the keystore data before storing it to MD-SAL and decrypted at runtime. How to use the Certificate Management Service to manage the TLS communication¶The following are the steps to configure the TLS communication within your feature or module:
<dependency> <groupId>org.opendaylight.aaa</groupId> <artifactId>aaa-cert</artifactId> <version>0.5.0-SNAPSHOT</version> </dependency>
import org.opendaylight.aaa.cert.api.ICertificateManager; import org.opendaylight.controller.md.sal.binding.api.DataBroker; public class UseCertManagerExampleProvider { private final DataBroker dataBroker; private final ICertificateManager caManager; public EncSrvExampleProvider(final DataBroker dataBroker, final ICertificateManager caManager) { this.dataBroker = dataBroker; this.caManager = caManager; } public SSLEngine createSSLEngine() { final SSLContext sslContext = caManager.getServerContext(); if (sslContext != null) { final SSLEngine sslEngine = sslContext.createSSLEngine(); sslEngine.setEnabledCipherSuites(caManager.getCipherSuites()); // DO the Implementation return sslEngine; } } public void init() { // TODO } public void close() { // TODO } }
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:odl="http://opendaylight.org/xmlns/blueprint/v1.0.0" odl:use-default-for-reference-types="true"> <reference id="dataBroker" interface="org.opendaylight.controller.md.sal.binding.api.DataBroker" odl:type="default" /> <reference id="aaaCertificateManager" interface="org.opendaylight.aaa.cert.api.ICertificateManager" odl:type="default-certificate-manager" /> <bean id="provider" class="org.opendaylight.UseCertManagerExample.impl.UseCertManagerExampleProvider" init-method="init" destroy-method="close"> <argument ref="dataBroker" /> <argument ref="aaaCertificateManager" /> </bean> </blueprint>
<properties> <aaa.version>0.5.0-SNAPSHOT</aaa.version> </properties> <dependency> <groupId>org.opendaylight.aaa</groupId> <artifactId>features-aaa</artifactId> <version>${aaa.version}</version> <classifier>features</classifier> <type>xml</type> </dependency>
<repository>mvn:org.opendaylight.aaa/features-aaa/{VERSION}/xml/features</repository> The Certificate Manager Service feature can be included inside the implementation bundle feature as shown in the following example: <feature name='odl-UseCertManagerExample' version='${project.version}' description='OpenDaylight :: UseCertManagerExample'> <feature version='${mdsal.version}'>odl-mdsal-broker</feature> <feature version='${aaa.version}'>odl-aaa-cert</feature> <bundle>mvn:org.opendaylight.UseCertManagerExample/UseCertManagerExample-impl/{VERSION}</bundle> </feature>
Encryption Service¶The AAA Encryption Service is used to encrypt the OpenDaylight users’ passwords and TLS communication certificates. This section shows how to use the AAA Encryption Service with an OpenDaylight distribution project to encrypt data.
<dependency> <groupId>org.opendaylight.aaa</groupId> <artifactId>aaa-encrypt-service</artifactId> <version>0.5.0-SNAPSHOT</version> </dependency>
import org.opendaylight.aaa.encrypt.AAAEncryptionService; import org.opendaylight.controller.md.sal.binding.api.DataBroker; public class EncSrvExampleProvider { private final DataBroker dataBroker; private final AAAEncryptionService encryService; public EncSrvExampleProvider(final DataBroker dataBroker, final AAAEncryptionService encryService) { this.dataBroker = dataBroker; this.encryService = encryService; } public void init() { // TODO } public void close() { // TODO } } The AAAEncryptionService can be used to encrypt and decrypt any data based on project’s needs.
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:odl="http://opendaylight.org/xmlns/blueprint/v1.0.0" odl:use-default-for-reference-types="true"> <reference id="dataBroker" interface="org.opendaylight.controller.md.sal.binding.api.DataBroker" odl:type="default" /> <reference id="encryService" interface="org.opendaylight.aaa.encrypt.AAAEncryptionService"/> <bean id="provider" class="org.opendaylight.EncSrvExample.impl.EncSrvExampleProvider" init-method="init" destroy-method="close"> <argument ref="dataBroker" /> <argument ref="encryService" /> </bean> </blueprint>
<dependency> <groupId>org.opendaylight.aaa</groupId> <artifactId>features-aaa</artifactId> <version>${aaa.version}</version> <classifier>features</classifier> <type>xml</type> </dependency> It is also necessary to add the aaa.version in the properties section: <properties> <aaa.version>0.5.0-SNAPSHOT</aaa.version> </properties>
<repository>mvn:org.opendaylight.aaa/features-aaa/{VERSION}/xml/features</repository> The Encryption Service feature can be included inside the implementation bundle feature as shown in the following example: <feature name='odl-EncSrvExample' version='${project.version}' description='OpenDaylight :: EncSrvExample'> <feature version='${mdsal.version}'>odl-mdsal-broker</feature> <feature version='${aaa.version}'>odl-aaa-encryption-service</feature> <feature version='${project.version}'>odl-EncSrvExample-api</feature> <bundle>mvn:org.opendaylight.EncSrvExample/EncSrvExample-impl/{VERSION}</bundle> </feature>
What is the authentication authorization and accounting AAA framework?AAA stands for authentication, authorization, and accounting. AAA is a framework for intelligently controlling access to computer resources, enforcing policies, auditing usage, and providing the information necessary to bill for services.
What authentication authorization and accounting modes are supported by AAA?The device supports RADIUS or HWTACACS authentication, authorization, and accounting, and local authentication and authorization.
Which standard provides authentication authorization and accounting AAA services for network routers and switches?TACACS+ Terminal Access Controller Access-Control System Plus, or TACACS+, is one of the most capable and flexible AAA protocols and offers security benefits over RADIUS — such as packet encryption — and supports a wider range of extensibility.
What is AAA authentication used for?AAA (Authentication, Authorization, Accounting) –
AAA is a standard-based framework used to control who is permitted to use network resources (through authentication), what they are authorized to do (through authorization), and capture the actions performed while accessing the network (through accounting).
|