H· Hawiyati Documentation
Application Integration

App Connector Catalog

Twenty pre-built SAML 2.0 and OIDC integration templates for popular self-hosted applications. The catalog is embedded in the Application Registration Wizard — select a connector, supply your deployment domain, review the pre-filled SAML endpoints and attribute mappings, and save.

Overview

The App Connector Catalog removes the need to hand-craft service provider metadata for common applications. Each catalog entry is a parameterised template — you fill in your deployment's domain, and Hawiyati generates the correct SAML metadata or OIDC client configuration and registers it in the SP registry in a single operation.

Templates are seeded from YAML files bundled in hawiyati-admin at startup. They are stored in the hawiyati_config.connector_templates database table and exposed through the Application Registration Wizard in the Admin Console and the REST API at /api/v1/catalog.

The catalog is integrated directly into the Application Registration Wizard. When you click Register Application in the Applications page, you choose between browsing the catalog (templates pre-fill all endpoints) or configuring a custom SAML 2.0 or OIDC integration from scratch. Both paths produce a standard SP registry entry.

All 20 connectors are for self-hosted applications.

No cloud accounts or vendor portals are required. Run Grafana, GitLab, Vault, and the other tools on your own infrastructure and point the connector at your instance domain.

Available connectors

The catalog ships with 20 connectors across six categories.

Monitoring

ConnectorProtocolNotes
GrafanaSAML 2.0Dashboard and alerting platform. SAML SSO via built-in auth proxy.
KibanaSAML 2.0Elasticsearch visualisation. Requires Elastic security plugin.
PrometheusOIDCMetrics server. OIDC reverse-proxy pattern via oauth2-proxy sidecar.

DevOps

ConnectorProtocolNotes
GitLab CE/EESAML 2.0Git hosting and CI/CD. SAML login under Admin > Settings > SSO.
JenkinsSAML 2.0Build automation server. Requires SAML plugin.
SonarQubeSAML 2.0Code quality platform. SAML configured in sonar.properties.
Nexus RepositorySAML 2.0Artifact repository. SAML IDP-initiated supported from v3.38.
GiteaOIDCLightweight Git hosting. OIDC OAuth app under Site Administration.

Productivity & Collaboration

ConnectorProtocolNotes
NextcloudSAML 2.0File sharing and groupware. SAML via SSO & SAML authentication app.
MattermostSAML 2.0Team messaging. SAML under System Console > Authentication.
Rocket.ChatSAML 2.0Open-source messaging. SAML under Administration > SAML.
SeafileSAML 2.0Document collaboration. SAML requires seahub_settings.py changes.
Jitsi MeetSAML 2.0Video conferencing. SAML via Prosody LDAP/SAML bridge.

Infrastructure

ConnectorProtocolNotes
RancherSAML 2.0Kubernetes management UI. SAML under Users & Authentication > Auth Provider.
Kubernetes DashboardOIDCK8s web UI. OIDC proxy or kube-apiserver OIDC flags.
PortainerOIDCContainer management. OAuth/OIDC under Settings > Authentication.

Security & Secrets

ConnectorProtocolNotes
HashiCorp VaultOIDCSecrets management. OIDC auth method under vault auth enable oidc.

Business & Documentation

ConnectorProtocolNotes
OdooSAML 2.0ERP platform. SAML via social-auth-saml module.
RedmineSAML 2.0Project management. SAML via omniauth-saml plugin.
ZammadSAML 2.0Help desk ticketing. SAML under Admin > Security > Third-party applications.
BookStackSAML 2.0Wiki platform. SAML under Settings > Authentication.

Registering an application from the catalog

The catalog is accessed through the Application Registration Wizard in the Admin Console. There is no standalone "App Catalog" sidebar page — catalog templates are a path inside the same wizard used for custom SAML and OIDC registrations.

Wizard walkthrough

  1. Open the wizard. Navigate to Identity & Access > Applications and click Register Application. The wizard opens on the Choose step.
  2. Browse App Catalog. Click the Browse App Catalog card. The wizard advances to the Pick App step, showing all connectors as tiles filterable by name and category.
  3. Select the connector. Click the application tile (e.g., Grafana, Odoo). A green checkmark marks the selection, and the Next button activates.
  4. General — name and domain. Enter the application display name and your deployment domain (host only, no scheme or trailing slash). The wizard shows a preview of the entity ID that will be generated from your domain.
  5. Sign-On — review SP endpoints. Entity ID, ACS URL, SLO URL, NameID format, and signing options are pre-filled from the template with your domain substituted. Edit any field that differs from your deployment.
  6. Attribute statements. User attributes to include in SAML assertions are pre-filled from the template. Add, remove, or change mappings as needed.
  7. Access & policy. Optionally assign an authentication policy, restrict accepted authentication methods, enable JIT provisioning, and require KYC verification for this application.
  8. Review and save. Inspect all settings. Click Save Application. Hawiyati creates the SP registry entry and displays the Setup Instructions panel with the IdP Metadata URL and SSO URL to paste into the application's SAML configuration.
Domain format

Enter the host and optional port only — for example grafana.example.org or gitlab.example.org:8443. Do not include https:// or a trailing slash. The connector template prepends the scheme and constructs the full endpoint URL.

After saving — configure the application

The Setup Instructions panel shows Hawiyati's IdP Metadata URL (https://<idp-host>/saml/metadata). Paste this URL into your application's SAML Identity Provider configuration. Applications that support metadata auto-import (Grafana, GitLab, Nextcloud) will download the certificate and SSO URL automatically.

Template parameters

Every connector template uses two standard parameters. Some connectors add a third.

ParameterRequiredDescription
domainYesHost (and optional port) where the application is running. Example: grafana.example.org.
displayNameYesHuman-readable name shown in the SP registry and the login chooser. Defaults to the connector name.
instanceIdOIDC onlySuffix appended to the generated OIDC client ID. Allows multiple instances of the same application to coexist. Defaults to the connector slug.

REST API

The catalog is also accessible programmatically via the Admin API. All endpoints require an authenticated admin session.

MethodPathDescription
GET/api/v1/catalogList all connector templates.
GET/api/v1/catalog/{slug}Get a single connector template by slug.
POST/api/v1/catalog/{slug}/enableEnable a connector. Body: {"domain":"…","displayName":"…"}. Returns 201 Created on success.

Example — enable Grafana via the API:

POST /api/v1/catalog/grafana/enable
Content-Type: application/json

{
  "domain": "grafana.example.org",
  "displayName": "Grafana"
}

Adding custom connectors

The catalog is extensible. To add a connector for an application not in the built-in list:

  1. Create a YAML file in hawiyati-admin/src/main/resources/connectors/ following the schema of an existing connector file. Use {{domain}} and {{displayName}} as placeholders.
  2. Restart hawiyati-admin. The ConnectorCatalogSeeder application runner picks up the new file on startup and inserts it into the database if the slug does not already exist.
  3. The connector immediately appears in the Admin Console catalog and the REST API.