Accessing DX NetOps Spectrum APIs with Basic Authentication when SSO is Enabled

Products

• Network Observability

Issue/Introduction

We want to understand how to access DX NetOps Spectrum APIs using Basic Authentication when Single Sign-On (SSO) is enabled for the Spectrum environment.

Environment

DX NetOps Spectrum all versions.

Token Based Authentication DX NetOps 24.3.10 version and Higher

Cause

Even when Single Sign-On (SSO) is enabled for the Spectrum UI, it is still possible and often necessary to use Basic Authentication for programmatic and script-based access to Spectrum's REST APIs. The crucial difference is that Basic Authentication in this scenario relies on local Spectrum user credentials, not on your SSO identity. SSO primarily manages browser-based user logins, while local Basic Authentication provides a direct, machine-to-machine authentication method.

Resolution

When SSO is configured in Spectrum, it redirects standard browser-based login attempts to an external Identity Provider (IdP). However, for automated tasks, scripts, or integrations that interact directly with Spectrum's REST APIs, a mechanism to authenticate without browser redirects is required. DX NetOps Spectrum facilitates this by allowing Basic Authentication using credentials for users that are managed directly within Spectrum's local user database.

This means:

1. Local Spectrum Users are Key: You must use the username and password of a user account that has been created and exists directly within Spectrum's local user management system. If the user account/password is exclusively managed by your SSO provider and not replicated or created locally in Spectrum, Basic Authentication attempts will fail.
2. Permissions: The local Spectrum user account designated for API access must be granted the appropriate permissions and roles within Spectrum to perform the specific API operations you intend (e.g., read device data, create alarms, etc.). Adhere to the principle of least privilege.

How to Implement Basic Authentication for Spectrum APIs

Basic Authentication involves sending a specific HTTP header with your API request.

Step-by-Step Implementation:

1. Prepare Spectrum Local User Credentials:

   • Identify or create a dedicated local Spectrum user account (e.g., apiuser).
   • Ensure this user has a strong, secure password (e.g., apiP@ssw0rd!).
   • Verify that this user has the necessary permissions within Spectrum to execute the required API calls.

2. Construct the Authentication String:

   • Combine the username and password with a colon in between: username:password (e.g., apiuser:apiP@ssw0rd!).
   • Base64 encode this entire string.
     • Example (Linux/macOS command line): echo -n "apiuser:apiP@ssw0rd!" | base64
     • This will produce an encoded string, such as YXBpdXNlcjphcGlQcGFzc3cwcmQh.

3. Include the Authorization Header in your API Request:

   • Add an Authorization HTTP header to your API request.
   • The header value should start with Basic (note the space after Basic), followed by the Base64 encoded string from the previous step.
     • Example: Authorization: Basic YXBpdXNlcjphcGlQcGFzc3cwcmQh

Example using curl (a common command-line tool for making HTTP requests):

Let's assume you want to retrieve a list of devices from Spectrum.

# 1. Define your local Spectrum user credentials
#    (Replace with your actual Spectrum local username and a strong password)
SPECTRUM_USERNAME="apiuser"
SPECTRUM_PASSWORD="apiP@ssw0rd!"

# 2. Base64 encode the username:password string
#    Using 'printf -v' (Bash) or 'printf' and 'base64' to avoid unintended newlines
AUTH_STRING=$(printf "%s:%s" "$SPECTRUM_USERNAME" "$SPECTRUM_PASSWORD" | base64)

# 3. Construct your API request using curl
#    (Replace 'your_spectrum_host' with your Spectrum server's hostname or IP,
#     and '8443' with your actual HTTPS port if different.
#     Adjust the API endpoint to your specific requirement, e.g., /spectrum/rest/devices)

curl -X GET \
  "https://your_spectrum_host:8443/spectrum/rest/devices" \
  -H "Authorization: Basic $AUTH_STRING" \
  -H "Accept: application/json" \
  --insecure # Use --insecure ONLY for development/testing with self-signed certificates.
             # In production, ensure proper certificates are trusted.

Important Considerations and Best Practices:

• HTTPS is Mandatory: Always use https:// for all API calls when employing Basic Authentication. Sending credentials over unencrypted HTTP (http://) is a severe security risk, as Base64 encoding is not encryption and can be easily decoded.
• Dedicated API Users: Create specific local Spectrum user accounts solely for API access. These accounts should not be used for interactive logins.
• Least Privilege: Grant API users only the absolute minimum Spectrum privileges (roles and access) required to perform their intended tasks. This minimizes potential damage if the API credentials are compromised.
• Secure Password Management: Avoid embedding passwords directly into scripts. Use secure methods for managing and accessing credentials, such as:
  • Environment variables
  • Secret management tools (e.g., HashiCorp Vault, CyberArk)
  • Secure configuration files with appropriate file permissions
• Error Handling: Implement robust error handling in your integration code to gracefully manage HTTP status codes, especially:
  • 401 Unauthorised: Indicates incorrect credentials (username, password, or invalid Base64 encoding).
  • 403 Forbidden: Indicates the authenticated user lacks the necessary Spectrum permissions to access the requested resource or perform the action.
  • 404 Not Found: Incorrect API endpoint or resource does not exist.
• Alternative Authentication Methods: While Basic Authentication is functional, many DX NetOps Spectrum now offers more secure and flexible alternative i.e. Token based Authentication from 24.3.10 version & higher. This often provides better mechanisms for token revocation and avoid sending full credentials with every request. Please refer to the documentation for further information.
• Non-SAML User Config: Clients using Broadcom Spectrum REST APIs with Basic Authentication must add their non-SAML user accounts to the non-saml-config.xml file, located in the <SPECROOT>/tomcat/conf directory.