Embed Authentication Flows

There are a variety of ways to orchestrate the embedding of content into a host application and its related authentication procedures.

  • In deploying Pyramid in a "standard" approach, Pyramid is deployed as a standalone sit. The key questions relate to where and how authentication is executed.
  • In deploying Pyramid in a "non-standard" approach, Pyramid is deployed using a virtual directory or sub-sub-domains. The key questions relate to configuring the environment.

The virtual directory and sub-sub-domain approaches are particularly useful when accommodating different identity providers for different users (or tenants) in embedded scenarios without needing to implement multiple IDPs in Pyramid itself. This benefit and approach is greatly accentuated if there is a requirement to embed the full Pyramid client in iframes with pass through authentication.

Setup of client-side security can have a major impact on the success of the embedding process. Configuration should be done carefully.

Standard Flows

The "standard" model focuses on a standard deployment of Pyramid as a standalone web site, with embedded content that is INJECTED into the host page of a 3rd party host site, rather than using less efficient iframes. The embedded content in the host will communicate via API's to the Pyramid instance, which doesn't need to be in the same domain or sub-domain (even though it usually is).

See the virtual directory and sub-domain flows below if the full client needs to be embedded with an iframe.

On Page Flow (JavaScript Only):

The "On-page" authentication flow is the simplest scenario in the standard deployment approach - using nothing other than the embed API and its login mechanisms. The login mechanism can be also performed using the REST APIs, which are simply veneered in the Embed API library.

This technique is usually only suitable when "internal database authentication" is used (rather than an IDP with SSO).

  1. User logs into the host page of the host site ("www.abc.com")
  2. On the host page standard requests are sent tot he server
  3. The host produces responses as normal.
  4. If a user accesses the analytical layer, the user might enter credentials into the host page itself, which are then sent via the embed API (or REST) to Pyramid to get the authentication token. Once returned, the token is saved locally in a cookie in the host domain.
  5. On each analytical request sent from the host page, the security token is included
  6. As embedded content is consumed requests for content to Pyramid are sent and responses are returned.

On-Page: Pros and Cons

  • Simple, quick and easy
  • Limited use cases
  • Cookies remain in the host domain (better). As such, the cookie CANNOT be sent in Pyramid requests. Instead the token is loaded into the API calls.
  • This mechanism only works with injected embedding. It will not work (well) if the full client needs to be hosted in an iframe.
  • The host and pyramid domains can be different (even though they are typically not)
  • CORS must be enabled, preferably with white listed websites

Code Behind Flow

The code behind or "Off-page" authentication flow is scenario assumes authentication is completed on the host's server side engine. It can also involve the use of an external identity provider (IDP) which is quite typical. The login mechanism is performed on the server using either REST APIs or client SDKs.

This is the most typical implementation of embedded authentication

  1. User logs into the host page of the host site ("www.abc.com")
  2. User authenticates to the host site.
    1. If an IDP is used, the user is typically redirected to the IDP for authentication (via SAML or OpenID etc).
    2. If local authentication is used, the user might enter credentials into the host page
  3. The page send the credentials or tokens to the server.
  4. The host server can now authenticate the known user to Pyramid, using authentication APIs
  5. Pyramid responds with a Pyramid authentication token
  6. The host writes a response to the user's browser with the original cookies and a Pyramid embed cookie containing the Pyramid token. BOTH cookies belong to the host domain (cookie.abc.com).
  7. If a user choose to access the analytical layer, the Pyramid token is sent via the embed API to Pyramid as part of the requests.
  8. This in turn is sent to the Pyramid server on each and every request
  9. Pyramid processes a response and returns it back to the user

Code Behind: Pros and Cons

  • Relatively simple and robust
  • This follows a well structured, high-scale and modern host application (especially using the IDP)
  • Server side authentication offers broad back-end functionality and logic in any language
  • Cookies remain in the host domain (better). As such, the cookie CANNOT be sent in Pyramid requests. Instead the token is loaded into the API calls.
  • This mechanism only works with injected embedding. It will not work (well) if the full client needs to be hosted in an iframe.
  • The host and pyramid domains can be different (even though they are typically not)
  • CORS must be enabled, preferably with white listed websites.

Non-Standard Flows

The "non-standard" models focus deployment of Pyramid as virtual directory or a sub-sub domain. These techniques solves SSO for the full client if embedded as an iframe and also allow the entire embedding apparatus to operate without CORS enabled. It also facilitates the use of multiple, different IDPs as the authentication mechanism. However, it's usually more complex to setup and maintain.

Virtual Directory Flows

The virtual directory flow works on a model where Pyramid is running as an application from a virtual directory of a different (or host) site. This is configured in the Pyramid admin console, and requires the operation of a reverse proxy engine that can redirect requests to different applications (potentially on different servers).

Even if a customer has multiple sub-domain entry points, they can all REUSE the same, central instance of Pyramid.

A notable benefit to using virtual directory deployments, is that the host page can be configured for each tenant (or customer). It can then redirect to a specific identity provider (IDP) for that customer, with a programmatic authentication into Pyramid - without needing to have each IDP setup in Pyramid itself.

  1. User logs into the host page in their specific sub-domain of the host site ("coke.abc.com" vs "pepsi.abc.com")
  2. The host page is already designed to ask the user to authenticate on Coke's specific IDP (part of the host's application authentication design). The IDP authenticates and returns the token (both for SAML and OpenID)
  3. The host server receives the token, typically creates a cookie on the server.
  4. The host server can now authenticate the known user to Pyramid, using authentication APIs
  5. Pyramid responds with a Pyramid authentication token
  6. The host writes a response to the user's browser with the original cookies and a Pyramid embed cookie containing the Pyramid token. BOTH cookies belong to the sub-domain (cookie.abc.com).
  7. When the user accesses analytics, they will go to the virtual directory entry point (coke.abc.com/analytics). The Virtual directory can be any name, but it must be consistently used across all sub-domains.
  8. The sub-domain cookies are sent with each requests as normal, including the Pyramid security token cookie
  9. Pyramid recognizes the security and continues as normal.

Virtual Directory: Pros and Cons

  • Cookies remain in the host sub-domain (better)
  • Only one SSL certificate is needed for both the host and Pyramid
  • Only one virtual directory label can be used
  • Multiple sub-domain entry points reuse the same, central instance of Pyramid
  • This mechanism works well with injected embedding and if the full client needs to be hosted in an iframe.
  • The reverse proxy configuration needs to be done.
  • CORS does not need to be enabled (better)

Sub-Sub-domain Flows

The sub-sub-domain flow works on a model where Pyramid is running as an application as a sub-domain of another domain (or sub-domain) hosted site. This does NOT require configuration in Pyramid. All the effort requires setup in a reverse proxy engine.

Even if a customer has multiple sub-domain entry points, they can all REUSE the same, central instance of Pyramid.

A notable benefit to using sub-domain deployments, is that the host page can be configured for each tenant (or customer). It can then redirect to a specific identity provider (IDP) for that customer, with a programmatic authentication into Pyramid - without needing to have each IDP setup in Pyramid itself.

  1. User logs into the host page in their specific sub-domain of the host site ("coke.abc.com" vs "pepsi.abc.com")
  2. The host page is already designed to ask the user to authenticate on Coke's specific IDP (part of the host's application authentication design). The IDP authenticates and returns the token (both for SAML and OpenID)
  3. The host server receives the token, typically creates a cookie on the server.
  4. The host server can now authenticate the known user to Pyramid, using authentication APIs
  5. Pyramid responds with a Pyramid authentication token
  6. The host writes a response to the user's browser with the original cookies and a Pyramid embed cookie containing the Pyramid token. BOTH cookies belong to the sub-domain (cookie.abc.com).
  7. When the user accesses analytics, they will go to a sub-sub-domain entry point (analytics.coke.abc.com). The sub-sub domain can be any name and can be different for each instance (subject to configurations in the reverse proxy)
  8. The sub-domain cookies are sent with each requests as normal, including the Pyramid security token cookie
  9. Pyramid recognizes the security and continues as normal.

Sub-Sub-Domain: Pros and Cons

  • Cookies remain in the host sub-domain, but are passed through to the sub-sub domain as well
  • Different SSL certificates are needed for the host and Pyramid domains
  • It requires no specific configuration in Pyramid itself. Setup in a reverse proxy is required, but is quick and easy.
  • Different sub-domains names can be used
  • Multiple sub-sub-domain entry points reuse the same, central instance of Pyramid
  • This mechanism works well with injected embedding and if the full client needs to be hosted in an iframe.
  • CORS does not need to be enabled (better)

Using a single instance of Pyramid

A single instance of Pyramid can accommodate the different authentication paths when using the virtual directory or sub-domain approaches as shown in the diagram below.

  • The reverse proxy effectively collates all the requests and sends them to Pyramid - which remains agnostic about the source URL/DNS setup. On responding, the proxy ensures the right response goes to the right browser (as normal).
  • Security within Pyramid, attached to each user's Pyramid token, handles access to the right content, the right data and the right functionality seamlessly.