.png)
Duo Security Integration Guide
Connect Duo Security with enterprise systems through signed REST APIs, authentication workflows, scheduled log synchronization, and standards-based SSO flows.
Duo Security integration options at a glance
Duo Security, also branded Cisco Duo, provides REST-based Admin and Authentication APIs for users, phones, integrations, endpoints, logs, and authentication operations. API requests generally use an integration key, secret key, timestamp, and HMAC-based signature. Duo also supports SAML and OIDC-based authentication flows in applicable Duo SSO configurations. A general-purpose webhook mechanism for all events was not confirmed, so scheduled polling is the safer pattern for log synchronization. Martini can consume Duo APIs from workflows, generate signed requests using protected secrets, expose normalized REST APIs, paginate collections, transform payloads, and maintain checkpoints for reliable incremental synchronization.
| Integration point | Supported by Duo Security? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | The Duo Admin API manages Users, Phones, Integrations, Endpoints, logs, and related administrative resources. The Authentication API supports pre-authentication, authentication attempts, factor evaluation, and status checks. | Martini can consume Duo REST APIs from workflows, generate signed requests, process JSON responses, paginate collections, and expose normalized APIs for downstream systems. |
| Authentication | Yes | Duo API requests use an integration key, secret key, timestamp, and HMAC-based request signature. Applicable Duo SSO configurations can also use SAML or OIDC-based flows. | Martini can store secrets securely, construct signed requests, invoke authentication flows, and apply separate configuration for API signing versus SSO authorization. |
| Scheduled synchronization | Yes | Scheduled retrieval is appropriate for Duo Users, Endpoints, Trusted endpoints, administrative logs, and Authentication logs when event delivery is not available. | Martini can trigger workflows on a schedule, maintain timestamps or event checkpoints, use overlap windows, and deduplicate retrieved data. |
| Webhooks / outbound callbacks | Not confirmed | A general-purpose Duo webhook mechanism covering all administrative and authentication events was not confirmed. Product-specific callbacks should be verified separately if required. | Martini can receive webhook-style callbacks when a specific Duo product documents them, but the default design should use scheduled API polling. |
| Bulk / async / batch APIs | Limited | Duo documents collection and administrative operations, but a general bulk import/export or asynchronous batch API was not confirmed. | Martini can process collections in pages, schedule rate-aware batches, checkpoint progress, and retry transient failures. |
| SAML and OIDC flows | Yes | Duo SSO supports SAML-based SSO and OIDC-based flows in supported configurations. These are distinct from HMAC-signed Admin and Authentication API requests. | Martini can orchestrate standards-based API and workflow interactions around configured authentication flows and expose controlled APIs for normalized outcomes. |
| File / attachment APIs | Not confirmed | No general Duo file import, export, or attachment API was confirmed. Duo's primary integration model is API-based. | Martini can process files from other systems when needed, but should not assume files are a native Duo integration mechanism. |
| Database / analytics access | Not confirmed | Direct database access to Duo's hosted service was not confirmed. Audit and operational data should be obtained through documented APIs or separately configured logging integrations. | Martini can write normalized Duo data to an approved database or analytics target without requiring direct access to Duo's hosted database. |
How Duo Security exposes data and business events
Duo REST APIs
Duo's principal integration surface is its REST API family. The Admin API provides administrative resources such as Users, Phones, Integrations, Endpoints, and logs, while the Authentication API supports pre-authentication and authentication status operations. Responses are generally JSON and collection endpoints may require pagination.
Martini implementation pattern
Martini implementation pattern: create workflows that build the required request, generate the documented HMAC signature from protected configuration, call the applicable Duo endpoint, validate the response, and map the result to a canonical model or target API.
Implementation sequence
Duo Authentication API
The Duo Authentication API supports pre-authentication evaluation, authentication attempts, factor-related operations, and status checks. Authentication requests are security-sensitive and may result in approved, denied, or pending states.
Martini implementation pattern
Martini implementation pattern: expose a controlled Martini REST API, validate the incoming request, invoke Duo pre-authentication and the selected authentication operation, then poll or check status until a permitted terminal response or timeout is reached.
Implementation sequence
Duo Log Polling
Duo provides administrative and Authentication log resources through APIs. The reviewed material does not establish a general real-time event stream or universal webhook mechanism, so incremental scheduled retrieval is the recommended general pattern.
Martini implementation pattern
Martini implementation pattern: run a scheduled workflow, retrieve records after a persisted checkpoint with a small overlap window, deduplicate by event identifier or composite key, and forward normalized events to security or operational systems.
Implementation sequence
SAML and OIDC Flows
Duo supports SAML-based SSO and OIDC-based flows in applicable Duo SSO configurations. These standards-based flows are separate from HMAC-signed Admin API and Authentication API requests.
Martini implementation pattern
Martini implementation pattern: use a workflow or exposed API to coordinate the configured identity flow, keep provider-specific authorization settings separate from Duo API signing secrets, and normalize the resulting identity or access decision for downstream applications.
Implementation sequence
Common Duo Security integration patterns
Pattern 1: Synchronize Duo Users with an identity platform
When to use this pattern
Use this pattern when Duo user enrollment or status must be aligned with an authoritative directory, HR platform, or identity provider. The workflow can operate from Duo to the target system or provision approved changes in the reverse direction.
Integration direction
Example Mapping
| Duo Security Field | Canonical Field | Target Field |
|---|---|---|
| username | user.login | userPrincipalName |
| status | user.lifecycleStatus | accountEnabled |
| user.email |
Martini implementation pattern
A scheduled Martini workflow retrieves paginated Duo Users, resolves stable identifiers, validates required fields, and applies rules for active, disabled, and unenrolled users. It writes only approved changes, records a checkpoint, and routes failed records for retry or review.
Martini capabilities used
- scheduled workflows
- API consumption
- request signing
- data mapping
- business rules
- checkpointing
- error handling
Pattern 2: Expose a normalized Duo authentication API
When to use this pattern
Use this pattern when internal applications should call one controlled endpoint rather than implement Duo-specific signing, factor handling, and status polling themselves.
Integration direction
Example Mapping
| Duo Security Field | Canonical Field | Target Field |
|---|---|---|
| applicationRequestId | correlationId | Duo request correlation |
| username | subject.login | Duo username |
| authStatus | decision.status | approved, denied, or pending |
Martini implementation pattern
Martini exposes a secured REST API that validates the request, invokes Duo pre-authentication and the applicable Authentication API operation, checks pending status with an expiration policy, and returns a normalized response. It avoids blind retries because repeating an authentication request may create another attempt.
Martini capabilities used
- API exposure
- workflow orchestration
- API consumption
- security controls
- conditional routing
- timeouts
- error handling
Pattern 3: Forward Duo authentication logs to Splunk
When to use this pattern
Use this pattern when security operations need Duo authentication and administrative activity in a SIEM without repeatedly importing the entire historical log set.
Integration direction
Example Mapping
| Duo Security Field | Canonical Field | Target Field |
|---|---|---|
| eventId | securityEvent.id | event_id |
| timestamp | securityEvent.occurredAt | _time |
| result | securityEvent.outcome | action |
| username | securityEvent.subject | user |
Martini implementation pattern
A scheduled workflow retrieves log pages after the last checkpoint, applies an overlap period, deduplicates events, and transforms Duo fields to the Splunk event contract. Transient failures use bounded retries, while the checkpoint advances only after successful delivery.
Martini capabilities used
- scheduler triggers
- incremental retrieval
- pagination
- data transformation
- deduplication
- retry handling
- monitoring
Pattern 4: Reconcile Duo Endpoints with ServiceNow
When to use this pattern
Use this pattern when endpoint records in Duo need to be compared with asset or configuration data and discrepancies should create operational work for review.
Integration direction
Example Mapping
| Duo Security Field | Canonical Field | Target Field |
|---|---|---|
| endpointId | asset.externalId | cmdb_ci.u_duo_endpoint_id |
| hostname | asset.name | name |
| status | asset.complianceStatus | state |
| owner | asset.owner | assigned_to |
Martini implementation pattern
Martini retrieves Duo Endpoints or Trusted endpoints, matches stable identifiers to ServiceNow records, classifies stale or unmatched devices, and creates idempotent incidents or tasks. Destructive Duo changes are excluded unless an explicit approval rule permits them.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- comparison rules
- idempotent writes
- exception routing
- audit logging
Applications commonly integrated with Duo Security
Duo Security can participate in identity, access, security operations, and user-lifecycle workflows. The exact direction depends on which platform is the identity provider and how Duo is configured. Martini can orchestrate these relationships through Duo APIs, standards-based authentication flows, and the APIs of adjacent applications.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Microsoft Entra ID | Coordinate MFA and access decisions with Microsoft cloud identity workflows. | Microsoft Entra ID → Martini → Duo Security | Use workflows to exchange approved identity and access information, invoke relevant Duo operations, and apply tenant-specific business rules before updating either system. |
| Active Directory | Support directory-backed application protection and user enrollment or deprovisioning processes. | Active Directory → Martini → Duo Security | Retrieve authoritative user or group changes, map them to Duo Users, and use validation, checkpointing, and controlled update logic for lifecycle changes. |
| Okta | Coordinate MFA, SSO, and identity-provider responsibilities across enterprise applications. | Okta → Martini → Duo Security | Orchestrate SAML, OIDC, or application-level authentication flows where configured, while keeping provider-specific credentials and routing rules in protected configuration. |
| ServiceNow | Create incidents or tasks for failed authentication patterns, enrollment issues, and endpoint exceptions. | Duo Security → Martini → ServiceNow | Poll Duo logs or retrieve endpoint information, normalize events, apply severity and deduplication rules, and create or update ServiceNow work items. |
| Splunk | Forward authentication and administrative activity for security detection and investigation. | Duo Security → Martini → Splunk | Incrementally retrieve Duo Authentication logs and administrative logs, transform them into the target event model, and forward them with checkpoint and retry handling. |
| Salesforce | Protect Salesforce access with Duo MFA and coordinate user or access-status workflows. | Salesforce → Martini → Duo Security | Expose or consume controlled APIs that normalize authentication outcomes and synchronize eligible user-status changes according to the configured identity architecture. |
| Workday | Use HR lifecycle data to drive Duo enrollment, access, or deprovisioning workflows. | Workday → Martini → Duo Security | Schedule retrieval of worker changes, validate lifecycle state, map users to Duo Users, and apply explicit rules for enrollment, disablement, and exceptions. |
| Jira | Create operational work items for authentication incidents, enrollment exceptions, or endpoint remediation. | Duo Security → Martini → Jira | Poll and normalize Duo events or endpoint discrepancies, classify them with business rules, and create idempotent Jira issues with correlation data. |
How to build a Duo Security integration in Martini
Objective
Set up the Duo API configuration and protect credentials before implementing workflow logic.
Instructions in Martini
- Store the integration key and secret key in Martini secrets or protected environment configuration
- Synchronize the runtime clock because Duo signatures contain timestamps
- Select the API surface, tenant configuration, and minimum required permissions
- Keep API signing, SAML, and OIDC configuration separate
Objective
Select a trigger that matches the integration's timing and security requirements.
Instructions in Martini
- Use a scheduler for Users, Endpoints, and log synchronization
- Use a Martini REST API for controlled authentication or façade requests
- Use a documented callback only if the specific Duo product confirms one
- Avoid treating Duo logs as a universal real-time event stream
Objective
Call the applicable Duo API and handle request signing, pagination, and response validation.
Instructions in Martini
- Construct the method, URI, parameters, and timestamp
- Generate the documented HMAC signature
- Retrieve collection pages until the endpoint is complete
- Persist a timestamp or event position for incremental log retrieval
- Classify authentication, authorization, validation, rate-limit, and server errors
Objective
Coordinate Duo calls with target-system lookups, enrichment, and controlled state changes.
Instructions in Martini
- Resolve existing target identifiers before creating objects
- Use correlation IDs for authentication and administrative operations
- Separate read, create, update, disable, and delete paths
- Apply approval rules before sensitive or destructive actions
Objective
Convert Duo Users, Phones, Endpoints, Integrations, and logs into canonical or target-specific models.
Instructions in Martini
- Map stable identifiers before display names or email addresses
- Validate required fields and preserve relevant audit context
- Normalize timestamps, statuses, factor outcomes, and endpoint attributes
- Minimize sensitive fields copied to downstream systems
Objective
Deliver normalized data to identity, security, ITSM, analytics, or operational applications.
Instructions in Martini
- Write only after the Duo response has passed validation
- Use idempotent upsert or update behavior where supported by the target
- Forward authentication and administrative events to approved destinations
- Store the checkpoint only after successful target delivery
Common Duo Security data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Users | Synchronize Duo user identity, enrollment, and status information or drive controlled provisioning and deprovisioning. | Active Directory, Microsoft Entra ID, Okta, Workday, ServiceNow | Martini retrieves or updates Users through signed API requests, resolves stable identifiers, validates lifecycle state, and applies explicit create, update, disable, or delete rules. |
| Phones | Manage phone devices and phone numbers associated with users and authentication factors. | Active Directory, Microsoft Entra ID, Okta, ServiceNow | Martini maps phone associations to canonical user and factor data, avoids using phone numbers alone as unique keys, and protects sensitive values in logs. |
| Endpoints | Reconcile devices known to Duo and endpoint-related information with asset or device-management data. | ServiceNow, Splunk, endpoint-management platforms, data warehouses | Martini retrieves paginated endpoint collections, compares stable identifiers, classifies stale or unmatched devices, and routes approved exceptions. |
| Integrations | Represent configured Duo applications and integrations used by protected services. | Configuration repositories, ServiceNow, audit platforms | Martini can retrieve integration metadata for inventory and audit workflows while restricting write operations to approved administrative processes. |
| Authentication logs | Synchronize authentication attempts, outcomes, factors, and event timestamps for security operations. | Splunk, ServiceNow, data warehouses, monitoring platforms | Martini polls incrementally, stores checkpoints, applies an overlap window, deduplicates events, and forwards normalized security events. |
| Trusted endpoints | Reconcile trusted-device or endpoint records used by Duo trusted-endpoint capabilities. | ServiceNow, endpoint-management platforms, compliance repositories | Martini compares Duo records with authoritative asset data and creates remediation or review work without performing destructive changes by default. |
Authentication and security considerations
HMAC-signed API requests
Duo Admin API and Authentication API requests generally use an integration key, secret key, timestamp, and documented HMAC-based signing. Martini can construct these requests in workflows while keeping the secret outside workflow logic.
Secret protection
- Store Duo credentials in Martini secrets or protected environment configuration.
- Do not log secret keys, raw signatures, or sensitive authentication responses.
- Use the minimum Duo permissions required by each integration.
- Keep SAML and OIDC configuration separate from HMAC API signing.
API exposure
Any Martini API that exposes Duo operations should use strong authentication and authorization, validate inputs, restrict permitted operations, and protect correlation and authentication data.
Operational considerations for Duo Security integrations
Rate limits and retries
Confirm applicable limits for the specific Duo API and use bounded exponential backoff for transient failures. Do not blindly retry authentication operations because a repeated request may create another authentication attempt.
Pagination and checkpoints
Treat collections as paginated unless the endpoint guarantees otherwise. For logs, persist a timestamp or event position, use a small overlap window, and advance the checkpoint only after successful target delivery.
Idempotency and duplicates
Resolve stable Duo identifiers before creating or updating Users, Phones, Endpoints, or Integrations. Deduplicate log events by Duo identifiers or a carefully designed composite key.
Schema and testing
Validate required fields because resources and response fields can differ by endpoint and product edition. Test authentication timeouts, pending states, permission failures, rate limits, pagination, late-arriving logs, and target-system outages.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini centralizes Duo request signing, API calls, pagination, mapping, business rules, target writes, and error handling in maintainable workflows rather than scattering logic across scripts.
Reusable integration assets
Teams can expose normalized APIs and reuse workflow logic for user lifecycle, authentication decisions, log forwarding, and endpoint reconciliation while keeping Duo-specific behavior behind consistent interfaces.
Operational control
Martini supports scheduled and API-led execution, checkpointing, retries, validation, monitoring, and controlled deployment. This makes it easier to distinguish transient API failures from authentication, authorization, or data-quality errors.
Frequently asked questions
Duo Security can be integrated through its REST-based Admin and Authentication APIs, which support administrative resources, authentication operations, users, phones, endpoints, integrations, and logs. Applicable Duo SSO configurations can also use SAML or OIDC flows. Scheduled API polling is the general approach for synchronization because a universal webhook mechanism was not confirmed.
Yes. Martini can consume Duo's REST APIs from workflows, generate HMAC-signed requests using protected integration credentials, synchronize Duo data, and expose controlled REST APIs that normalize Duo authentication or administrative operations. It can also coordinate applicable SAML or OIDC-based flows.
No. A dedicated Duo Security connector is not required. Martini can integrate using Duo's native REST APIs, HMAC request authentication, scheduled polling, and applicable SAML or OIDC flows. A general-purpose Duo webhook mechanism should not be assumed unless the relevant product documentation confirms it.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Duo Security. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Duo, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Use the Duo Admin API for administrative resources such as Users, Phones, Integrations, Endpoints, and logs, and use the Duo Authentication API for pre-authentication, authentication attempts, factor operations, and status checks. Use SAML or OIDC only for applicable Duo SSO configurations; these are not substitutes for HMAC-signed API requests.
A general-purpose webhook mechanism covering all Duo administrative and authentication events was not confirmed. For synchronization, Martini should normally poll the relevant Duo log APIs on a schedule, using checkpoints, overlap windows, and deduplication. A product-specific callback can be used only when documented for the required event.
Martini can retrieve paginated collections or logs, map them to a canonical model, and write them to target systems. Log synchronization should use a persisted timestamp or event position, a small overlap period, and stable identifiers for deduplication. User and Phone synchronization should resolve existing identifiers and apply explicit lifecycle rules.
Yes. Martini can expose a secured REST API that validates requests, calls Duo pre-authentication and authentication operations, checks pending status, and returns an approved, denied, or pending result. The design should include correlation IDs, expiration and timeout policies, strict access controls, and careful handling of retries.
Related Martini documentation
Build a maintainable Duo Security integration with Martini
Use Martini to connect Duo Security APIs with identity, security, ITSM, and operational systems through secure workflows, normalized APIs, data mapping, and reliable synchronization.