Single Sign-On Configuration

Waii provides flexible authentication options to support both interactive users accessing the web and command line interfaces and automated processes performing knowledge graph maintenance operations. This guide covers how to configure authentication for both scenarios within your deployment.

Key Authentication Concepts

Identity and Access

Federated Identity allows your organization's existing identity system to authenticate users for Waii. Single Sign-On (SSO) enables users to access Waii without separate credentials once authenticated.

Authentication Protocols

SAML 2.0 is an enterprise-grade, XML-based protocol ideal for large organizations. It handles both authentication and authorization in a single token.

OpenID Connect (OIDC) is built on OAuth 2.0, making it ideal for cloud-native deployments. It provides authentication through ID tokens while using OAuth 2.0's authorization flow.

OAuth 2.0 is an authorization framework used primarily for service-to-service and automated process authentication. It defines how applications obtain and use access tokens to access protected resources.

Token Types

JWT (JSON Web Tokens) are encoded tokens containing claims about the authenticated user and their permissions. They're self-contained, allowing services to verify the user's identity and permissions without additional lookups.

Access Tokens are short-lived credentials used to access protected resources. They can be JWTs or opaque tokens, depending on the implementation.

Refresh Tokens are long-lived credentials used to obtain new access tokens when they expire. They're securely stored by the application and exchanged for fresh access tokens without requiring user re-authentication.

Architecture

Waii operates within the enterprise network, centered around the Waii APIs which act as the authentication hub. These APIs manage tokens and credentials for all components - the web UI, CLI, and database scanner.

When users interact with the web UI, they authenticate through their enterprise identity provider using SAML or OIDC. The Waii APIs store the resulting refresh tokens and handle token renewal, ensuring smooth user sessions without repeated logins.

For automation needs, users can generate API keys through the UI. These keys are stored and managed by the Waii APIs, which map them to the appropriate user credentials for database access. This enables the CLI to provide a streamlined experience while maintaining security and audit capabilities.

The database scanner runs as a continuous service, requiring persistent access to the enterprise database. The Waii APIs manage its credentials and handle token renewal, eliminating the need for manual token management while maintaining security through regular rotation.

All credential storage and token exchanges are encrypted, with the Waii APIs maintaining a secure store of refresh tokens and managing their lifecycle. This centralized approach simplifies security auditing and enables features like token revocation and access monitoring.

Authentication Configuration Guide

SAML Configuration with Okta

Waii supports SAML-based SSO integrations. The following instructions detail how to configure Okta as your identity provider.

Okta Account & App Integration

1. Open your Okta Account

2. Switch to Admin Mode
   Log in to your Okta dashboard and access the admin settings.

3. Create a New App Integration

   • Navigate to Applications and select Create App Integration.
   • Choose SAML as the sign-on method.
   • Enter a name for the Waii application.

4. Configure SAML Settings

   • Single Sign-On URL: Enter your waii endpoint url (e.g., https://\<url where waii is hosted\>/saml2/callback) followed by /saml2/callback.
   • Audience URI (SP Entity ID): Use your base URL (e.g., https://\<url where waii is hosted\>/).
   • Application Username: Typically set to “Okta username”.
   • Attribute Statements: Configure the attribute as follows:
     • Name: waii.ai/roles
     • Name Format: Unspecified
     • Filter: Starts with: waii-

5. Enable Single Sign Out
   Configure the single sign-out as below (Logout Request url: https://\<url where waii is hosted\>/saml2/slo)

6. Assigning the Application to a Group
   • Create a group in Okta (via Directory → Groups → Add group). This group will serve as a role within Waii. Waii supports waii-trial-user, waii-user, waii-api-user, waii-admin-user, waii-org-admin-user, waii-super-admin-user, waii-trial-api-user roles. So you would need to create groups with these names based on your requirements. More about waii roles https://doc.waii.ai/python/docs/waii-user-roles
   • Assign the Waii application to the groups that you create.
   • Finally, add users to the groups via People → Assign People.

Waii SAML Configuration File

Create a configuration file (e.g., saml_config.yaml) with the following sample content. Replace the placeholder values with actual details from your Okta setup.

saml:
  sp_entity_id: "https://\<url where waii is hosted\>/"              # Use your domain where waii is hosted
  acs_url: "https://\<url where waii is hosted\>/saml2/callback"        # Assertion Consumer Service URL
  idp_entity_id: "YOUR_OKTA_ENTITY_ID"                    # Available in your Okta metadata
  idp_sso_url: "YOUR_OKTA_SSO_URL"                        # SSO endpoint from Okta
  idp_certificate_path: "YOUR_OKTA_IDP_CERTIFICATE_ABSOLUTE_PATH"            # Download from Okta metadata
  sp_private_key_path: "YOUR_SP_PRIVATE_KEY_ABSOLUTE_PATH"                   # Create using openssl/your preferred provider
  sp_certificate_path: "YOUR_SP_CERTIFICATE_ABSOLUTE_PATH"                   # Create using openssl/your preferred provider
  sp_logout_url: "https://\<url where waii is hosted\>/saml2/slo"        # Single Logout URL

Starting Waii with SAML Configuration

Launch Waii by pointing to your SAML configuration file. (Make sure you mount sp_private_key_path, sp_certificate_path, idp_certificate_path to your docker)

--saml_config_file_path saml_config.yaml --api_key_auth_enabled

OIDC Configuration

Identity Provider Configuration (Okta, Google, etc)

1. Create new OIDC application
2. Configure callback URL as {your-waii-domain}/oauth2/callback
3. Get client ID and secret
4. Assign appropriate users/groups

Configuration File: oidc_config.yaml

oidc:
	issuer: "https://your-oidc-provider"
	client_id: "\<client_id\>"
	client_secret: "\<client_secret\>"

Start Waii with the OIDC configuration

--oidc_config_file_path oidc_config.yaml

Database OAuth Configuration

Prerequisites

• OAuth provider client ID and secret
• Redirect URI for database OAuth callbacks

Configuration File

Create an oauth_config.yaml:

\<database_identifier\>:
	oauth_provider: "\<provider_name\>"
	redirect_uri: "https://your-waii-domain/oauth2/callback"
	client_id: "\<client_id\>"
	client_secret: "\<client_secret\>"

Start Waii with the OAuth configuration:

--oauth_config_file_path oauth_config.yaml