{ "info": { "author": "Robert Bricheno", "author_email": "", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.1", "Programming Language :: Python :: 3.2", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "# ArubaOS XML API client\n\n[![Build Status](https://travis-ci.org/rbricheno/ArubaOS_XML_API.svg?branch=master)](https://travis-ci.org/rbricheno/client_of_redundant_servers)\n[![codecov](https://codecov.io/gh/rbricheno/ArubaOS_XML_API/branch/master/graph/badge.svg)](https://codecov.io/gh/rbricheno/client_of_redundant_servers)\n[![PyPI version](https://badge.fury.io/py/ArubaOS-XML-API.svg)](https://badge.fury.io/py/ArubaOS-XML-API)\n\nThis is a simple client for the [Aruba OS](http://www.arubanetworks.com/en-gb/products/networking/arubaos/)\n[XML API](http://www.arubanetworks.com/techdocs/ArubaOS_60/UserGuide/XML_API.php).\n\nNotably this allows programmatically changing the user name of clients in a \"captive portal\" role.\n\n## Installation\n```\npip install ArubaOS-XML-API\n```\n\n## Worked example\n\nHere we configure ```my_service```, a wireless service using a custom captive portal. Our captive portal server is a web\nserver which knows how to authenticate our local, 1st party usernames.\n\nWe configure two Aruba users, each with a different role to manage what it can talk to on the network via ACLs:\n\n * One called ```my_service-login``` with role ```my_service-login_role```. This has just the ability to connect to the\n network (with DHCP and DNS) and talk to the captive portal server.\n * Another called ```my_service-open``` with role ```my_service-open_role```. This grants the user full access to\n network resources.\n\nWe configure RADIUS servers in ```my_service-srvgrp``` (not otherwise described) to support the default AAA profile \nusing MAC authentication. The MAC authentication is configured to always succeed, and is used to record the start and\nend of sessions as well as RADIUS accounting information. We do not change the user account of users once they have\ncompleted MAC authentication, they should still be in \"my_service-login_role\" at this point. These RADIUS servers log\ninformation about sessions to a database server which is also accessible to the captive portal server.\n\nNext, the XML API is used to change the user ID of the connected client on login, from ```my_service-login``` to\n```my_service-open```. It is the responsibility of the captive portal server to track which login events and (1st party)\nusernames correspond to which sessions. The Aruba controller provides a lot of information to the captive portal server\nin the redirection URL when redirecting users to facilitate this. The following named parameters are available:\n\n\n| Parameter | Contents | Notes |\n|-----------|------------------------------------------------------------|------------------------------------------|\n| cmd | The action requested by the controller (?) | Seems to always be \"login\" |\n| switchip | The IP address of the Aruba controller serving the client. | Must be enabled in captive-portal config |\n| mac | Client device MAC address | |\n| ip | Client device IP address | |\n| essid | ESSID to which the client is connected | |\n| apname | Name of AP to which the client is connected | |\n| apgroup | Name of the group that contains the aforementioned AP | |\n| url | Original URL requested by the client before redirection | |\n\n\nThe captive portal server updates the database to add usernames to sessions being tracked by the RADIUS servers.\n\n### Aruba configuration\n\n**Configure Captive Portal server.** Assume ```https://login.wireless.example.com/``` is a web server running Python,\nwhich can authenticate our (1st party) users somehow, and make use of the ArubaOS-XML-API Python module.\n```\n(host) (config) #aaa authentication captive-portal my_service-cp\n(host) (Captive Portal Authentication Profile \"my_service-cp\") #login-page \"https://login.wireless.example.com/\"\n(host) (Captive Portal Authentication Profile \"my_service-cp\") #switchip-in-redirection-url\n```\nOptionally, **configure bandwidth limits** for unauthenticated users:\n```\n(host) (config) #aaa bandwidth-contract unauth-down_bw kbits 768\n(host) (config) #aaa bandwidth-contract unauth-up_bw kbits 256\n```\n**Define ACLs** for services that need to be accessible to unauthenticated users to allow them access to network\nservices and our captive portal server. Also create an ACL that allows full network access.\n\n(omitted for brevity, results in my_icmp-acl, my_dhcp-acl, my_dns-acl, my_service-captiveportal-acl and\nmy_service-open-acl).\n\n**Create users and roles.** Create a \"login\" user and role for users who are not yet logged in, with limited access to\nresources, and another \"open\" user and role for logged-in users with full access to network resources:\n```\n(host) (config) #local-userdb add username my_service-login password ... role my_service-login_role\n\n(host) (config) #user-role my_service-login_role\n(host) (config-role) #bw-contract unauth-up_bw per-user upstream\n(host) (config-role) #bw-contract unauth-down_bw per-user downstream\n(host) (config-role) #captive-portal \"my_service-cp\"\n(host) (config-role) #access-list session my_icmp-acl\n(host) (config-role) #access-list session my_dhcp-acl\n(host) (config-role) #access-list session my_dns-acl\n(host) (config-role) #access-list session my_service-captiveportal-acl\n\n(host) (config) #local-userdb add username my_service-open password T0pS3cr3T role my_service-open_role\n\n(host) (config) #user-role my_service-open_role\n(host) (config-role) #access-list session my_icmp-acl\n(host) (config-role) #access-list session my_dhcp-acl\n(host) (config-role) #access-list session my_dns-acl\n(host) (config-role) #access-list session my_service-open-acl\n```\n**Create an SSID** for the captive portal service:\n```\n(host) (config) #wlan ssid-profile my_service-ssid\n(host) (SSID Profile \"my_service-ssid\") # essid \"MyService\"\n```\n**Create an XML API server:**\n```\n(master-a) (config) #aaa xml-api server 10.11.12.13\n(master-a) (XML API Server \"10.11.12.13\") #key ArubaIsC00l\n```\n\n**Create an AAA profile** referencing the XML API server, and set a key for the XML API server\n```\n(host) (config) #aaa profile my_service-aaa\n(host) (AAA Profile \"my_service-aaa\") #initial-role \"my_service-login_role\"\n(host) (AAA Profile \"my_service-aaa\") #mac-default-role \"my_service-login_role\"\n(host) (AAA Profile \"my_service-aaa\") #mac-server-group \"my_service-srvgrp\"\n(host) (AAA Profile \"my_service-aaa\") #radius-accounting \"my_service-srvgrp\"\n(host) (AAA Profile \"my_service-aaa\") #radius-interim-accounting\n(host) (AAA Profile \"my_service-aaa\") #enforce-dhcp\n(host) (AAA Profile \"my_service-aaa\") #xml-api-server 10.11.12.13\n```\n**Create a virtual AP** for the new SSID using this AAA profile\n```\n(host) (config) #wlan virtual-ap \"my_service-vap\"\n(host) (Virtual AP profile \"my_service-vap\") #aaa-profile \"my_service-aaa\"\n(host) (Virtual AP profile \"my_service-vap\") #ssid-profile \"my_service-ssid\"\n(host) (Virtual AP profile \"my_service-vap\") #vlan ...\n(host) (Virtual AP profile \"my_service-vap\") #broadcast-filter all\n```\n\n### Python code on captive portal server\nNow we can finally write Python to record logins and update the user via the XML API:\n\nThe \"authenticate\" function is passed the 1st party username of the identified user, and the URL provided by the Aruba\ncontroller which redirected the user. \n```python\nfrom ArubaOS_XML_API import aruba_cmd\nfrom my_database_functions import database_update_session # You get to write this yourself.\nimport requests\n\ntarget_user = \"my_service-open\"\ntarget_user_pass = \"T0pS3cr3T\"\naruba_key = \"ArubaIsC00l\"\naruba_key_type = \"cleartext\"\n\ndef authenticate(our_username, aruba_url):\n query = requests.utils.urlparse(aruba_url).query\n params = dict(x.split('=') for x in query.split('&'))\n database_update_session(our_username, params['mac'], params['ip'])\n aruba_result = aruba_cmd(\"user_authenticate\", params['ip'], params['switchip'],\n target_user, target_user_pass, aruba_key, aruba_key_type)\n # if aruba_result['status'] == \"Ok\":\n # success = True\n```\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/rbricheno/ArubaOS_XML_API", "keywords": "aruba arubaos xml api", "license": "", "maintainer": "", "maintainer_email": "", "name": "ArubaOS-XML-API", "package_url": "https://pypi.org/project/ArubaOS-XML-API/", "platform": "", "project_url": "https://pypi.org/project/ArubaOS-XML-API/", "project_urls": { "Bug Reports": "https://github.com/rbricheno/ArubaOS_XML_API/issues", "Homepage": "https://github.com/rbricheno/ArubaOS_XML_API", "Source": "https://github.com/rbricheno/ArubaOS_XML_API" }, "release_url": "https://pypi.org/project/ArubaOS-XML-API/0.2/", "requires_dist": null, "requires_python": "", "summary": "Client of the ArubaOS XML API", "version": "0.2" }, "last_serial": 3844904, "releases": { "0.1": [ { "comment_text": "", "digests": { "md5": "f7e39ba8735d70fc20c0c6f920cc5acf", "sha256": "ab67d18ab61f44db2020b8e0a603d332a67ea0d4ed4f03e1f3de012fc4be69b0" }, "downloads": -1, "filename": "ArubaOS_XML_API-0.1-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "f7e39ba8735d70fc20c0c6f920cc5acf", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 3257, "upload_time": "2018-05-02T16:57:50", "url": "https://files.pythonhosted.org/packages/35/a0/de2a8f0762a361a9a25ea37fef75a43bf2ed3e8d79ffb950fda5f021f864/ArubaOS_XML_API-0.1-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c828c4040e2f75049f75c0c12bfe8d42", "sha256": "445ab1bab75fbdfb739a22462f0c91b4f6145930641dceac99b248f945ace061" }, "downloads": -1, "filename": "ArubaOS_XML_API-0.1.tar.gz", "has_sig": false, "md5_digest": "c828c4040e2f75049f75c0c12bfe8d42", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 2315, "upload_time": "2018-05-02T16:57:51", "url": "https://files.pythonhosted.org/packages/de/85/f7949c598dd7273bb8415a54e840fbf1e50fc7c3d52e5aa43cffa28804e1/ArubaOS_XML_API-0.1.tar.gz" } ], "0.2": [ { "comment_text": "", "digests": { "md5": "f222c63c9984c6060ccc3e93edc56a18", "sha256": "4b46fe4f4761deb29777b27e59a909cc56b771e04ecba2815b949bd0a42fd5a9" }, "downloads": -1, "filename": "ArubaOS_XML_API-0.2-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "f222c63c9984c6060ccc3e93edc56a18", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 5788, "upload_time": "2018-05-08T17:26:03", "url": "https://files.pythonhosted.org/packages/4d/48/b3b942b802402398af5c57ed70f79cb310f2e6cc87320ff401e837719b5b/ArubaOS_XML_API-0.2-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "d68e6cf0e2ab8c8b0851d1b94948cb4b", "sha256": "2012d895a5c71e50a648cd0fd23864475d2e8d509af68514803b85f1bc735663" }, "downloads": -1, "filename": "ArubaOS_XML_API-0.2.tar.gz", "has_sig": false, "md5_digest": "d68e6cf0e2ab8c8b0851d1b94948cb4b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 5462, "upload_time": "2018-05-08T17:26:04", "url": "https://files.pythonhosted.org/packages/c1/95/3c8e0a1c05014a5642dc6de1ecb8c6425ec224c7300fb1a5e601159449cb/ArubaOS_XML_API-0.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "f222c63c9984c6060ccc3e93edc56a18", "sha256": "4b46fe4f4761deb29777b27e59a909cc56b771e04ecba2815b949bd0a42fd5a9" }, "downloads": -1, "filename": "ArubaOS_XML_API-0.2-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "f222c63c9984c6060ccc3e93edc56a18", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 5788, "upload_time": "2018-05-08T17:26:03", "url": "https://files.pythonhosted.org/packages/4d/48/b3b942b802402398af5c57ed70f79cb310f2e6cc87320ff401e837719b5b/ArubaOS_XML_API-0.2-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "d68e6cf0e2ab8c8b0851d1b94948cb4b", "sha256": "2012d895a5c71e50a648cd0fd23864475d2e8d509af68514803b85f1bc735663" }, "downloads": -1, "filename": "ArubaOS_XML_API-0.2.tar.gz", "has_sig": false, "md5_digest": "d68e6cf0e2ab8c8b0851d1b94948cb4b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 5462, "upload_time": "2018-05-08T17:26:04", "url": "https://files.pythonhosted.org/packages/c1/95/3c8e0a1c05014a5642dc6de1ecb8c6425ec224c7300fb1a5e601159449cb/ArubaOS_XML_API-0.2.tar.gz" } ] }