SEC 1: How are you associating tenant context with users and applying that context within your SaaS architecture?

A SaaS architecture must successfully connect a user’s identity with the identity of their tenant. This SaaS identity must be attached to all of their interactions with a SaaS environment, allowing you to resolve and apply this context across all the services of your application without introducing overhead that could undermine the performance of your system.

Resources

AWS re:Invent 2017: GPS: SaaS and OpenID Connect: The Secret Sauce of Multi-Tenant Identity (GPSTEC323)
Identity Federation and SSO for SaaS on AWS
Managing SaaS Identity Through Custom Attributes and Amazon Cognito
SaaS Quick Start Highlights Identity and Isolation with Amazon Cognito/
AWS re:Invent 2016: The Secret to SaaS (Hint: It's Identity) (GPSSI404)

Best Practices:

• Use application services to generate a unified SaaS identity: SaaS application services map users to tenants, yielding a single representation of the user/tenant identity that can be passed to downstream services.

• Create libraries and frameworks that apply tenant context outside the view of developers: The details of tenant context are hidden from developers through the introduction of libraries and frameworks that own responsibility for extracting and applying the tenant context that is passed into each service.

• Use an identity provider to bind users to tenants: An identity provider manages both user and tenant data, enabling a single authentication experience to return a representation that includes the union of these two concepts. This unified representation is conveyed to all services, eliminating the need to resolve tenant context via separate services.

Improvement Plan

Use application services to generate a unified SaaS identity

Manage and configure tenants separate from users

• Have a centralized service that manages the configuration and status of tenants, providing a well-defined and encapsulated representation of tenants outside the context of users.
• Associate an internally managed, unique identifier with each tenant that is used across the system to reference and associate resources with a given tenant. 
• Allow users to provide an externally more user-friendly name with each tenant to simplify administration and management of tenant state.
• Associate a status with each tenant that indicates if the tenant is active or inactive. Reference this status to enable or disable access to the system.
• Associate some notion of a tier or plan with tenants that represents the current billing model for a tenant.
  AWS re:Invent 2016: The Secret to SaaS (Hint: It's Identity) (GPSSI404)

Create a linkage between tenants and users.

• Augment the authentication flow of your application, adding a post-authentication step that generates a token for downstream processing.
• Use the user identity to resolve the user to a corresponding tenant. This mapping can be acquired though a service or it might rely on the domain of the user to identify the tenant.
• Allow for scenarios where a tenant might be mapped to multiple tenants, introducing an extra step that might require a user to select their target tenant.

Package key tenant attributes with user data in a single representation.
AWS re:Invent 2017: GPS: SaaS and OpenID Connect: The Secret Sauce of Multi-tenant Identity (GPSTEC323)

Place tenant attributes in custom claims that are essential to tenants without bringing in a large collection of authorization constructs that are used to manage access to features and functions.

Use a key to sign this token to protect its contents.

Inject this token into a token for all downstream interactions with the system.

Create libraries and frameworks that apply tenant context outside the view of developers

Have a centralized helper for acquiring tenant context.

• Introduce a token helper that assumes responsibility for unpacking and acquiring tenant attributes that are embedded in a token.
• Rely on the token helper to validate and renew expiring tokens.
  AWS re:Invent 2017: GPS: SaaS and OpenID Connect: The Secret Sauce of Multi-Tenant Identity (GPSTEC323)

Use libraries to inject tenant context into metrics and logs

• Have all log messages sent through a tenant-aware logging wrapper that extracts and injects tenant context into all log files.
• Have all metrics and consumption events sent through a metrics wrapper that extracts and injects tenant context into metric events before they are published.
  AWS re:Invent 2017: GPS: SaaS and OpenID Connect: The Secret Sauce of Multi-Tenant Identity (GPSTEC323)

Use data access libraries to encapsulate tenant dependencies

• When your code needs to access data, it requires some tenant context to determine how and where that tenant’s is stored. This mapping should be done by a data access library that acquires and applies tenant context when data is accessed.
• Use these same data access libraries to hide tenant isolation details. Acquire scoped credentials in this library (where possible) to scope data access to the current tenant.
  Building Serverless SaaS with Lambda layers

Use convention to enforce isolation

• Use the tenant context to identify the current tenant and use this context to apply isolation policies outside the view of developers.
• Rely on language constructs to intercept and apply isolation policies ensuring that isolation compliance cannot be treated as optional.

Use an identity provider to bind users to tenants

Use identity provider custom claims for tenant attributes

When your identity provider (Amazon Cognito, Okta, Ping, Auth0, etc.) is configured, define the custom attributes that are added to your user identity to track tenant attributes.

At a minimum, ensure that the tenant identifier for your system is stored in the custom claims of your identity provider.
Managing SaaS Identity Through Custom Attributes and Amazon Cognito
Amazon Cognito API Reference

Use Amazon Cognito with federated identity providers to introduce tenant context

• In scenarios where the identity of your users is managed by an externally managed identity provider, you might need to manage or introduce custom claims outside of the identity provider.
• Introducing claims in this scenario is achieved through federation where Amazon Cognito will own the custom attributes, generating a token that joins the external user identity with the attributes from Amazon Cognito.
  Identity Federation and SSO for SaaS on AWS

Inject the token returned from the identity provider into a bearer token for all downstream interactions with the system.

Rely on the identity provider to handle signing and the lifecycle of tokens.