Configure User Authentication on Docker

The Sensor Management web user interface only supports ZITADEL-based user authentication.

This section explains how to log in to Sensor Management Docker using a ZITADEL account.

Configure ZITADEL Before Logging In

ZITADEL is the Identity Infrastructure for Developers.

Refer to ZITADEL's documentation for details.

Reference version: 4.15.1

Creating the Organization on the ZITADEL server

Refer to Organizations for details.

Prerequisites

• User can access ZITADEL Console.
• User has permission to create/manage organizations, for example INSTANCE_OWNER.
• ZITADEL URL is available, for example:

https://<zitadel-domain>/ui/console

Steps

1. Open supported browser and access ZITADEL Console:

https://<zitadel-domain>/ui/console

2. Log in to ZITADEL Console.
   Log in with an administrator account.

3. Open Organization Menu.

   a. In the top header, click the Organization dropdown.
   b. Select + New Organization.

4. Input Organization Information.

   a. Enter the organization name.

Example: Orchestrator

b. Select the initial administrator option:

Current User: Use the currently logged-in user as the organization manager.

New Account: Create a new user account to manage this organization.

Recommended option: Current User

5. Create Organization.

   a. Click Create.
   b. Wait until the organization is created successfully.
   c. The new organization should appear in the organization list/dropdown.

Creating the ZITADEL Project: Manage Apps, Services & Roles

Refer to ZITADEL Projects: Manage Apps, Services & Roles for details.

The idea of projects is to have a vessel for all components who are closely related to each other. Multiple projects can exist within an organization.

All applications within a project share the same roles, grants, and role assignments:

• Applications initiate the authorization flow. They could be a web application and a mobile application that share the same roles.
• Roles define the access rights of a project and can be assigned to users.
• Role Assignments define the association between users and their roles within a project.

A Project is the vessel that holds your Applications and Roles. It defines the security context for a specific software solution.

Create a Project

1. Navigate to your Organization in the Console.
2. Go to Projects.
3. Click the Create New Project button.
   
4. Input your Project name.
5. Click the Continue button.
6. Check on Return user roles during authentication option.
7. Click Save button.

Creating the ZITADEL Applications

Refer to Applications for details.

Applications are the entry point to your Project Overview. Users either log in to one of your applications (Frontend) and interact with them directly or use one of your APIs (Backend).

All applications within a project share the same Roles and Role Assignments. This means you define a role once (e.g., admin) on the Project level, and it applies across all your web, mobile, and API applications.

Create an Application

1. Navigate to your Project in the Management Console and select your application.
   

2. Click the New button and select your Application Type: WEB.
   

3. Click Continue button.

4. Select the Authentication Method: PKCE.
   

5. Input the redirect URI is where the ZITADEL authorization server redirects the user after they have been authenticated.

   • Redirect URIs: https://<server_IP>/businessweb/login/oauth2/code/zitadel
   • Post Logout URLs: https://<server_IP>/businessweb

6. Click Continue button.

7. Click Create button.

Application Settings

After creating an application, you can modify its settings.

1. OIDC Compliance: The Management Console checks if your settings are OIDC compliant and shows tasks for completion if anything is missing.

   • Response Types: Code
   • Authentication Method: None
   • Grant Types: Authorization Code and Refresh Token
   • Check on Refresh Token

2. Token Settings

• Using the Token with

  • Auth Token Type: JWT

  • All three following settings must be checked

    • Add user roles to the access token
    • User roles inside ID Token
    • User Info inside ID Token

Creating the Roles in the Project

After the ZITADEL server authenticates a user, it sends Cisco Crosswork Assurance Sensor Management a list of roles for the user. The user roles must be among the roles recognized by Cisco Crosswork Assurance Sensor Management. See "Managing User Accounts".

Your ZITADEL server must be configured to send the list of roles to Cisco Crosswork Assurance Sensor Management after authentication.

To add roles, navigate to the section Roles and create those new roles with the following values:

1. Click New button.
   
2. Input all information below to create 6 supported Roles.

3. Click Save.

All 6 supported roles will be displayed.

Configuring ZITADEL to Add Authorizations for the Project

If ZITADEL sends any roles that Cisco Crosswork Assurance Sensor Management does not recognize, the login to the Cisco Crosswork Assurance Sensor Management will fail. If the resulting list of roles is empty or if ZITADEL sends an empty list, Sensor Management will deny access to the user.

At authentication time, the ZITADEL user must be assigned one of the following roles below for the Roles Assignments configuration in the ZITADEL:

• ROLE_USER, ROLE_ADMIN
• ROLE_USER, ROLE_OPERATOR
• ROLE_USER, ROLE_FW_MGMT
• ROLE_USER, ROLE_VIEWER
• ROLE_USER, ROLE_WS

Obtaining OAuth/OIDC Endpoints from ZITADEL

All standard OAuth/OIDC endpoints can be automatically discovered from the OpenID Connect Discovery document.

Before enabling ZITADEL authentication using the Cisco Crosswork Assurance Sensor Management CLI, ensure that the required OAuth/OIDC configuration values have been obtained from the ZITADEL server.

These values are used to configure the connection between Cisco Crosswork Assurance Sensor Management and ZITADEL, allowing users to authenticate through the OpenID Connect (OIDC) protocol.

The following parameters must be collected from the ZITADEL deployment before executing the authentication configuration commands.

Enable ZITADEL Authentication

The OAuth CLI enables configuration of OAuth 2.0 / OpenID Connect (OIDC) authentication for end users, including setting up the identity provider connection, authorization and token endpoints, role mapping, and remote authentication management.

1. Open an SSH terminal session to the Cisco Crosswork Assurance Sensor Management CLI on port 2200.
2. Log in as the skylight user.
3. Enter the command below to show current OAuth configuration:

oauth show

4. (Optional) If the ZITADEL server uses a self-signed certificate, import and trust the certificate:

certificate import trusted-cert-file <certificate_file> alias <alias_name>

5. Enter the commands below:

oauth edit enabled true
oauth edit client-id <client_id>
oauth edit project-id <project_id>
oauth edit issuer-location https://<zitadel_domain>
oauth edit authorization-uri https://<zitadel_domain>/oauth/v2/authorize
oauth edit token-uri https://<zitadel_domain>/oauth/v2/token
oauth edit user-info-uri https://<zitadel_domain>/oidc/v1/userinfo
oauth edit jwk-set-uri https://<zitadel_domain>/oauth/v2/keys

6. Enter the command below to show OAuth configuration again:

oauth show

7. Stop the Cisco Crosswork Assurance Sensor Management services by entering:

services stop

8. Start the Cisco Crosswork Assurance Sensor Management services by entering:

services start

Note: Wait about 10 minutes to ensure all services are healthy.

Log In Using a ZITADEL Account

Administrators define user accounts in the ZITADEL server. When you have your account, you can log in as explained below.

This section explains how to configure and log in to the Cisco Crosswork Assurance Sensor Management.

To log in to Sensor Management

1. Open a supported browser. See the list of "Supported Web Browsers".

2. Enter the following URL in the browser's address bar: https://<serverIPaddress>/businessweb
   The login dialog is displayed.
   

3. Click Remote Log in button.
   The login dialog is displayed.
   

4. Enter your ZITADEL Username and Password.

5. Click Next.

Automatic Creation of ZITADEL Users in Sensor Management

When a user logs in to Sensor Management using a ZITADEL account, a corresponding Sensor Management user account (with User Type set to OAUTH_JWT) is automatically created in the Sensor Management data store.

These OAUTH_JWT user accounts cannot be converted to LOCAL or RADIUS users in Sensor Management.

The Admin ▶ Users page displays operational data on ZITADEL authentication.