UTD Authorization Migration to Okta for ISR

Table 1. Feature history

Feature name

Release information

Description

UTD Authorization Migration to Okta for ISR

Cisco IOS XE Release 26.2.1

This feature modernizes how Cisco Unified Threat Defense (UTD) on Cisco IOS XE routers in autonomous mode authenticates with Cisco Automated Software Distribution (ASD) servers to download automated threat-inspection and IPS signature updates.

Cisco UTD OAuth 2.0 Device Authorization

In previous releases of Cisco IOS XE, UTD in Autonomous Mode utilized customer Cisco.com (CCO) credentials (username and password) to authenticate against legacy SSO services (cloudsso.cisco.com) for automated software and signature package downloads from Cisco Automated Software Distribution (ASD) APIs (api.cisco.com/software/).

Starting with this release, authentication migrates to Okta (id.cisco.com) using an OAuth 2.0 Device Authorization Flow. Individual CCO usernames and passwords are replaced by a cryptographic refresh-token.

Key architecture and benefits

  • No Cleartext Credentials: Routers no longer store user account passwords. The refresh-token is securely encrypted in the Cisco IOS XE Configuration Database (CDB) using Cisco Type 6 encryption.

  • Single Network-Wide Authorization: The administrator performs the browser-based authorization workflow only once on any single router hosting UTD. The resulting refresh-token can be deployed across all autonomous routers in the customer domain.

  • Rolling 90-Day Token Validity: The generated refresh-token has a 90-day validity window. Each time an automated periodic signature update (daily, weekly, or monthly) is performed, the token is automatically refreshed, extending its lifetime by another 90 days.

Device authorization flow

The device authorization workflow operates in the following sequence:

  1. The administrator issues the utd threat-inspection signature update generate refresh-token command on the router.

  2. The router contacts the Okta authorization server (id.cisco.com) using embedded client credentials and receives a Device Code, a User Code, and a Verification URI (For example, https://id.cisco.com/activate?user_code=HSPCDPRQ).

  3. The administrator opens the verification URI in a standard web browser, logs in using a generic Cisco account (non-cisco.com email address), and approves the device authorization request. The device code remains valid for 10 minutes (600 seconds).

  4. The administrator executes the generation command again on the router CLI. The router exchanges the authorized device code for a durable refresh-token.

  5. The administrator configures the refresh-token under the threat-inspection configuration mode on all target autonomous routers.

Deprecation notice


Note

Configuring CCO credentials using the legacy signature update server cisco username <username> password <password> syntax is deprecated. Entering or executing legacy credential commands generates a system logging (syslog) warning alerting the administrator to migrate to Okta refresh-tokens.

Configuring an Okta Refresh Token

The refresh-token generation requires a two-step CLI workflow on the router combined with web browser approval. Once generated, the same token is configured across all autonomous routers in your network.

Before you begin

  • Ensure the Cisco UTD container is installed and actively running on at least one router (show utd engine standard status).

  • Ensure the router has HTTPS connectivity to id.cisco.com and api.cisco.com.

  • Have access to a web browser and an authorized Cisco user account (generic non-cisco.com email).

Procedure

Step 1

Enter privileged EXEC mode on the router hosting the active UTD container.

Example:

Router# enable

Step 2

Initiate the OAuth 2.0 device authorization workflow to request a verification URL and user code.

Example:

Router# utd threat-inspection signature update generate refresh-token

The router contacts Okta and displays the verification URI with embedded user code:

Please visit https://id.cisco.com/activate?user_code=HSPCDPRQ and authenticate to approve the request.
Device code expires in 600 seconds (10 minutes).

Step 3

Open the provided verification URI in an external web browser and approve the authorization request.

Log in using your Cisco account credentials and confirm the displayed user code matching the CLI prompt. You must complete this approval within 10 minutes.

Step 4

Return to the router CLI and re-issue the generation command to retrieve the authorized refresh-token.

Example:

Router# utd threat-inspection signature update generate refresh-token

The router exchanges the authorized device code with Okta and displays the cryptographic refresh-token:

Refresh-Token generated successfully:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjFhMmIzYzRkNWU2Zi... [Token String]

Step 5

Enter global configuration mode on any autonomous router requiring UTD signature updates.

Example:

Router# configure terminal

Step 6

Navigate to the UTD threat-inspection configuration mode and configure the refresh-token.

  • Single-Tenancy:

    Router(config)# utd engine standard
Router(config-utd-eng-mngr)# threat-inspection
Router(config-utd-threat)# signature update server cisco refresh-token 0 eyJhbGciOiJSUzI1NiIs...
Router(config-utd-threat)# signature update occur-at daily 02:00
Router(config-utd-threat)# exit

  • Multi-Tenancy:

    Router(config)# utd engine standard multi-tenancy
Router(config-utd-eng-mngr)# utd global
Router(config-utd-global)# threat-inspection
Router(config-utd-threat)# signature update server cisco refresh-token 0 eyJhbGciOiJSUzI1NiIs...
Router(config-utd-threat)# signature update occur-at daily 02:00
Router(config-utd-threat)# exit

  • Unified Policy:

    Router(config)# utd engine standard unified-policy
Router(config-utd-eng-mngr)# utd global
Router(config-utd-global)# threat-inspection
Router(config-utd-threat)# signature update server cisco refresh-token 0 eyJhbGciOiJSUzI1NiIs...
Router(config-utd-threat)# signature update occur-at daily 02:00
Router(config-utd-threat)# exit

Step 7

Return to privileged EXEC mode and save the configuration.

Example:

Router(config-utd-threat)# end
Router# write memory

The router is now configured to securely retrieve signature updates using the Okta OAuth 2.0 refresh-token. Each scheduled update automatically extends the token's 90-day rolling validity.

Example: Verifying Signature Update Status

Router# show utd engine standard threat-inspection signature update status
UTD Threat-Inspection Signature Update:
  Status: Success
  Last Update: 2026-09-27 02:00:15 UTC
  Next Update: 2026-09-28 02:00:00 UTC
  Server: Cisco ASD (id.cisco.com)
  Version: 29.0.c.148

CLI Reference for UTD Okta Device Authorization

UTD Okta device authorization has these commands:

  • Privileged EXEC commands

  • Global configuration commands

  • Verification and monitoring commands

Table 2. Privileged EXEC commands
Command Mode Description
utd threat-inspection signature update generate refresh-token Privileged EXEC Initiates the OAuth 2.0 device authorization workflow to request a verification URL (1st run) and exchanges authorized device-code for the refresh-token (2nd run).
utd threat-inspection signature update server cisco refresh-token [0 | 6] <TOKEN> Privileged EXEC Attempts an immediate on-demand signature download using the supplied refresh-token. 0 specifies unencrypted; 6 specifies Type 6 encrypted.
utd threat-inspection signature update revoke refresh-token [0 | 6] <TOKEN> Privileged EXEC Revokes the specified refresh-token on the Okta authentication server (id.cisco.com), terminating its access validity.
Table 3. Global configuration commands
Command Configuration Mode Syntax Details
signature update server cisco refresh-token [0 | 6] <TOKEN> config-utd-threat Configures the Okta OAuth 2.0 refresh-token used for automated periodic signature updates. Token is saved in CDB using Type 6 encryption.
signature update occur-at {daily <hh:mm> | weekly <day> <hh:mm> | monthly <date> <hh:mm>} config-utd-threat Defines the recurrence interval and time for automated signature downloads.
Table 4. Verification and monitoring commands
Show command Output and security considerations
show running-config | show sd-routing run Displays the configured token in masked format: signature update server cisco refresh-token 6 <encrypted_hash>. Cleartext tokens are never displayed.
show utd engine standard status Verifies the operational status and health of the UTD inspection engine container.
show utd engine standard threat-inspection signature update status Displays signature download operational status, last success/failure timestamps, and ASD API response codes without exposing credential tokens.