Providers

Provider Overview

You can use Role-Based Access Control (RBAC) for specifying access permissions. RBAC servers are remote network servers that authenticate and authorize network access based on roles assigned to individual users within an enterprise (The accounting part of AAA is not included). If a user’s group in the RBAC server is not specified, or if the provider group is not mapped to any user roles, that user cannot log in. This restriction avoids security issues by ignoring users without mapped groups. You can use the following protocols to authenticate and authorize users: LDAP, Active Directory, TACACS+, and RADIUS. See the Creating sections below for more information about individual protocols.

From the left navigation menu, navigate to External Systems > Providers to go to providers. You can create, clone, edit and delete providers.

_images/providers_401.png

Creating LDAP Provider

Lightweight Directory Access Protocol (LDAP)

  1. From the left navigation menu, navigate to External Systems > Providers and click Create Provider.
  2. Enter a Name (64 characters or fewer), select LDAP, and if you want LDAP to be the active provider, toggle on Active?.
  3. For Connection Settings, enter/select the following:
    • Port - The TCP port - LDAP: 389, LDAPS: 636
    • Hostname FQDN IP(s) - The fully qualified domain name (FQDN) or IP address of the LDAP server. For high availability (HA) environments, specify multiple LDAP servers using the same settings. If the first server cannot be reached, connections to succeeding ones are attempted in order.
  4. For Provider-specific Parameters enter/select the following, as appropriate:
    • Groups Search DN - The LDAP Distinguished Name (DN) path for the RBAC Groups Organizational Unit (OU)
    • Users Search DN - The LDAP Distinguished Name (DN) path for the RBAC Users Organization Unit (OU)
    • Bind DN - The LDAP Distinguished Name (DN) path for the active server user that the Apstra server will connect as
    • Password - The LDAP server user password for the Apstra server to connect as
    • Encryption - None, SSL/TLS or STARTTLS
    • Advanced Config
      • Timeout (seconds)
      • Username Attribute Name - The LDAP attribute from the user entry that Apstra Server uses for authentication. (usually cn or uid)
      • User Search Attribute Name
      • User First Name Attribute Name
      • User Last Name Attribute Name
      • User Email Attribute Name
      • User Object Class Attribute Name
      • User Member Attribute Name
      • Group Name Attribute Name
      • Group DN Attribute Name
      • Group Search Attribute Name
      • Group Member Attribute Name
      • Group Member Mapping Attribute Name
      • Group Object Class Attribute Name
  5. You can Check provider parameters and Check login (to verify authentication with the remote user credentials) before creating the provider.
  6. Click Create to create the provider and return to the list view.

Configuring LDAP Provider

To authorize Apstra users via a LDAP provider, the LDAP server must be configured to properly return a provider group attribute. This attribute must be mapped to a defined Apstra Role. The example configuration below is for the open-source OpenLDAP server.

dn: ou=People,dc=example,dc=com
objectClass: organizationalUnit
ou: People

dn: ou=Groups,dc=example,dc=com
objectClass: organizationalUnit
ou: Groups

dn: cn=user,ou=Groups,dc=example,dc=com
gidNumber: 5000
cn: user
objectClass: posixGroup
memberUid: USER1

dn: cn=USER1,ou=People,dc=example,dc=com
cn: USER1
givenName: USER1
loginShell: /bin/sh
objectClass: inetOrgPerson
objectClass: posixAccount
uid: USER1
userPassword: USER1
uidNumber: 10000
gidNumber: 5000
sn: USER1
homeDirectory: /home/users/USER1
mail: USER1@example.com

The user group must be mapped to a defined Apstra Role.

After configuring and activating a provider, you must map that provider to one or more user roles to give access permissions to users with those roles.

Creating Active Directory Provider

Active Directory (AD) is a database-based system that provides authentication, directory, policy, and other services in a Windows environment.

  1. From the left navigation menu, navigate to External Systems > Providers and click Create Provider.
  2. Enter a Name (64 characters or fewer), select Active Directory, and if you want Active Directory to be the active provider, toggle on Active?.
  3. For Connection Settings, enter/select the following:
    • Port - The TCP port used by the server
    • Hostname FQDN IP(s) - The fully qualified domain name (FQDN) or IP address of the AD server. For high availability (HA) environments, specify multiple AD servers using the same settings. If the first server cannot be reached, connections to succeeding ones are attempted in order.
  4. For Provider-specific Parameters enter/select the following, as appropriate:
    • Groups Search DN - The AD Distinguished Name (DN) path for the RBAC Groups Organizational Unit (OU)
    • Users Search DN - The AD Distinguished Name (DN) path for the RBAC Users Organization Unit (OU)
    • Bind DN - The AD Distinguished Name (DN) path for the active server user that the Apstra server will connect as
    • Password - The AD server user password for Apstra server to connect as
    • Encryption - None, SSL/TLS or STARTTLS
    • Advanced Config
      • Timeout (seconds)
      • Username Attribute Name - The AD attribute from the user entry that the Apstra server uses for authentication. (usually cn or uid)
      • User Search Attribute Name
      • User First Name Attribute Name
      • User Last Name Attribute Name
      • User Email Attribute Name
      • User Object Class Attribute Name
      • User Member Attribute Name
      • Group Name Attribute Name
      • Group DN Attribute Name
      • Group Search Attribute Name
      • Group Member Attribute Name
      • Group Member Mapping Attribute Name
      • Group Object Class Attribute Name
  5. You can Check provider parameters and Check login (to verify authentication with the remote user credentials) before creating the provider.
  6. Click Create to create the provider and return to the list view.

After configuring and activating a provider, you must map that provider to one or more user roles to give access permissions to users with those roles.

Creating TACACS+ Provider

Terminal Access Controller Access-Control Systems (TACACS+)

  1. From the left navigation menu, navigate to External Systems > Providers and click Create Provider.

  2. Enter a Name (64 characters or fewer), select TACACS+, and if you want TACACS+ to be the active provider, toggle on Active?.

  3. For Connection Settings, enter/select the following:

    • Port - The TCP port used by the server, usually 49
    • Hostname FQDN IP(s) - The fully qualified domain name (FQDN) or IP address of the TACACS+ server. For high availability (HA) environments, specify multiple TACACS+ servers using the same settings. If the first server cannot be reached, connections to succeeding ones are attempted in order.
  4. For Provider-specific Parameters enter/select the following, as appropriate:

    • Shared Key - shared key configured on the server

      Caution

      Shared key is not displayed when editing a configured TACACS+ provider. If you do not change it, the previously configured shared key is retained. If you test the provider and you have not re-entered the shared key, a null shared key is used for the test and may not work.

    • Auth Mode - Authentication mode - ASCII (clear-text), PAP (Password Authentication Protocol), or CHAP (Challenge-Handshake Authentication Protocol)

  5. You can Check provider parameters and Check login (to verify authentication with the remote user credentials) before creating the provider.

  6. Click Create to create the provider and return to the list view.

Configuring TACACS+ Provider

To authorize Apstra users via a TACACS+ provider, the TACACS+ server must be configured to properly return an apstra-group attribute. This attribute must be mapped to a defined Apstra Role. The example configuration below is for the open-source tac_plus TACACS+ server.

user = jdoe {
    default service = permit
    name = "John Doe"
    member = admin
    login = des LQqpIWvpxDXDw
}

group = admin {
    service = exec {
        priv-lvl = 15
    }
    cmd=show {
        permit .*
    }
    service = Apstra-exec {
        default attribute = permit
        priv-lvl = 15
        apstra-group = apstra-admins
    }
}

The apstra-admins group must be mapped to a defined Apstra Role.

After configuring and activating a provider, you must map that provider to one or more user roles to give access permissions to users with those roles. access.

Creating RADIUS Provider

Remote Authentication Dial-In User Service (RADIUS). See below for limitations.

  1. From the left navigation menu, navigate to External Systems > Providers and click Create Provider.

  2. Enter a Name (64 characters or fewer), select RADIUS, and if you want RADIUS to be the active provider, toggle on Active?.

  3. For Connection Settings, enter/select the following:

    • Port - The TCP port used by the server, default is 1812 as specified in RFC 2865.
    • Hostname FQDN IP(s) - The fully qualified domain name (FQDN) or IP address of the RADIUS server. For high availability (HA) environments, specify multiple RADIUS servers using the same settings. If the first server cannot be reached, connections to succeeding ones are attempted in order.
  4. For Provider-specific Parameters enter/select the following, as appropriate:

    • Shared Key (64 characters or fewer) - shared key configured on the server

      Caution

      Shared key is not displayed when editing a configured RADIUS provider. If you do not change it, the previously configured shared key is retained. If you test the provider and you have not re-entered the shared key, a null shared key is used for the test and may not work.

      An example of a pre-shared key configuration that tests successfully with Apstra is from Ubuntu FreeRADIUS (an open source RADIUS server). The Shared Key as given in the RADIUS server configuration must be provided in Apstra.

      home_server localhost {
      ipaddr = 127.0.0.1
      port = 1812
      type = "auth"
      secret = "testing123"
      response_window = 20
      max_outstanding = 65536
      
    • Advanced Config

      • Group Name Attribute Name - To tell Apstra which role a user belongs to, the RADIUS server must specify the users’ group. The user group information must be specified with Framed-Filter-ID as the attribute. It is used to assign users to different RADIUS groups.

        For example, the FreeRADIUS config below specifies the Framed-Filter-ID attribute to be freerad. In this case, when mapping later, you would enter freerad for the Provider Group.

      /etc/freeradius/users
             freerad Cleartext-Password := "testing123"
             Framed-Filter-Id = "freerad"
      

      So that the user can be mapped to an existing group in the Apstra environment, the RADIUS server must return the Apstra group name as part of the authentication response.

      Warning

      If the group is unmapped, users cannot log in.

    • Timeout (seconds) - Defaults to 30 seconds

After configuring and activating a provider, you must map that provider to one or more user roles to give permissions to users with those roles. access.

RADIUS Limitations

  • No support for changing the RADIUS user’s password on a remote RADIUS server.
  • RADIUS authentication does not control Linux user login via SSH.
  • No support for group role-mapping changes.
  • Nested groups are not allowed. You must explicitly assign each group to a role.
  • When a user logs in, only username and password are required for authenticating against the remote RADIUS server. Log in credentials are not cached. Therefore, when a user logs in, a connection between Apstra and the remote RADIUS server is required.

Editing Provider

Caution

Any users who are logged into Apstra when a setting is changed in an active RBAC provider, are immediately logged out without notification. To continue, the user must log back into the Apstra server. This does not affect users who are defined locally on the Apstra server (for example, admin).

  1. Either from the list view (External Systems > Providers) or the details view, click the Edit button for the provider to edit.
  2. Make your changes.
  3. Click Update (bottom-right) to edit the provider and return to the list view.

Deleting Provider

  1. Either from the list view (External Systems > Providers) or the details view, click the Delete button for the provider to delete.
  2. Click Delete to delete the provider and return to the list view.

Provider Role Mapping

After configuring an RBAC provider, you must map the provider to one or more user roles to give access permissions to users with those roles. You can create, edit and delete provider role mappings, as needed. Other details to be aware of include the following:

  • Only one provider can be active at a time.
  • You can map more than one Apstra role to the same provider group (new in version 4.0).
  • When the same username exists both locally and in the RBAC provider, the local user is used to authenticate login attempts.
  • Changing users with the web-based RBAC feature does not modify accounts on the Apstra server VM. To change these credentials, use standard Linux CLI commands: “useradd”, “usermod”, “userdel”, “passwd”.

From the left navigation menu, navigate to External Systems > Providers > Provider Role Mapping to go to provider role mapping.

_images/provider_role_mapping_401.png

Creating Role Map

  1. From the left navigation menu, navigate to External Systems > Providers > Provider Role Mapping and click the Edit button (top-right).

  2. Click Add mapping, select a role from the drop-down list, then enter a provider group. The following is an example for mapping the apstra-admins group that was configured in the TACACS+ configuration above.

    _images/role_map_create_401.png

    Tip

    To see user role details, navigate to Platform > User Management > Roles. From there, you can also create new roles, as needed.

  3. To add another role mapping, click Add mapping and select an Apstra Role and Provider Group. You can have more than one role associated with the same provider group.

  4. Click Update to create the role map. If the provider that you mapped is the active provider, then users with the mapped roles can log in with their usernames and passwords defined in the RBAC server.

Editing Role Map

Caution

Changing role mappings for an active provider causes all remotely logged in users to be logged out (because the session tokens are cleared when changes are made). Users will need to log back into the system. This includes the user admin, if admin is not logged in locally.

  1. From the left navigation menu, navigate to External Systems > Providers > Provider Role Mapping and click the Edit button (top-right).
  2. Edit role mapping as needed.
  3. Click Update to update the role map.

Deleting Role Map

  1. From the list view (External Systems > Providers > Provider Role Mapping) click the Edit button (top-right), then click the X next to the mapping to delete.
  2. Click Update to update the role map.