While getting ready to roll out your Mosaic integration, determine how you are going to handle communication with Mosaic. Depending on your security guidelines and requirements, decide on the deployment setup to use.
The basic third-party setup is recommended for test and POC deployments only.
In a basic implementation, a user's device calls your app APIs (e.g., app.acme.com) while communicating directly with Mosaic (https://api.transmitsecurity.io/) at the same time. Such implementation is called third-party integration because the user's device interacts with other services outside your domain.
Consider:
- Benefits: The implementation is simple since it does not require any changes to your DNS or domain, configuring certificates and network.
- Caveats: Take into account that third-party DNS lookups are often evaluated and blocked by privacy and ad-block tools and which can interfere with the Mosaic flows.
In production environments, the best practice is to try to avoid redirecting to external services, such as Mosaic, for privacy, usability, and security reasons. Unlike third-party integration, first-party integrations imply that all communication occurs within your domain. From the user's perspective, the app never leaves its domain, but under the hood it remains fully integrated with Mosaic through APIs and SDK calls.
You can use the default domain (api.transmitsecurity.io) or a default subdomain (<your-subdomain>.app.transmitsecurity.io), or a custom domain (a domain you own, e.g. auth.acme.com). The three options below are the technical ways to implement a custom domain. The main difference: with CNAME mapping, traffic goes directly to Mosaic; with CNAME proxying and path proxying, it goes through your infrastructure first, then to Mosaic.
| Option | How it works | Available for |
|---|---|---|
| CNAME mapping | Your subdomain (e.g. auth.acme.com) points straight to Mosaic via DNS. Traffic goes from the user directly to Mosaic — no proxy on your side. | All Mosaic services |
| CNAME proxying | Your subdomain points to your infrastructure (CDN, load balancer, or reverse proxy), which then forwards traffic to Mosaic. | Journeys, Identity Management, Fraud Prevention (Identity Verification support TBD) |
| Path proxying | A path on your domain (e.g. acme.com/mosaic) is proxied to Mosaic. You route that path through your proxy or load balancer. | Fraud Prevention only |
In this first-party integration, Mosaic traffic is passed through a dedicated subdomain. You create a CNAME record at the DNS level that points your subdomain directly to the Mosaic endpoint. Traffic goes from the user's device to Mosaic without passing through your infrastructure.
In the diagram below, app.acme.com is your main subdomain, mosaic.acme.com is a CNAME record that points to Mosaic (api.transmitsecurity.io). Whenever a user's device needs to send data to Mosaic, DNS lookup resolves the mosaic.acme.com CNAME to Mosaic.
For a streamlined setup with optional Transmit-managed SSL, you can request a custom domain from Transmit Security. They provide a fallback origin (API Gateway URL) that you point your CNAME to; Transmit can provision and manage certificates for you. See Configure custom domains.
Consider:
- Benefits: The implementation is fairly simple. It requires providing the TLS certificate to Transmit Security and changing the DNS record on your side (or using the custom domain flow for managed SSL).
- Caveats: If you manage certificates yourself, you must handle TLS including generating new certificates and replacing expired ones. Alternatively, you can leverage ACME challenge and DCV delegation to automate certificate renewals, or use the custom domain provisioning for Transmit-managed SSL.
This first-party integration requires proxying traffic to Mosaic through a dedicated subdomain. For Mosaic to operate properly, forward Mosaic client-side SDK calls and API calls through this subdomain as a proxy.
In the diagram below, app.acme.com is your main subdomain and mosaic.acme.com is a subdomain managed by your product and proxied to Mosaic (api.transmitsecurity.io).
Consider:
- Benefits: Ability to control your app subdomains and forward traffic via a load balancer, CDN, reverse proxy, etc.
- Caveats: CNAME proxying can introduce additional charges for cloud computing services.
Path proxying is supported for applications integrated with Fraud Prevention only.
This first-party integration requires forwarding Mosaic client-side SDK and API calls through a path-based proxy. This includes creating a URI path within your domain and configuring the load balancer, CDN, reverse proxy, application layer, etc., to work as a proxy.
This integration also requires passing the real client IP address in the X-Forwarded-For header to fully leverage Mosaic Fraud Prevention. Mosaic reads the IP chain (list of IPs separated by commas) from this header. The original IP is determined by the first, non-internal IP address in the X-Forwarded-For chain IP list and is used for risk evaluation and fraud detection. Refrain from passing the client IP in the True-Client-Ip header.
In the diagram below, app.acme.com is your main subdomain, app.acme.com/mosaic is a URI path managed by your product and proxied to Mosaic.
Consider:
- Benefits: The most seamless integration. Enables you to leverage an existing DNS record and data routing. The only changes being made are affecting a load balancer, CDN, reverse proxy, etc.
- Caveats: You have to handle data before routing it to Mosaic. Supports Fraud Prevention capabilities only.
For detailed information on requesting and configuring a custom domain (including managed SSL via fallback origin), see Configure custom domains.