Read-only API access with a user name, password and URL.
This guide shows how to connect Cisco Catalyst Center to NetOp with three values: the Catalyst Center URL, and the user name and password of a read-only user.
Overview
NetOp connects to Cisco Catalyst Center with three values: the Catalyst Center Url, and the User Name and Password of a dedicated read-only user. NetOp uses them to request API tokens from Catalyst Center on its own, so you do not create or paste a token in NetOp. Because the user is read-only, NetOp can read your network data but cannot change Catalyst Center or any device it manages.
Steps 1 to 4 happen in Catalyst Center. Step 5 happens in the NetOp dashboard.
Steps 1 to 4 happen in Catalyst Center. Step 5 happens in the NetOp dashboard.
The three values NetOp needs
| Field in NetOp | Example | Where you get it |
|---|---|---|
| User Name | netop-api-ro |
Step 2 |
| Password | The password you set for that user | Step 2 |
| Url |
https://catalyst.example.com or https://10.10.10.181
|
Step 1 |
Before you begin
Check these four points first.
- Catalyst Center administrator access. You can log in with a user that has SUPER-ADMIN-ROLE. Only this role can create users.
- API enabled. The Catalyst Center Platform application and the REST API bundle are enabled (Step 3).
- Network path. NetOp can reach the Catalyst Center URL over HTTPS on TCP port 443.
- NetOp access. You can log in to the NetOp dashboard and open or create a tenant in your organization (Step 5).
Step 1: Find your Catalyst Center URL
The Url field in NetOp takes the same address you type into your browser to open the Catalyst Center GUI. You can use the FQDN or the IP address.
- Log in to Catalyst Center in your browser.
- Copy the address from the browser bar and keep only the scheme and host, for example
https://catalyst.example.comorhttps://10.10.10.181. Leave off any path after the host. - If you run a multi-node cluster, use the cluster virtual IP address or the FQDN that resolves to it, not the address of a single node.
Step 2: Create a read-only user
NetOp signs in to Catalyst Center as this user, so the user's role decides what NetOp can do. Create a dedicated user with the built-in OBSERVER-ROLE, which Cisco defines as view-only: it cannot access any function that configures or controls Catalyst Center or the devices it manages.
Where to click in Catalyst Center, from the main menu to a saved read-only user
Where to click in Catalyst Center, from the main menu to a saved read-only user
- Log in to Catalyst Center as a user with SUPER-ADMIN-ROLE.
- Click the Menu icon (three lines, top left) and choose System > Users & Roles > User Management.
- Click Add. The Create Internal User pane opens.
- Fill in the fields:
- First Name: NetOp
- Last Name: Integration
- Email: a shared team mailbox you monitor
-
Username:
netop-api-ro(or your own naming standard)
- Under Role List, choose OBSERVER-ROLE.
- Enter a strong password, confirm it, and click Save. Keep the user name and password at hand: you enter both in NetOp in Step 5.
- Log in once as
netop-api-roin a private browser window to confirm the account works. If Catalyst Center asks this user to set a new password, set it and use the new one.
Step 3: Confirm the REST API is enabled
The API is ready when Menu > Platform > Developer Toolkit opens and lists the Catalyst Center APIs.
- Click the Menu icon and choose Platform > Developer Toolkit.
- If you see the API list, grouped by areas such as Authentication, Sites and Devices, the API is enabled. Continue to Step 4.
- If Platform is missing from the menu, a SUPER-ADMIN-ROLE user must install the Catalyst Center Platform application.
- If Platform exists but Developer Toolkit does not, a SUPER-ADMIN-ROLE user must enable the REST API bundle under Platform > Manage > Bundles, then wait four minutes before the first API request.
Step 4: Test the read-only access
This optional test confirms that netop-api-ro can sign in to the API and get a token, which is what NetOp does in the background after Step 5. You do not paste the test token anywhere. Use either method below.
Method 1: Developer Toolkit in the Catalyst Center GUI
- Log in to Catalyst Center as
netop-api-ro. - Choose Menu > Platform > Developer Toolkit.
- In the left menu, choose Authentication > Authentication API. The page shows the endpoint
POST /dna/system/api/v1/auth/token. - Run the request from the Toolkit.
- Check that the response contains a
Tokenvalue, a long string that starts witheyJ. If it does, the user, the password and the API are ready for NetOp.
Method 2: curl
Run this from any machine that can reach Catalyst Center. Give only the username, and curl will prompt for the password, so it is not saved in your shell history.
curl -k -X POST "https://catalyst.example.com/dna/system/api/v1/auth/token" \ -H "Content-Type: application/json" \ -u "netop-api-ro"
Expected reply:
{"Token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}
A reply with a Token value means the test passed. The test token expires after 1 hour. The -k flag skips certificate validation on the machine you run the test from.
Keep the password safe. Do not send it by email or chat. Type it directly into the Password field in NetOp in Step 5.
Step 5: Add the integration in NetOp
In NetOp, the integration lives under a tenant of your organization: Organization > Tenant > Integrations > Cisco Catalyst Center.
Where to click in NetOp, from your organization to the saved integration
Where to click in NetOp, from your organization to the saved integration
- Log in to the NetOp dashboard at production.opscenter.cloud.
- Open your organization. The organization represents your company. If it does not exist yet, create it first.
- Under the organization, create a tenant, or open the tenant this Catalyst Center belongs to. The breadcrumb at the top shows where you are, for example Netop > NetopOrganization > NetopLabs.
-
Under the tenant, click Integrations in the left sidebar.
The tenant view: the breadcrumb shows the organization and the tenant, and Integrations is in the left sidebar.
-
On the Datasources tab, click the Cisco Catalyst Center tile.
The Datasources tab lists the supported vendors. The Cisco Catalyst Center tile is highlighted.
The Datasources tab lists the supported vendors. The Cisco Catalyst Center tile is highlighted.
-
In the New Cisco Catalyst Center Integration window, fill in the three required fields:
-
User Name:
netop-api-ro, the user from Step 2 - Password: the password of that user
-
Url: the address from Step 1, for example
https://catalyst.example.com
The New Cisco Catalyst Center Integration window
The New Cisco Catalyst Center Integration window
-
User Name:
- Leave Enabled selected and click SAVE. SAVE becomes available once the three required fields are filled in.
Security and removing access
NetOp can only read, because it signs in as netop-api-ro, and OBSERVER-ROLE cannot configure or control Catalyst Center or any managed device.
- Dedicated user. NetOp activity stays separate from your administrators' activity in Catalyst Center.
- Encrypted transport. NetOp talks to Catalyst Center over HTTPS only.
- Short-lived tokens. Catalyst Center issues each API token for 1 hour, and every token carries only the read-only permissions of the user.
-
Password changes. If you change or reset the password of
netop-api-ro, update the Password field of the integration in NetOp. If your Catalyst Center enforces password expiry, plan the change before the expiry date. -
Removing access. Delete the Cisco Catalyst Center integration in NetOp, then delete
netop-api-roin System > Users & Roles > User Management.
Troubleshooting
Most problems come from the credentials, the network path, or the user's role.
| Symptom | Likely cause | What to do |
|---|---|---|
| NetOp cannot sign in to Catalyst Center | Wrong user name or password, or the user is locked or its password expired | Log in to the GUI as netop-api-ro to check, then update the Password field in NetOp |
| 401 Unauthorized in the Step 4 test | Wrong user name or password | Check both values and reset the password if needed |
| 404 Not Found in the Step 4 test | Older Catalyst Center release | Use /api/system/v1/auth/token instead |
| Some data is missing in NetOp | The user has no read access to that area | Make sure the user has OBSERVER-ROLE |
| No Platform or Developer Toolkit in the menu | Platform application or REST API bundle not enabled | Follow Step 3 |
| NetOp cannot connect (timeout) | A firewall, NAT rule or Catalyst Center IP access control blocks NetOp | Allow HTTPS on TCP 443 from NetOp to the Catalyst Center URL |
| Certificate error in NetOp | The URL does not match the name on the Catalyst Center certificate | Use the FQDN that appears on the certificate |
| The integration worked, then stopped | The password of netop-api-ro changed or expired, or the user was deleted |
Update the Password field in NetOp, or create the user again (Step 2) |
Cisco references
- Catalyst Center API: Authentication
- Authentication API reference, release 2.3.7.9
- API Quickstart: Developer Toolkit and REST API bundle
- Getting Started: base URL and API paths by release
- Cisco TAC: Understand and Use Catalyst Center APIs (Developer Toolkit screenshots)
- Cisco Catalyst Center Administrator Guide for your release, chapter "Manage Users"
Comments
0 comments
Please sign in to leave a comment.