User Access, Authentication, and Accounting

This chapter contains the following sections:

Access rights workflow dependencies

Access rights workflow dependencies are coordination requirements that occur when Cisco Application Centric Infrastructure (ACI) RBAC rules restrict administrator access to specific fabric domains needed for configuration tasks.

RBAC access scenarios

The ACI RBAC rules enable or restrict access to some or all of the fabric. For example, in order to configure a leaf switch for bare metal server access, the logged in administrator must have rights to the infra domain. By default, a tenant administrator does not have rights to the infra domain. In this case, a tenant administrator who plans to use a bare metal server connected to a leaf switch could not complete all the necessary steps to do so. The tenant administrator would have to coordinate with a fabric administrator who has rights to the infra domain. The fabric administrator would set up the switch configuration policies that the tenant administrator would use to deploy an application policy that uses the bare metal server attached to an ACI leaf switch.

User access, authorization, and accounting

User access, authorization, and accounting is a security framework that

  • manages the authentication, authorization, and accounting (AAA) functions of the Cisco Application Centric Infrastructure (ACI) fabric through Application Policy Infrastructure Controller (APIC) policies

  • combines user privileges, roles, and domains with access rights inheritance to enable administrators to configure AAA functions at the managed object level in a granular fashion, and

  • supports implementation using the REST API, the CLI, or the GUI.

Login domain limitations


Note

There is a known limitation where you cannot have more than 32 characters for the login domain name. In addition, the combined number of characters for the login domain name and the user name cannot exceed 64 characters.

Multiple tenant support

Multiple tenant support is a data access control system that

  • provides multitenant isolation through a core Application Policy Infrastructure Controller (APIC) internal data access control system

  • prevents information privacy from being compromised across tenants through read/write restrictions, and

  • restricts tenants from accessing other tenants' configuration, statistics, faults, or event data unless administrators assign specific permissions.

User access roles, privileges, and security domains

User access roles, privileges, and security domains are access control mechanisms that

  • associate Cisco Application Centric Infrastructure (ACI) fabric users with predefined or custom roles containing one or more privileges

  • determine the managed objects (MOs) to which the user has access through a set of privileges

  • provide privilege types for each role: no access, read-only, or read-write, and

  • use one or more security domain tags that identify the portions of the management information tree (MIT) that a user can access.

Roles and privileges

A privilege controls access to a particular function within the system. The ACI fabric manages access privileges at the managed object (MO) level. Every object holds a list of the privileges that can read from it and a list of the privileges that can write to it. All objects that correspond to a particular function will have the privilege for that function in its read or write list. Because an object might correspond to additional functions, its lists might contain multiple privileges. When a user is assigned a role that contains a privilege, the user is given read access to the associated objects whose read list specifies read access, and write access to those whose write list specifies write access.

As an example, 'fabric-equipment' is a privilege that controls access to all objects that correspond to equipment in the physical fabric. An object corresponding to equipment in the physical fabric, such as 'eqptBoard,' will have 'fabric-equipment' in its list of privileges. The 'eqptBoard' object allows read-only access for the 'fabric-equipment' privilege. When a user is assigned a role such as 'fabric-admin' that contains the privilege 'fabric-equipment,' the user will have access to those equipment objects, including read-only access to the 'eqptBoard' object.


Note

Some roles contain other roles. For example, '-admin' roles such as tenant-admin, fabric-admin, access-admin are groupings of roles with the same base name. For example, 'access-admin' is a grouping of 'access-connectivity', 'access-equipment', 'access-protocol', and 'access-qos.' Similarly, tenant-admin is a grouping of roles with a 'tenant' base, and fabric-admin is a grouping of roles with a 'fabric' base.

The 'admin' role contains all privileges. The 'admin' user cannot be deleted from APIC.

For more details about roles and privileges see APIC Roles and Privileges Matrix.

A security domain is a tag associated with a certain subtree in the ACI MIT object hierarchy. For example, the default tenant "common" has a domain tag common. Similarly, the special domain tag all includes the entire MIT object tree. An administrator can assign custom domain tags to the MIT object hierarchy. For example, an administrator could assign the "solar" domain tag to the tenant named "solar." Within the MIT, only certain objects can be tagged as security domains. For example, a tenant can be tagged as a security domain, but objects within a tenant cannot.


Note

(Until R6.1.2) Password strength parameters can be configured by either creating Custom Conditions or by selecting Any Three Conditions that are provided.


Note

(From R6.1.3) Password strength parameters can be configured by either creating Custom Conditions or by selecting the Default Three Conditions, which include lowercase letters, digits, and special characters.

Creating a user and assigning a role to that user does not enable access rights. It is necessary to also assign the user to one or more security domains. By default, the ACI fabric includes these special pre-created domains:

  • All—allows access to the entire MIT

  • Common—allows access to fabric common objects/subtrees

  • Mgmt—allows access to fabric management objects/subtrees


Note

For read operations to the managed objects that a user's credentials do not allow, a "DN/Class Not Found" error is returned, not "DN/Class Unauthorized to read." For write operations to a managed object that a user's credentials do not allow, an HTTP 401 Unauthorized error is returned. In the GUI, actions that a user's credentials do not allow, either they are not presented, or they are grayed out.

A set of predefined managed object classes can be associated with domains. These classes should not have overlapping containment. Examples of classes that support domain association are:

  • Layer 2 and Layer 3 network managed objects

  • Network profiles (such as physical, Layer 2, Layer 3, management)

  • QoS policies

When an object that can be associated with a domain is created, the user must assign domains to the object within the limits of the user's access rights. Domain assignment can be modified at any time.

If a virtual machine management (VMM) domain is tagged as a security domain, the users contained in the security domain can access the correspondingly tagged VMM domain. For example, if a tenant named solar is tagged with the security domain called sun and a VMM domain is also tagged with the security domain called sun, then users in the solar tenant can access the VMM domain according to their access rights.

Login domains

A login domain is an authentication domain mechanism that

  • defines the authentication domain for a user

  • can be set to Local, LDAP, RADIUS, TACACS+, DUO, SAML, RSA, or OAuth 2 authentication mechanisms, and

  • enables the user to select the correct authentication domain when accessing the system from REST, CLI, or GUI.

Authentication access methods

When accessing the APIC through different interfaces, the authentication method varies:

  • REST: The username is prefixed with a string so that the full login username looks as follows: 

    apic:<domain>\<username>

  • GUI: The APIC offers a drop-down list of domains for the user to select.

If no apic: domain is specified, the default authentication domain servers are used to look up the username.

Starting in ACI version 1.0(2x), the login domain fallback of the APIC defaults local. If the default authentication is set to a non-local method and the console authentication method is also set to a non-local method and both non-local methods do not automatically fall back to local authentication, the APIC can still be accessed via local authentication.

To access the APIC fallback local authentication, use these strings:

  • Use the APIC#fallback\\username string for REST API, GUI, and CLI for both APIC and Switches.

  • Use the apic:fallback\\username string for only the REST API and the GUI, but not for the CLI interface.


Note

Do not change the fallback login domain. Doing so could result in being locked out of the system.

Create login domain using the GUI

This task creates a login domain to define authentication parameters for users accessing the fabric through external authentication servers. The login domain establishes the realm and authentication method for user access control.

Authentication by an external server for SAML and OAuth 2 is based on user group map rule information, in addition to the standard CiscoAVpair-based authentication.

Before you begin

  • The Cisco Application Centric Infrastructure (ACI) fabric is installed, Application Policy Infrastructure Controllers (APICs) are online, and the APIC cluster is formed and healthy.

  • The login domain name, realm, and remote server provider are available to define the authentication domain for the user.

Follow these steps to create a login domain using the GUI:

Procedure

Step 1

On the menu bar, choose Admin > AAA.

Step 2

In the Navigation pane, choose Authentication.

Step 3

In the Work pane, choose the Login Domains tab.

Step 4

Click the Actions button > Create Login Domain.

Step 5

In the Create Login Domain screen, in the General pane, specify the following:

  • The user configured domain name.

  • Description of the login domain.

  • The realm to verify the identity of an entity (person or device) accessing the fabric devices. The options available in the Realm drop-down list are discussed here:

    1. A RADIUS provider group for a group of remote servers supporting the RADIUS protocol for authentication.

    2. A TACACS+ provider group for a group of remote servers supporting the TACACS+ protocol for authentication.

    3. An LDAP provider group for a group of remote servers supporting the LDAP protocol for authentication.

    4. A RSA provider group for a group of remote servers supporting the RSA protocol for authentication.

    5. A SAML provider remote server supporting the SAML protocol for authentication.

    6. An OAuth 2 provider remote server supporting the OAuth 2 protocol for authentication.

Note

 

If LDAP, RADIUS, or TACACS+ is specified as the default security method and the associated provider group specified in this dialog is not available to provide authentication during a user login, fallback local authentication is not executed by the Cisco APIC server unless is specifically configured to do so.

If Cisco APIC requires proxy servers to reach identity providers, then configure the corresponding proxy addresses. The proxy setting configuration is found under System > System Settings > Proxy Policy. In the Proxy Policy pane, enter the required URL in the HTTP URL or HTTPS URL fields.

Step 6

Fill in the details for the displayed options. The displayed options are dynamic and based on the selected Realm.

When the selected Realm is RADIUS or LDAP, these options are displayed:

  • Select either Default or Duo for the Realm Subtype.

  • In the Settings pane, click Add RADIUS (or LDAP) Provider to select or create a provider if you selected the Default option above. If you have selected the Duo option, click Add RADIUS (or LDAP) Duo Provider to select or create a provider.

When the selected Realm is TACACS+ or RSA, these options are displayed:

  • In the Settings pane, click Add RSA (or TACACS+) Provider to select or create a provider.

When the selected Realm is SAML or OAuth 2, these options are displayed:

  • In the Settings pane, click Select SAML (or OAuth 2) Provider to select or create a provider.

  • For SAML (or OAuth 2) Authorization Choice, select either CiscoAVPair or GroupMap.

    • When CiscoAVPair is selected, the authorization is based on the CiscoAVpair value/ string configured on the external authentication server. On receiving the CiscoAVPair value from external IDP, Cisco APIC assigns the privileges accordingly to the remote user.

    • When GroupMap is selected, the authorization is based on the group information configured on the external authentication server. On receiving the user group information from the external IDP, Cisco APIC matches the user group name configured on Cisco APIC and assigns the privileges to the remote user accordingly.

    Two additional parameters are required for authorization using GroupMap, they are:

    • Enter the Group Attribute. The group attribute entered here should match the group attribute on the external authentication server. For SAML, the group attribute should match the name of the group assertion in the response sent by the SAML IDP server. For OAuth2, the group attribute should match the group claim in the JWT (JSON Web Token) sent by the OAuth2 server. 

      Example: memberOf (used in Active directory), Groups or groups (used in ping ID/Okta)

      Also, for OAuth2, to receive group information from IDP properly, ensure corresponding scope is configured in the OAuth2 provider configuration. Example: openid profile groups .

    • Add a User Group Map Rule, by clicking Add User Group Map Rule.

      In the Add User Group Map Rule window, enter these details:

      1. In the Name field, enter a name for the user group map rule.

      2. In the Description field, enter a description.

      3. In the User Group field, enter the name of the user group to which the user belongs.

        Ensure that the user group entered here matches the user group on the external server. This is used by Cisco APIC to validate the authentication information received from the external server. Privileges are set based on the user group to which the user belongs.

      4. To set User Privileges, click Add User Privileges.

      5. To add a security domain, click Select Security Domain to choose a security domain from the displayed list.

      6. Click Add Role to select a role and associate a privilege type (read or write); click the tick mark to associate the privilege to the role.

        To add more roles, click Add Role, and associate privileges.

      7. Click Add (on Add User Privileges window).

      8. Click Apply (on the Add User Group Map Rule window).

Step 7

Click Save (on the Create Login Domain screen).

The login domain is created with the specified authentication parameters. Users can now authenticate using the configured external authentication server through this login domain.

Create a Provider

Use this procedure to create a provider for the authentication/authorization protocols.

Before you begin

The relevant prerequisites before creating a provider for an authentication/authorization protocol is discussed under the relevant protocol sections.

Procedure

Step 1

On the menu bar, choose Admin > AAA .

Step 2

In the Navigation pane, choose Authentication .

Step 3

In the Work pane, choose Providers .

Step 4

Click Actions > Create Provider .

Step 5

In the Create Provider screen that is displayed, enter the Hostname/IP Address , Description , and choose a Realm from the drop-down list. The choices available for Realm are:

  • RADIUS

  • TACACS+

  • LDAP

  • SAML

  • RSA

  • OAuth 2

The options for configuring a provider are dynamic and change as per the selected Realm . The options available for each Realm are discussed in detail, in the subsequent steps.

Step 6

(Optional) Applicable only for RADIUS: Choose a Realm Subtype . The options are Default or Duo . Specify the following:

  • Password for the RADIUS server; enter the password again for confirmation.

  • Click Select Reachability EPG to choose an endpoint group.

  • The service port number for RADIUS. The range is 1 to 65535. The default value is 1812.

  • The authentication protocol, options are PAP , CHAP , MS-CHAP . You will see this option only if you chose Default for the Realm Subtype .

  • The timeout for communication with a RADIUS server. The range is from 0 to 60 seconds. The default is 5 seconds (Realm Subtype: Default); default is 30 seconds (Realm Subtype:Duo).

  • The number of retries when contacting the RADIUS endpoint.

  • Select the Enabled check box to enable periodic server monitoring; enter a user name and password for the same.

This step is for RADIUS provider configuration. You can now proceed to step 12.

Step 7

(Optional step; applicable only for TACACS+) Specify the following:

  • Password for the TACACS+ server; enter the password again for confirmation.

  • From the Select Reachability EPG drop-down list, choose an endpoint group.

  • Enter the service port number for TACACS+ in the Port field.

    The range is 1 to 65535. The default value is 49 for TACACS+ over non-TLS.

  • The authentication protocol, options are—PAP, CHAP, MS-CHAP.

  • The timeout for communication with a TACACS+ server. The range is from 0 to 60 seconds. The default is 5 seconds.

  • The number of retries when contacting the TACACS+ endpoint.

  • Select the Enabled check box to enable periodic server monitoring; enter a user name and password for the same.

    Follow these steps to configure TACACS+ over TLS.

  • Check the Enable TACACS+ over TLS check box to enable TACACS+ over TLS connection.

    When TACACS+ over TLS is enabled, the TACACS+ provider must not be configured with Shared Secret .

  • In SSL Certificate Validation Level , choose Strict or Permissive option.

  • From the Key Ring drop-down list, choose the key ring certificate for the TACACS+ provider.

  • From the Certificate Authority drop-down list, choose the CA certificate for the TACACS+ provider.

  • Enter the service port number for TACACS+ in the Port field.

    The range is 1 to 65535. The default value is 6049 for TACACS+ over TLS.

Note

 

The user having AAA privilege can modify TLS mode to non-TLS mode and conversely in TACACS+ provider configuration.

This step is for TACACS+ provider configuration. You can now proceed to step 12.

Step 8

(Optional step; applicable only for LDAP) Choose a Realm Subtype, options are— Default or Duo . Specify the following:

  • The Root Distinguished Name (DN) of the LDAP directory.

  • The LDAP Base DN, which is the container name and path in the LDAP server where the APIC searches for the remote user account. This is where the password is validated. Filter is used to locate the attribute that the APIC requests to use for the Cisco AVPair .

  • Password for the LDAP server; enter the password again for confirmation.

  • The service port number for LDAP. The range is 1 to 65535. The default value is 389.

  • Click Select Reachability EPG to choose an endpoint group.

  • The timeout for communication with an LDAP server. The range is from 0 to 60 seconds. The default is 30 seconds.

  • The number of retries when contacting the LDAP endpoint.

  • Select the Enable check box to enable SSL.

  • SSL Certificate Validation Level. The options are:

    • Permissive—A debugging knob to help diagnose DUO LDAP SSL Certificate issues.

    • Strict—A level that should be used when in production.

  • LDAP Attribute.

  • Authentication Method. The options are:

    • LDAP Bind

    • Password Compare

  • Filter Type. Filters are a key element in defining the criteria used to identify entries in search requests. Example: (cn=*), which means any entry that contains one or more cn values. The options are:

    • Default

    • Microsoft Active Directory

    • Custom

  • LDAP Filter. This field is auto-filled based on the selected Filter Type (unless you have chosen the Custom option Filter Type). If you have chosen Default, the filter is cn=Suserid ; if you have chosen Microsoft Active Directory, the filter is sAMAccountName=Suserid .

  • Select the Enabled check box to enable periodic server monitoring; enter a user name and password for the same.

This step is for LDAP provider configuration. You can now proceed to step 12.

Step 9

(Optional step; applicable only for RSA) Specify the following:

  • Password for the RSA server; enter the password again for confirmation.

  • Click Select Reachability EPG to choose an endpoint group.

  • The service port number for RSA. The range is 1 to 65535. The default value is 1812.

  • The timeout for communication with a RSA server. The range is from 0 to 60 seconds. The default is 5 seconds.

  • The number of retries when contacting the RSA endpoint.

  • Select the Enabled check box to enable periodic server monitoring; enter a user name and password for the same.

This step is for RSA provider configuration. You can now proceed to step 12.

Step 10

(Optional step; applicable only for SAML) Specify the following:

  • Identity Provider (IdP). The options are—ADFS, OKTA, PING IDENTITY.

  • Metadata URL provided by IDP.

    In case of ADFS, Metadata URL provided by IDP is of the format, https://<FQDN of ADFS>/FederationMetadata/2007-06/FederationMetadata.xml.

    For Ping ID, copy the metadata URL link from the configuration section of the Ping ID server (under the SAML application).

  • Enter the IdP Entity ID for the SAML-based service.

  • Enter the SP Entity ID (Service Provider Entity ID). This identifier represents the APIC and can be any string, although the ACS URL is commonly used. Configure the same value on the Identity Provider (IdP).

    For the 6.2(2) release and earlier, use the query-parameter URL: 
    https://apic-id/api/aaaLoginSSO.json?name=domain-name
    For the 6.2(3) release and later, use the path-based URL: 
    https://apic-saml/<samldomain-name>

    Attention

     

    The SP Entity ID is a required field and cannot be empty during SAML provider creation on APIC. It is an arbitrary but stable identifier for APIC as the SAML service provider. For example, you can use https://apic-saml/OKTA; it does not have to be a reachable URL and is not the ACS URL. Use the same SP Entity ID on every APIC a given cluster, and configure this same value as the SP Entity ID / Audience (relying-party identifier) on the identity provider.

  • Click Select Certificate Authority to select a certificate authority if IdP is signed by a private CA.

  • GUI Redirect Banner. This can be a URL or a message. This information is displayed before the user is redirected to the Identity Provider login page for authentication.

  • The timeout for communication with a SAML server. The range is from 0 to 60 seconds. The default is 5 seconds.

  • Select the Signature Algorithm from the drop down list.

  • Put a check in the Enabled check box, to enable all/any of these— Encrypted SAML Assertions, Assertions in SAML Response Signed, SAML Auth Requests Signed, SAML Response Message Signed.

This step is for SAML provider configuration. You can now proceed to step 12.

Step 11

(Optional step; applicable only for OAuth 2) Specify the following:

  • Client ID—Client identifier of the APIC application on IdP.

  • Client Secret for the APIC application. Enter the client secret again for confirmation.

  • Username Claim. Username attribute in the token. Example: email, sub.

  • Scope. List of OAuth 2 scopes. Example: "openid profile". To receive user group information, add the corresponding scope configured in the IdP provider. Example: "openid profile groups".

  • Choose to Enable or Disable the OIDC Protocol.

  • Put a check in the Enabled check box to Verify Token Signature.

  • JWKS Endpoint. The JSON Web Key Sets (JWKS) to verify the token. This field is displayed only if you have enabled Verify Token Signature.

  • Authorization Endpoint. The IdP endpoint authorization URL. Get the authorization endpoint from the IdP server. This field is displayed only when the OIDC protocol is disabled.

  • Token Endpoint. The IdP endpoint token URL. Get the token endpoint from the IdP server. This field is displayed only when the OIDC protocol is disabled.

  • Issuer URL. Get the issuer URL from the IdP server. This field is displayed only when the OIDC protocol is enabled.

  • Click Select Certificate Authority to select a certificate authority if IdP is signed by a private CA.

  • Click Select Reachability EPG to choose an endpoint group.

  • The timeout for communication with an OAuth 2 server. The range is from 0 to 60 seconds. The default is 5 seconds.

  • GUI Redirect Banner. This can be a URL or a message. This information is displayed before the user is redirected to the Identity Provider login page for authentication.

This step is for OAuth 2 provider configuration. You can now proceed to step 12.

Step 12

Click Save .

Local user configuration

A local user is a system account that

  • provides authenticated access to the system with assigned roles and privileges

  • supports granular, role-based access control where accounts can be created with various roles including non-admin users with fewer privileges, and

  • exists in addition to the initial admin account that is configured in the initial configuration script when the system starts.

Local user access control

The APIC supports a granular, role-based access control system where user accounts can be created with various roles including non-admin users with fewer privileges.

Configure a local user using the GUI

Configure a local user account to provide authenticated access to the APIC system with specified security domain permissions and role privileges.

Local user accounts provide direct authentication to the APIC system without requiring external authentication servers. Each local user is assigned to specific security domains and granted role-based privileges that control their access permissions within the fabric.

Before you begin

  • The ACI fabric is installed, APIC controllers are online, and the APIC cluster is formed and healthy.

  • As appropriate, the security domain(s) that the user will access are defined. For example, if the new user account will be restricted to accessing a tenant, the tenant domain is tagged accordingly.

  • An APIC user account is available that will enable the following:

    • Creating the TACACS+ provider.

    • Creating the local user account in the target security domain(s). If the target domain is all, the login account used to create the new local user must be a fabric-wide administrator that has access to all. If the target domain is a tenant, the login account used to create the new local user must be a tenant administrator that has full read write access rights to the target tenant domain.

Follow these steps to configure a local user using the GUI:

Procedure

Step 1

On the menu bar, choose Admin > AAA.

Step 2

In the Navigation pane, click Users.

In the Work pane, verify that you are in the Local Users tab.

Step 3

In the Work pane, click the task icon drop-down list and select Create Local User.

Step 4

In the STEP 1 > User Identity dialog box, perform these actions:

  1. In the Login ID field, add an ID.

    The login ID must meet these guidelines:

    • Must be unique within APIC.

    • Must begin with a letter.

    • Can contain between 1 and 32 characters.

    • Can include alphanumeric characters, underscores, dashes, and dots.

    After creating a user account, you cannot change the login ID. You must delete the user account and create a new one.

  2. In the Password field, enter the password.

    At the time a user sets their password, the Cisco APIC validates it against these criteria:

    • Minimum password length is 8 characters.

    • Maximum password length is 64 characters.

    • Has fewer than three consecutive repeated characters.

    • (Until R6.1.1) Password must include characters from at least three of these character types: lowercase letters, uppercase letters, digits, and symbols.

    • (From R6.1.2) Depending on the conditions of the password strength check, these requirements must be met:

      • If default conditions are enabled:

        • Password must include characters from at least three of these character types: lowercase letters, uppercase letters, digits, and symbols. From R6.1.3, password must specifically contain characters from all three of these character types: lowercase letters, digits, and symbols.

      • If custom conditions are enabled, select at least three of these conditions:

        • Password must include at least one uppercase letter.

        • Password must include at least one lowercase letter.

        • Password must include at least one digit.

        • Password must include at least one symbol.

        • Password must not contain any character repeated more than three times consecutively.

        • Password must not include more than three consecutive characters from the QWERTY keyboard layout. This is applicable only to these character types: lower case letters, upper case letters, and digits.

    • Does not use easily guessed passwords.

    • Cannot be the username or the reverse of the username.

    • Cannot be any variation of cisco, isco or any permutation of these characters or variants obtained by changing the capitalization of letters therein.

  3. In the Confirm Password field, confirm the password.

  4. (Optional) For Certificate based authentication, in the User Certificate Attribute field, enter the user identity from the authentication certificate.

  5. Click Next.

Step 5

You can activate or deactivate the user account by using the Account Status control, and you can set an expiration date by using the Account Expires control.

Step 6

In the STEP 2 > Security dialog box, under Security Domain, choose the desired security domain for the user, and click Next.

Step 7

In the STEP 3 > Roles dialog box, perform these actions:

  1. Click the + to associate the user with a domain.

  2. From the drop-down lists, choose a Role Name and a Role Privilege Type for the user.

  3. click Update

You can provide read-only or read/write privileges.

Step 8

click Finish

The local user account is created with the specified login credentials, security domain assignment, and role privileges. The user can now authenticate to the APIC system using their login ID and password.

Configure SSH public key authentication using the GUI

SSH public key authentication provides a more secure method of logging in to a server compared to password-based authentication. This task enables you to set up SSH public key authentication for local users through the GUI interface.

SSH public key authentication uses a pair of keys (public and private) to authenticate users. The public key is stored on the server, while the private key remains with the user. This method enhances security by eliminating the need to transmit passwords over the network.

Before you begin

  • Create a local user account in the target security domain(s). If the target domain is all, the login account used to create the new local user must be a fabric-wide administrator that has access to all. If the target domain is a tenant, the login account used to create the new local user must be a tenant administrator that has full read write access rights to the target tenant domain.

  • Generate a public key using the Unix command SSH-keygen .

    The default login domain must be set to local

Follow these steps to configure SSH public key authentication using the GUI:

Procedure

Step 1

On the menu bar, choose Admin > Users and confirm you are in the Local tab.

Step 2

In the Work pane, click the name of the user that you previously created.

A window is displayed on the right with information about the user.

Step 3

Click the Details icon, The window displays user information and SSH Authorization details for configuring public key authentication., and the user details are displayed on a new screen.

Scroll down to see the SSH Authorization details.

Step 4

Click the Edit icon, The window displays user information and SSH Authorization details, guiding the user to create an SSH Private Key File for download., and the Edit Local User screen is displayed. You can change the SSH details as required.

Note

 

To create the SSH Private Key File for downloading to a remote location, in the menu bar, expand Firmware > Download Tasks.

Step 5

Click Save.

SSH public key authentication is now configured for the selected local user. The user can authenticate using their private key instead of a password when connecting to the system.

Remote users

A remote user is an authentication method that

  • enables the APIC to point at centralized enterprise credential datacenters instead of configuring local users,

  • supports multiple protocols including Lightweight Directory Access Protocol (LDAP), active directory, RADIUS, and TACACS+, and

  • provides server monitoring capabilities starting with the 3.1(1) release to determine whether AAA servers are alive.

Remote user authentication requirements

To configure a remote user authenticated through an external authentication provider, you must meet these prerequisites:

  • The DNS configuration should have already been resolved with the hostname of the RADIUS server.

  • You must configure the management subnet.


Note

When an APIC is in minority (disconnected from the cluster), remote logins can fail because the ACI is a distributed system and the user information is distributed across APICS. Local logins, however, continue to work because they are local to the APIC.

Server monitoring can be configured through RADIUS, TACACS+, LDAP, and RSA to determine whether the respective AAA servers are alive. Server monitoring feature uses the respective protocol login to check for server aliveness. For example, a LDAP server will use LDAP login and a RADIUS server will use RADIUS login with server monitoring to determine server aliveness.

AV pairs on external authentication servers

An AV pair on an external authentication server is a configuration mechanism that

  • specifies the APIC required RBAC roles and privileges for the user

  • uses the same format for RADIUS, LDAP, or TACACS+, and

  • is configured by adding a Cisco AV pair to the existing user record on the external authentication server.

AV pair configuration details

The Cisco APIC requires that an administrator configure a Cisco AV Pair on an external authentication server. To configure a Cisco AV Pair on an external authentication server, an administrator adds a Cisco AV pair to the existing user record.

The Cisco AV pair format is as follows:

shell:domains = 
domainA/writeRole1|writeRole2|writeRole3/readRole1|readRole2,
domainB/writeRole1|writeRole2|writeRole3/readRole1|readRole2
shell:domains = 
domainA/writeRole1|writeRole2|writeRole3/readRole1|readRole2,
domainB/writeRole1|writeRole2|writeRole3/readRole1|readRole2(16003)

Starting with Cisco APIC release 2.1, if no UNIX ID is provided in AV Pair, the APIC allocates the unique UNIX user ID internally.

Starting with release 3.1(x), the AV Pair shell:domains=all//admin allows you to assign Read-only privileges to users and provide them access to the switches and run commands.

The APIC supports these regexes: 

shell:domains\\s*[=:]\\s*((\\S+?/\\S*?/\\S*?)(,\\S+?/\\S*?/\\S*?){0,31})(\\(\\d+\\))$
shell:domains\\s*[=:]\\s*((\\S+?/\\S*?/\\S*?)(,\\S+?/\\S*?/\\S*?){0,31})$

Note

The APIC Cisco AV-pair format is compatible and can co-exist with other Cisco AV-pair formats. APIC will pick up the first matching AV-pair from all the AV-pairs.


Note

The "/" character is a separator between writeRoles and readRoles per Security domain and is required even if only one type of role is to be used.

The Cisco AVpair string is case sensitive. Although a fault may not be seen, using mismatching cases for the domain name or roles could lead to unexpected privileges being given.

AV pair configuration examples

These examples show different AV pair configurations:

  • Example 1: A Cisco AV Pair that contains a single Security domain with only writeRoles:

    shell:domains=domainA/writeRole1|writeRole2/

  • Example 2: A Cisco AV Pair that contains a single Security domain with only readRoles:

    shell:domains=domainA//readRole1|readRole2
An example configuration for an open RADIUS server (/etc/raddb/users) is as follows:
aaa-network-admin Cleartext-Password := "<password>"
Cisco-avpair = "shell:domains = all/aaa/read-all(16001)"

Configure an AV pair on the external authentication server

Configure an AV pair on the external authentication server to define user authentication parameters and domain access privileges for SSH or telnet login sessions.

The numerical value within the parentheses in the attribute/value (AV) pair string is used as the UNIX user ID of the user who is logged in using Secure Shell (SSH) or telnet.


Note

Beginning with the 6.0(2) release, telnet is not supported.
Procedure

Configure an AV pair on the external authentication server.

The Cisco AV pair definition is as follows (Cisco supports AV pairs with and without UNIX user IDs specified):

Example:
shell:domains = domainA/writeRole1|writeRole2|writeRole3/readRole1|readRole2,domainB/writeRole1|writeRole2|writeRole3/readRole1|readRole2
shell:domains = domainA/writeRole1|writeRole2|writeRole3/readRole1|readRole2,domainB/writeRole1|writeRole2|writeRole3/readRole1|readRole2(8101)

These are the boost regexes supported by APIC:
uid_regex("shell:domains\\s*[=:]\\s*((\\S+?/\\S*?/\\S*?)(,\\S+?/\\S*?/\\S*?){0,31})(\\(\\d+\\))$");
regex("shell:domains\\s*[=:]\\s*((\\S+?/\\S*?/\\S*?)(,\\S+?/\\S*?/\\S*?){0,31})$");

The following is an example:

shell:domains = coke/tenant-admin/read-all,pepsi//read-all(16001)

Note

 

ACI users have limited access to APIC nodes. After you login to APIC using the CLI, you stay in a restricted sandbox with limited privileges. As an ACI user, you get your own home directory /home/$user and a /tmp directory. The mounted /tmp directory for a user is different from /tmp directory of the main system. You can create files only under these directories, you cannot create and delete files in any other directory. Also, you cannot delete files created by other users. Users also have restrictions regarding CPU, memory usages and FDs. Read-only users cannot create, update, or delete any configuration data.

The AV pair is configured on the external authentication server with the specified domain access and user privileges.

Configure APIC for TACACS+ access

This task enables TACACS+ authentication for user access to the APIC.

TACACS+ provides centralized authentication, authorization, and accounting services for network access. This configuration is essential for enterprise environments that require secure, centralized user management.

Before you begin

  • The Cisco Application Centric Infrastructure (ACI) fabric is installed, Application Policy Infrastructure Controllers (APICs) are online, and the APIC cluster is formed and healthy.

  • The TACACS+ server host name or IP address, port, and key are available.

  • The APIC management endpoint group is available.

Procedure

Step 1

In the APIC, create the TACACS+ Provider.

For configuring a TACACS+ provider, see Create a Provider.

For toggling in-band or out-of-band management in the APIC GUI:

In the Navigation pane, choose System > System Settings > APIC Connectivity Preferences. In the Work Pane select either inband or ooband.

Step 2

Create the Login Domain for TACACS+.

For the detailed procedure, see Create login domain using the GUI.

The APIC is now configured for TACACS+ authentication with the provider and login domain created.

What to do next

This completes the APIC TACACS+ configuration steps. Next, if a RAIDUS server will also be used, configure the APIC for RADIUS. If only a TACACS+ server will be used, go to the ACS server configuration topic below.

Configure APIC for RADIUS access

Configure APIC for RADIUS access to enable centralized authentication and authorization for user access to the APIC.

This configuration allows the APIC to authenticate users against a RADIUS server, providing centralized user management and enhanced security for the ACI fabric.

Before you begin

  • The ACI fabric is installed, Application Policy Infrastructure Controllers (APICs) are online, and the APIC cluster is formed and healthy.

  • The RADIUS server host name or IP address, port, authorization protocol, and key are available.

  • The APIC management endpoint group is available.

Procedure

Step 1

In the APIC, create the RADIUS provider.

For configuring a RADIUS provider, see Create a Provider.

For toggling in-band or out-of-band management in the APIC GUI:

In the Navigation pane, choose System > System Settings > APIC Connectivity Preferences. In the Work Pane select either inband or ooband.

Step 2

Create the Login Domain for RADIUS.

For the detailed procedure, see Create login domain using the GUI.

The APIC is now configured for RADIUS access with the necessary provider and login domain created.

What to do next

This completes the APIC RADIUS configuration steps. Next, configure the RADIUS server.

Configure a Cisco Secure Access Control Server for RADIUS and TACACS+ access to the APIC

This task configures a Cisco Secure Access Control Server to provide centralized authentication and authorization services for users accessing the APIC through RADIUS and TACACS+ protocols.

The Cisco Secure Access Control Server (ACS) provides centralized authentication, authorization, and accounting (AAA) services. When configured properly, it allows you to control user access to the APIC and assign appropriate role-based access control (RBAC) privileges based on user identity groups.

Before you begin

  • The Cisco Secure Access Control Server (ACS) version 5.5 is installed and online.


    Note

    ACS v5.5 was used to document these steps. Other versions of ACS might support this task but the GUI procedures might vary accordingly.

  • The Cisco Application Policy Infrastructure Controller (Cisco APIC) RADIUS or TACACS+ keys are available (or keys for both if both will be configured).

  • The APICs are installed and online; the APIC cluster is formed and healthy.

  • The RADIUS or TACACS+ port, authorization protocol, and key are available.

Follow these steps to configure a Cisco Secure Access Control Server for RADIUS and TACACS+ access to the APIC:

Procedure

Step 1

Log in to the ACS server to configure the APIC as a client.

  1. Navigate to Network Resources > Network Devices Groups > Network Devices and AAA Clients.

  2. Specify the client name, the APIC in-band IP address, select the TACACS+ or RADIUS (or both) authentication options.

    Note

     

    If the only RADIUS or TACACS+ authentication is needed, select only the needed option.

  3. Specify the authentication details such as Shared Secret (key), and port as appropriate for the authentication option(s).

    Note

     

    The Shared Secret(s) must match the APIC Provider key(s).

Step 2

Create the Identity Group.

  1. Navigate to Users and Identity Stores > Internal Groups option.

  2. Specify the Name, and Parent Group as appropriate.

Step 3

Map users to the Identity Group.

  1. In the Navigation pane, click the Users and Identity Stores > Internal Identity Stores > Users option.

  2. Specify the user Name, and Identity Group as appropriate.

Step 4

Create the Policy Element.

  1. Navigate to the Policy Elements option.

  2. For RADIUS, specify the Authorization and Permissions > Network Access > Authorization Profiles Name. For TACACS+, specify the Authorization and Permissions > Device Administration > Shell Profile Name as appropriate.

  3. For RADIUS, specify the Attribute as cisco-av-pair , Type as string, and the Value as shell:domains = <domain>/<role>/,<domain>//role as appropriate. For TACACS+, specify the Attribute as cisco-av-pair , Requirement as Mandatory, and the Value as shell:domains = <domain>/<role>/,<domain>//role as appropriate.

    The syntax of the Value field determines whether write privileges are granted:

    • For read/write privileges, the syntax is shell:domains = <domain>/<role>/ .

    • For read-only privileges, the syntax is shell:domains = <domain>// <role> .

    For example, if the cisco-av-pair has a value of shell:domains = solar/admin/,common// read-ALL , then solar is the security domain, admin is the role that gives write privileges to this user in the security domain called solar , common is the tenant common, and read-ALL is the role with read privileges that gives this user read privileges to ALL of the tenant common.

Step 5

Create a service selection rule.

  1. For RADIUS, create a service selection rule to associate the Identity Group with the Policy Element by navigating to Access Policies > Default Device Network Access Identity > Authorization and specifying the rule Name, Status, and Conditions as appropriate, and Add the Internal Users:UserIdentityGroup in ALL Groups:<identity group name> .

  2. For TACACS+, create a service selection rule to associate the Identity Group with the Shell Profile by navigating to Access Policies > Default Device Admin Identity > Authorization. Specify the rule Name, Conditions, and Select the Shell Profile as appropriate.

The Cisco Secure Access Control Server is now configured to provide RADIUS and TACACS+ authentication and authorization for users accessing the APIC. Users can now authenticate using their configured credentials and will receive appropriate access privileges based on their assigned identity groups and roles.

What to do next

Use the newly created RADIUS and TACACS+ users to log in to the APIC. Verify that the users have access to the correct APIC security domain according to the assigned RBAC roles and privileges. The users should not have access to items that have not been explicitly permitted. Read and write access rights should match those configured for that user.

Configure windows server 2012 LDAP for APIC access with Cisco AVPair

Configure Windows Server 2012 LDAP to authenticate users and provide role-based access control for Cisco APIC using the CiscoAVPair attribute.

LDAP authentication provides centralized user management and role-based access control for Cisco APIC. The CiscoAVPair attribute enables you to assign specific RBAC roles to users, controlling their access permissions within security domains.

Before you begin

  • First, configure the LDAP server, then configure the Cisco Application Policy Infrastructure Controller (Cisco APIC) for LDAP access.

  • The Microsoft Windows Server 2012 is installed and online.

  • The Microsoft Windows Server 2012 Server Manager ADSI Edit tool is installed. To install ADSI Edit, follow the instructions in the Windows Server 2012 Server Manager help.

  • CiscoAVPair attribute specifications: Common Name = CiscoAVPair, LDAP Display Name = CiscoAVPair, Unique X500 Object ID = 1.3.6.1.4.1.9.22.1, Description = CiscoAVPair, Syntax = Case Sensitive String.


    Note

    For LDAP configurations, best practice is to use CiscoAVPair as the attribute string. If customer faces the issue using Object ID 1.3.6.1.4.1.9.22.1, an additional Object ID 1.3.6.1.4.1.9.2742.1-5 can also be used in the LDAP server.

  • A Microsoft Windows Server 2012 user account is available that will enable the following:

    • Running ADSI Edit to add the CiscoAVPair attribute to the Active Directory (AD) Schema.

    • Configuring an Active Directory LDAP user to have CiscoAVPair attribute permissions.

  • Port 636 is required for configuring LDAP integration with SSL/TLS.

Follow these steps to configure Windows Server 2012 LDAP for APIC access with Cisco AVPair:

Procedure

Step 1

Log in to an Active Directory (AD) server as a domain administrator.

Step 2

Add the CiscoAVPair attribute to the AD schema.

  1. Navigate to Start > Run, type MMC and press Enter.

    The Microsoft Management Console (MMC) opens.

  2. Navigate to File > Add/Remove Sanp-in > Add.

  3. In the Add Standalonee Snap-in dialog box, select the Active Directory Schema and click Add.

    The MMC Console opens.

  4. Right-click the Attributes folder, select the Create Attribute option.

    The Create New Attribute dialog box opens.

  5. Enter CiscoAVPair for the Common Name, CiscoAVPair for the LDAP Display Name, 1.3.6.1.4.1.9.22.1 for the Unique X500 Object ID, and select Case Sensitive String for the Syntax.

  6. Click OK to save the attribute.

Step 3

Update the User Properties class to include the CiscoAVPair attribute.

  1. In the MMC Console, expand the Classes folder, right-click the user class, and choose Properties.

    The user Properties dialog box opens.

  2. Click the Attributes tab, and click Add to open the Select Schema Object window.

  3. In the Select a schema object: list, choose CiscoAVPair, and click Apply.

  4. In the MMC Console, right-click the Active Directory Schema, and select Reload the Schema.

Step 4

Configure the CiscoAVPair attribute permissions.

Now that the LDAP includes the CiscoAVPair attributes, LDAP users need to be granted Cisco APIC permission by assigning them Cisco APIC RBAC roles.

  1. In the ADSI Edit dialog box, locate a user who needs access to the Cisco APIC.

  2. Right-click on the user name, and choose Properties.

    The <user> Properties dialog box opens.

  3. Click the Attribute Editor tab, select the CiscoAVPair attribute, and enter the Value as shell:domains = <domain>/<role>/,<domain>// role.

    For example, if the CiscoAVPair has a value of shell:domains = solar/admin/,common// read-all(16001) , then solar is the security domain, admin is the role for this user that gives write privileges to this user in the security domain called solar , common is the Cisco Application Centric Infrastructure (Cisco ACI) tenant common, and read-all(16001) is the role with read privileges that gives this user read privileges to all of the Cisco ACI tenant common.

  4. Click OK to save the changes and close the <user> Properties dialog box.

The LDAP server is configured to access the Cisco APIC.

What to do next

Configure the Cisco APIC for LDAP access.

Configure APIC for LDAP access

Configure APIC to use LDAP authentication for user access management.

LDAP configuration enables centralized authentication for APIC users through an external LDAP server.

Before you begin

  • The Cisco Application Centric Infrastructure (ACI) fabric is installed, Application Policy Infrastructure Controllers (APICs) are online, and the APIC cluster is formed and healthy.

  • The LDAP server host name or IP address, port, bind DN, Base DN, and password are available.

  • The APIC management endpoint group is available.

Procedure

Step 1

In the APIC, configure the LDAP Provider.

For configuring an LDAP provider, see Create a Provider.

For toggling in-band or out-of-band management in the APIC GUI:

In the Navigation pane, choose System > System Settings > APIC Connectivity Preferences. In the Work Pane select either inband or ooband.

Step 2

Create the Login Domain for LDAP.

For the detailed procedure, see Create login domain using the GUI.

APIC is configured for LDAP authentication with the provider and login domain created.

What to do next

This completes the APIC LDAP configuration steps. Next, test the APIC LDAP login access.

Change the default behavior for remote users with missing or bad Cisco AV pairs

This task configures how the system handles remote users with authentication issues by assigning default roles instead of denying access completely.

Remote users may occasionally have missing or malformed Cisco AV pairs that prevent proper authentication. By default, these users are denied login access. You can modify this behavior to provide minimal access instead.

Procedure

Step 1

On the menu bar, choose Admin > Authentication > AAA > Policy tab.

Step 2

From the Remote user login policy drop-down list, choose Assign Default Role.

The default value is No Login. The Assign Default Role option assigns the minimal read-only privileges to users that have missing or bad Cisco AV Pairs. Bad AV Pairs are those AV Pairs that fail the parsing rules.

Remote users with missing or bad Cisco AV pairs will now be assigned the default role with minimal read-only privileges instead of being denied login access.

Signature-based transactions

A signature-based transaction is an authentication method that

  • calculates a signature for every transaction using a private key that must be kept secret in a secure location

  • enables the APIC to verify the signature using an X.509 certificate when receiving a request, and

  • provides the most secure authentication by requiring an attacker to crack the RSA/DSA key to forge or impersonate user credentials.

Authentication methods comparison

The APIC controllers in a Cisco ACI fabric offer different methods to authenticate users.

The primary authentication method uses a username and password and the APIC REST API returns an authentication token that can be used for future access to the APIC. This may be considered insecure in a situation where HTTPS is not available or enabled.

In signature-based authentication, every transaction to the APIC must have a newly calculated signature. This is not a task that a user should do manually for each transaction. Ideally this function should be utilized by a script or an application that communicates with the APIC.


Note

Additionally, you must use HTTPS to prevent replay attacks.

Before you can use X.509 certificate-based signatures for authentication, verify that these pre-requisite tasks are completed:

  1. Create an X.509 certificate and private key using OpenSSL or a similar tool.

  2. Create a local user on the APIC. (If a local user is already available, this task is optional).

  3. Add the X.509 certificate to the local user on the APIC.

Guidelines and limitations

Follow these guidelines and limitations:

  • Local users are supported. Remote AAA users are not supported.

  • The APIC GUI does not support the certificate authentication method.

  • WebSockets and eventchannels do not work for X.509 requests.

  • Certificates signed by a third party are not supported. Use a self-signed certificate.

Generate an X.509 certificate and a private key

Generate an X.509 certificate and private key to enable secure authentication. The certificate will be added to the user's profile on the APIC for signature verification, while the private key is used by the client to generate signatures.

X.509 certificates contain public keys used for signature verification, while private keys must be kept secure and are never stored on the APIC. This process creates both components needed for certificate-based authentication.

Procedure

Step 1

Enter an OpenSSL command to generate an X.509 certificate and private key.

Example:

$ openssl req -new -newkey rsa:1024 -days 36500 -nodes -x509 -keyout userabc.key -out userabc.crt -subj '/CN=User ABC/O=Cisco Systems/C=US'

Note

 

  • Once the X.509 certificate is generated, it will be added to the users profile on the APIC, and it is used to verify signatures. The private key is used by the client to generate the signatures.

  • The certificate contains a public key but not the private key. The public key is the primary information used by the APIC to verify the calculated signature. The private key is never stored on the APIC. You must keep it secret.

Step 2

Display the fields in the certificate using OpenSSL.

Example:

$ openssl x509 -text -in userabc.crt
        Certificate:
            Data:
                Version: 3 (0x2)
                Serial Number:
                    c4:27:6c:4d:69:7c:d2:b6
                Signature Algorithm: sha1WithRSAEncryption
                Issuer: CN=User ABC, O=Cisco Systems, C=US
                Validity
                    Not Before: Jan 12 16:36:14 2015 GMT
                    Not After : Dec 19 16:36:14 2114 GMT
                Subject: CN=User ABC, O=Cisco Systems, C=US
                Subject Public Key Info:
                    Public Key Algorithm: rsaEncryption
                    RSA Public Key: (1024 bit)
                        Modulus (1024 bit):
                            00:92:35:12:cd:2b:78:ef:9d:ca:0e:11:77:77:3a:
                            99:d3:25:42:94:b5:3e:8a:32:55:ce:e9:21:2a:ff:
                            e0:e4:22:58:6d:40:98:b1:0d:42:21:db:cd:44:26:
                            50:77:e5:fa:b6:10:57:d1:ec:95:e9:86:d7:3c:99:
                            ce:c4:7f:61:1d:3c:9e:ae:d8:88:be:80:a0:4a:90:
                            d2:22:e9:1b:25:27:cd:7d:f3:a5:8f:cf:16:a8:e1:
                            3a:3f:68:0b:9c:7c:cb:70:b9:c7:3f:e8:db:85:d8:
                            98:f6:e3:70:4e:47:e2:59:03:49:01:83:8e:50:4a:
                            5f:bc:35:d2:b1:07:be:ec:e1
                        Exponent: 65537 (0x10001)
                X509v3 extensions:
                    X509v3 Subject Key Identifier:
                        0B:E4:11:C7:23:46:10:4F:D1:10:4C:C1:58:C2:1E:18:E8:6D:85:34
                    X509v3 Authority Key Identifier:
                        keyid:0B:E4:11:C7:23:46:10:4F:D1:10:4C:C1:58:C2:1E:18:E8:6D:85:34
                        DirName:/CN=User ABC/O=Cisco Systems/C=US
                        serial:C4:27:6C:4D:69:7C:D2:B6
        
                    X509v3 Basic Constraints:
                        CA:TRUE
            Signature Algorithm: sha1WithRSAEncryption
                8f:c4:9f:84:06:30:59:0c:d2:8a:09:96:a2:69:3d:cf:ef:79:
                91:ea:cd:ae:80:16:df:16:31:3b:69:89:f7:5a:24:1f:fd:9f:
                d1:d9:b2:02:41:01:b9:e9:8d:da:a8:4c:1e:e5:9b:3e:1d:65:
                84:ff:e8:ad:55:3e:90:a0:a2:fb:3e:3e:ef:c2:11:3d:1b:e6:
                f4:5e:d2:92:e8:24:61:43:59:ec:ea:d2:bb:c9:9a:7a:04:91:
                8e:91:bb:9d:33:d4:28:b5:13:ce:dc:fe:c3:e5:33:97:5d:37:
                cc:5f:ad:af:5a:aa:f4:a3:a8:50:66:7d:f4:fb:78:72:9d:56:
                91:2c
        [snip]

You have successfully generated an X.509 certificate and private key pair. The certificate file contains the public key and certificate information, while the private key file contains the secret key for generating signatures.

Create a local user and add a user certificate using the GUI

This task creates a local user account with authentication credentials and associates an X.509 certificate for certificate-based authentication through the GUI.

Local users provide direct authentication to the system without requiring external authentication servers. Adding user certificates enables certificate-based authentication as an alternative to password-based login.

Procedure

Step 1

On the menu bar, choose ADMIN > AAA.

Step 2

In the Navigation pane, click Users and Local Users in the Work pane.

Step 3

In the Work pane, verify that you in the Local Users tab.

The ADMIN user is present by default

Step 4

In the Work pane, click on task icon drop-down list and select Create Local User.

Step 5

In the Security dialog box, choose the desired security domain for the user, and click Next.

Step 6

In the Roles dialog box, click the radio buttons to choose the roles for your user, and click Next.

You can provide read-only or read/write privileges.

Step 7

In the User Identity dialog box, perform the following actions:

  1. In the Login ID field, add an ID.

  2. In the Password field, enter the password.

  3. In the Confirm Password field, confirm the password.

  4. (Optional) For Certificate based authentication, in the User Certificate Attribute field, enter the user identity from the authentication certificate.

  5. Click Finish.

Step 8

In the Navigation pane, click the name of the user that you created. In the Work pane, expand the + sign next to your user in the Security Domains area.

The access privileges for your user are displayed.

Step 9

In the Work pane, in the User Certificates area, click the user certificates + sign, and in the Create X509 Certificate dialog box, perform the following actions:

  1. In the Name field, enter a certificate name.

  2. In the Data field, enter the user certificate details.

  3. Click Submit.

The X509 certificate is created for the local user.

A local user account is created with the specified credentials and security domain access. The X.509 certificate is associated with the user for certificate-based authentication.

Create a local user using python SDK

Create a local user account in the APIC system with certificate-based authentication and appropriate role assignments for system access.

Use the Python SDK to programmatically create local users in the APIC system. This method provides automated user provisioning with certificate authentication and role-based access control.

Before you begin

Follow these steps to create a local user using Python SDK:

Procedure

Create a local user.

Example:

#!/usr/bin/env python
from cobra.model.pol import Uni as PolUni
from cobra.model.aaa import UserEp as AaaUserEp
from cobra.model.aaa import User as AaaUser
from cobra.model.aaa import UserCert as AaaUserCert
from cobra.model.aaa import UserDomain as AaaUserDomain
from cobra.model.aaa import UserRole as AaaUserRole
from cobra.mit.access import MoDirectory
from cobra.mit.session import LoginSession
from cobra.internal.codec.jsoncodec import toJSONStr

APIC = 'http://10.10.10.1'
username = 'admin'
password = 'p@$$w0rd'

session = LoginSession(APIC, username, password)
modir = MoDirectory(session)
modir.login()

def readFile(fileName=None, mode="r"):
   if fileName is None:
      return ""
   fileData = ""
   with open(fileName, mode) as aFile:
      fileData = aFile.read()
   return fileData

# Use a dictionary to define the domain and a list of tuples to define
# our aaaUserRoles (roleName, privType)
# This can further be abstracted by doing a query to get the valid
# roles, that is what the GUI does

userRoles = {'all': [
               ('aaa', 'writePriv'),
               ('access-admin', 'writePriv'),
               ('admin', 'writePriv'),
               ('fabric-admin', 'writePriv'),
               ('nw-svc-admin', 'writePriv'),
               ('ops', 'writePriv'),
               ('read-all', 'writePriv'),
               ('tenant-admin', 'writePriv'),
               ('tenant-ext-admin', 'writePriv'),
               ('vmm-admin', 'writePriv'),
           ],
}

uni = PolUni('') # '' is the Dn string for topRoot
aaaUserEp = AaaUserEp(uni)
aaaUser = AaaUser(aaaUserEp, 'userabc', firstName='Adam',
                  email='userabc@cisco.com')

aaaUser.lastName = 'BC'
aaaUser.phone = '555-111-2222'
aaaUserCert = AaaUserCert(aaaUser, 'userabc.crt')
aaaUserCert.data = readFile("/tmp/userabc.crt")
# Now add each aaaUserRole to the aaaUserDomains which are added to the
# aaaUserCert
for domain,roles in userRoles.items():
   aaaUserDomain = AaaUserDomain(aaaUser, domain)
   for roleName, privType in roles:
       aaaUserRole = AaaUserRole(aaaUserDomain, roleName,
                                 privType=privType)
print toJSONStr(aaaUser, prettyPrint=True)

cr = ConfigRequest()
cr.addMo(aaaUser)
modir.commit(cr)
# End of Script to create a user

A local user account is created in the APIC system with the specified certificate authentication and role assignments across all domains.

Using a private key to calculate a signature

This task allows you to authenticate with APIC using signature-based authentication, which provides a secure method for API access without transmitting passwords.

Signature-based authentication requires calculating a digital signature using your private key for each API request. This signature is sent to the APIC as a cookie in the request header for verification.

Before you begin

You must have the following information available:

  • HTTP method - GET, POST, DELETE

  • REST API URI being requested, including any query options

  • For POST requests, the actual payload being sent to the APIC

  • The private key used to generate the X.509 certificate for the user

  • The distinguished name for the user X.509 certificate on the APIC

Follow these steps to use a private key to calculate a signature:

Procedure

Step 1

Concatenate the HTTP method, REST API URI, and payload together in this order and save them to a file.

This concatenated data must be saved to a file for OpenSSL to calculate the signature. In this example, we use a filename of payload.txt. Remember that the private key is in a file called userabc.key.

Example:

GET example: 
GET http://10.10.10.1/api/class/fvTenant.json?rsp-subtree=children
POST example: 
POST http://10.10.10.1/api/mo/tn-test.json{"fvTenant": {"attributes": {"status": "deleted", "name": "test"}}}

Step 2

Verify that the payload.txt file contains the correct information.

For example, using the GET example shown in the previous step:

GET http://10.10.10.1/api/class/fvTenant.json?rsp-subtree=children

Your payload.txt file should contain only the following information:

GET/api/class/fvTenant.json?rsp-subtree=children

Step 3

Verify that you didn't inadvertently create a new line when you created the payload file.

Example:

# cat –e payload.txt

Determine if there is a $ symbol at the end of the output, similar to the following: 

GET/api/class/fvTenant.json?rsp=subtree=children$

If so, then that means that a new line was created when you created the payload file. To prevent creating a new line when generating the payload file, use a command similar to the following: 

echo -n "GET/api/class/fvTenant.json?rsp-subtree=children" >payload.txt

Step 4

Calculate a signature using the private key and the payload file using OpenSSL.

Example:

openssl dgst -sha256 -sign userabc.key payload.txt > payload_sig.bin
The resulting file has the signature printed on multiple lines.

Step 5

Convert the signature to base64 format:

Example:

openssl base64 -A -in payload_sig.bin -out payload_sig.base64

Step 6

Strip the signature of the new lines using Bash.

Example:

$ tr -d '\n' < payload_sig.base64
P+OTqK0CeAZjl7+Gute2R1Ww8OGgtzE0wsLlx8fIXXl4V79Zl7
Ou8IdJH9CB4W6CEvdICXqkv3KaQszCIC0+Bn07o3qF//BsIplZmYChD6gCX3f7q
IcjGX+R6HAqGeK7k97cNhXlWEoobFPe/oajtPjOu3tdOjhf/9ujG6Jv6Ro=

Note

 

This is the signature that will be sent to the APIC for this specific request. Other requests will require to have their own signatures calculated.

Step 7

Place the signature inside a string to enable the APIC to verify the signature against the payload.

This complete signature is sent to the APIC as a cookie in the header of the request.

Example:

APIC-Request-Signature=P+OTqK0CeAZjl7+Gute2R1Ww8OGgtzE0wsLlx8f
IXXl4V79Zl7Ou8IdJH9CB4W6CEvdICXqkv3KaQszCIC0+Bn07o3qF//BsIplZmYChD6gCX3f
7qIcjGX+R6HAqGeK7k97cNhXlWEoobFPe/oajtPjOu3tdOjhf/9ujG6Jv6Ro=; 
APIC-Certificate-Algorithm=v1.0; APIC-Certificate-Fingerprint=fingerprint; 
APIC-Certificate-DN=uni/userext/user-userabc/usercert-userabc.crt

Note

 

The DN used here must match the DN of the user certified object containing the x509 certificate in the next step.

Step 8

Use the CertSession class in the Python SDK to communicate with an APIC using signatures.

This script is an example of how to use the CertSession class in the ACI Python SDK to make requests to an APIC using signatures.

Example:

#!/usr/bin/env python
# It is assumed the user has the X.509 certificate already added to
# their local user configuration on the APIC
from cobra.mit.session import CertSession
from cobra.mit.access import MoDirectory

def readFile(fileName=None, mode="r"):
    if fileName is None:
        return ""
    fileData = ""
    with open(fileName, mode) as aFile:
        fileData = aFile.read()
    return fileData

pkey = readFile("/tmp/userabc.key")
csession = CertSession("https://ApicIPOrHostname/",
                       "uni/userext/user-userabc/usercert-userabc", pkey)

modir = MoDirectory(csession)
resp = modir.lookupByDn('uni/fabric')
pring resp.dn
# End of script

Note

 

The DN used in the earlier step must match the DN of the user certified object containing the x509 certificate in this step.

You have successfully created a signature for APIC authentication and can now use the CertSession class to make authenticated API requests to the APIC.

Accounting

Accounting is a fabric security mechanism that

  • tracks user account login and logout sessions on the Cisco Application Policy Infrastructure Controller and switches

  • monitors changes users make to objects and when the changes occurred, and

  • processes data using the same mechanism as faults and events.

Managed objects

Cisco Application Centric Infrastructure (ACI) fabric accounting is handled by these managed objects:

  • The aaaSessionLR managed object tracks user account login and logout sessions on the Cisco Application Policy Infrastructure Controller (APIC) and switches, and token refresh. The Cisco ACI fabric session alert feature stores information such as:

    • Username

    • IP address initiating the session

    • Type (telnet, HTTPS, REST, and so on)


      Note

      Beginning with the 5.3(1) release, telnet is not supported.

    • Session time and length

    • Token refresh: A user account login event generates a valid active token which is required in order for the user account to exercise its rights in the Cisco ACI fabric.


      Note
      Token expiration is independent of login; a user could log out but the token expires according to the duration of the timer value it contains.

  • The aaaModLR managed object tracks the changes users make to objects and when the changes occurred.

  • If the AAA server is not pingable, it is marked unavailable and a fault is seen.

Both the aaaSessionLR and aaaModLR event logs are stored in Cisco APIC shards. After the data exceeds the pre-set storage allocation size, it overwrites records on a first-in first-out basis.


Note
In the event of a destructive event such as a disk crash or a fire that destroys a Cisco APIC cluster node, the event logs are lost; event logs are not replicated across the cluster.

The aaaModLR and aaaSessionLR managed objects can be queried by class or by distinguished name (DN). A class query provides all the log records for the whole fabric. All aaaModLR records for the whole fabric are available from the GUI at the Fabric > Inventory > POD > History > Audit Log section. The Cisco APIC GUI History > Audit Log options enable viewing event logs for a specific object identified in the GUI.

The standard syslog, callhome, REST query, and CLI export mechanisms are fully supported for aaaModLR and aaaSessionLR managed object query data. There is no default policy to export this data.

There are no pre-configured queries in the Cisco APIC that report on aggregations of data across a set of objects or for the entire system. A fabric administrator can configure export policies that periodically export aaaModLR and aaaSessionLR query data to a syslog server. Exported data can be archived periodically and used to generate custom reports from portions of the system or across the entire set of system logs.

Routed connectivity to external networks as a shared service billing and statistics

Routed connectivity to external networks as a shared service billing and statistics is a ACI feature that

  • enables collection of byte count and packet count billing statistics from ports configured for routed connectivity to external networks as a shared service

  • allows any EPG in any tenant to share an external L3Out EPG for routed connectivity to external networks

  • aggregates billing statistics at the Cisco APIC from leaf switches where external L3Out EPGs are provisioned, and

  • supports periodic export of billing statistics to a server through configurable accounting policies.

External network representation and billing collection

The Cisco Application Policy Infrastructure Controller (APIC) can be configured to collect billing statistics from ports configured for routed connectivity to external networks as a shared service. External networks are represented as external L3Out endpoint group (l3extInstP managed object) in Cisco Application Centric Infrastructure (ACI).

Billing statistics can be collected for each EPG in any tenant that uses an external L3Out EPG as a shared service. The leaf switch where the external L3Out EPG is provisioned forwards the billing statistics to the Cisco APIC where they are aggregated. Accounting policies can be configured to export these billing statistics periodically to a server.