Recommendations
This guide provides recommendations for authenticating and authorizing identities attempting to access your Spark resources. From a technical control perspective, identity serves as the primary perimeter. The typical types of identities include:
Humans: Application users, administrators, and potential malicious actors.
Systems: Service-to-service (S2S) interactions, such as those using client credentials or API keys.
Keycloak is the application used by Spark to manage Identity and Access Management. Spark SaaS operates with tenants, each integrated with its own isolated Keycloak realm serving as the Identity Provider (IdP). Each Spark tenant uses its dedicated Keycloak realm for authentication and authorization. Both the Keycloak realms and the Spark tenants are completely isolated, ensuring no overlap or dependency between different tenants and their associated Keycloak realms.
Your tenant's dedicated Keycloak realm supports two types of account setup:
Identity Broker for federated identities (recommended): Act as an intermediary to federate authentication with external identity providers. See Federation for more details.
Identity Provider for local accounts: Manage and authenticate users directly within the realm using local credentials. See Manage users and Benefits of IdP versus local accounts for more details.
Glossary
API key
A type of secret shared between a provider and consumer, used through a secure and predefined mechanism for authentication or access.
Break glass account
A highly privileged account created for use in emergency scenarios (e.g., to regain access to systems or resources if other methods fail). It typically bypasses regular authentication or authorization controls and must be carefully managed.
Client Credentials
A method of authentication where a system (e.g., an application or service) uses a client ID and secret to authenticate itself directly to an identity provider, typically for server-to-server communication.
IdP (Identity Provider)
A service, like Keycloak, Microsoft Entra ID, or Okta, that authenticates and manages user identities.
Keycloak IdP mapper
The IdP mapper mechanism in Keycloak used to map identity provider (IdP) attributes to Keycloak user attributes, roles, or groups. This is commonly used to translate claims or attributes from external IdPs (like Microsoft Entra ID) into attributes understood by Keycloak.
Role
A set of permissions that define what a user or group can do within a system.
User identity
An identity assigned to a person, such as an employee or administrator.
Workload identity
A system identity for an application, service, script, or container, using client credentials or API keys to authenticate to Spark services and resources.
Understand the importance of shared responsibility for access management
See Shared responsibility model.
Create a Break glass account
As the first step after acquiring your Spark tenant, set up a Break Glass local account. This is a highly privileged account designed for emergency access in case of a lockout or authentication failure. The account bypasses standard controls like MFA to ensure immediate access. It should be protected with a strong, unique password and monitored closely to prevent misuse.
For detailed, step-by-step instructions, refer to Break glass account.
Setup Multi-Factor Authentication (MFA) for local accounts
If you use Keycloak as the Identity Provider for local accounts or need access to Spark before integrating with your organization's IdP and enabling SSO, ensure MFA is configured for high-privilege accounts. This includes accounts with tenant-admin or supervisor:pf privileges to enhance security and mitigate the risk of unauthorized access.
For detailed, step-by-step instructions, refer to Multi-Factor Authentication (MFA).
Configure federated identities and enable Single sign-on (SSO)
To act as an Identity Broker and enable SSO, create and configure an Identity Provider (IdP) and integrate it with your organization's IdP within your Spark Keycloak Realm. This is recommended instead of relying upon local accounts as it helps to facilitate user experience and alignment with coporate policies, see Benefits of IdP versus local accounts.
While Keycloak supports integration with major modern cloud IdPs such as Microsoft Entra ID, Okta, and Ping Identity, it can also be integrated with any IdP that supports OpenID Connect (OIDC) or SAML protocols.
Protocol
JSON-based on OAuth 2.0 for authentication and authorization.
XML-based for authentication.
Configuration
Dynamic, simpler configuration.
Manual setup, metadata exchange.
Token Format
JWT (JSON, compact).
SAML assertions (XML, large).
Performance
Faster with lightweight JSON.
Slower due to XML parsing.
Session Management
Requires extra setup for SSO.
Strong SSO and SLO support.
Security
Robust JWT-based signatures.
Relies on XML signatures.
Modernity
Preferred for modern applications.
Fully supported for enterprise use.
For Spark Keycloak integrations, OpenID Connect (OIDC) is the preferred choice due to its simplicity, efficiency, and compatibility. The external IdP's token will ultimately be exchanged for a Keycloak token.
Integrate Spark Keycloak IdP with major cloud IdPs
If your organization's IdP is a modern cloud IdP such as Microsoft Entra ID, Okta, or PingOne, refer to the following guides for step-by-step configuration:
These integrations can also be added to app dashboards below:
If your organization's IdP is not one of the listed options, refer to your IdP's documentation and adjust Keycloak's configuration accordingly. Keycloak supports SAML and OIDC, which are open standards, making the setup straightforwards.
Enable Signature Validation for SAML Identity Providers in Keycloak
If you're using SAML integration with your Identity Provider (IdP), it is essential to enable Signature Validation to ensure secure and trusted communication.
For detailed, step-by-step instructions, refer to Importance of validating signatures in SAML.
Setup your own notifications for expired Client Secret or certificate
Set up a notification system within your organization to monitor and alert when a client secret (OIDC) or certificate (SAML) is about to expire. This ensures timely updates and prevents disruptions in authentication flows.
If the client secret or certificate has already expired and access is disrupted, use the Break glass account to regain access and replace the expired secret or certificate immediately.
Enable the Keycloak Identity Provider Redirector
Set up the Identity Provider Redirector in your Keycloak realm to enable direct SSO with your organization's IdP. This bypasses the realm discovery login page, which lists multiple identity providers, including Keycloak local accounts, streamlining the user login experience.
For detailed, step-by-step instructions, refer to Identity Provider Redirector.
Use your organization's IdP groups/roles with Keycloak IdP mappers
To streamline role management, it's best to keep group and role assignments in your organization’s IdP and use Keycloak IdP mappers to map them to Keycloak groups. This ensures centralized control while dynamically assigning users to critical Keycloak groups like tenant-admin and supervisor:pf. By doing so, you simplify administration, enhance security, and ensure accurate permissions within your Spark tenant.
Example use case
A user logs in via their organization's IdP, such as Okta, which assigns them roles like "Spark tenant admin" or "Spark supmrvisor".
Keycloak uses an IdP Mapper to map these roles (e.g., via the groups claim) to Keycloak groups such as
tenant-adminorsupervisor:pf.The user’s permissions in the Spark application are determined by the mapped Keycloak groups, ensuring centralized role management through the IdP rather than direct assignments in Spark’s tenant Keycloak.
MS Entra ID use App Roles instead of Groups
If your organization uses Microsoft Entra ID, it's recommended to use App Roles instead of Groups for role management. App Roles are application-specific, offering more granular and tailored permission management. They integrate seamlessly with Keycloak, simplifying role mapping and ensuring tighter security and better scalability compared to Groups.
Refer to the following guides for the respective step-by-step configuration:
Enhance productivity with a centralized application dashboard
A recommended best practice is to provide a centralized application dashboard. This gives employees one-click access to essential tools while reducing login friction and streamlining onboarding. This minimizes time spent searching for apps, decreases IT support requests, and enhances the user experience by ensuring a seamless workflow and faster access to business-critical applications.
If your organization has implemented this approach, you should add Spark to your organization's Apps dashboard. Instructions for different IAM platforms are referenced below:
Use user identity for applications requiring authenticated users
Use user identity for applications that require authenticated users from your organization or B2B partner organizations. This ensures proper authentication and access control tailored to individual users.
To implement this, create a client in Keycloak and configure the necessary client mappers and the redirect URL for your application. Detailed instructions about client mappers can be found in the article Create client mappers.
Example use case
You created a Rater Spark Service for internal use by your organization's insurance brokers. A Single Page Application (SPA) authenticates with your organization's IdP, obtains an access token, and uses it to consume the service securely.
Use workload identity for non-human interaction tasks
In a workload Identity scenario, you consume the Spark API using either OAuth2 Client Credentials or API keys.
Purpose
Secure, OAuth 2.0-based client authentication.
Simplistic access to APIs, often without user context.
Security
More secure with tokens and client secret authentication.
Less secure; easily exposed if not handled carefully.
Ease of use
Requires OAuth 2.0 flow and token exchange.
Simple to implement; just include a key in API requests.
Granularity
Fine-grained control over scopes and permissions.
Limited scope and permissions control.
Expiration
Access tokens have short lifetimes, improving security.
Typically static; does not expire by default.
Use Cases
High-security applications, server-to-server interactions.
Quick integrations, server-to-server, low-security apps.
Traceability
Easy to trace and audit based on token issuance.
Difficult to track usage to specific clients.
Standards compliance
Follows OAuth 2.0 standards.
Not standardized; varies by implementation.
When to use OAuth2 Client Credentials or API Keys
Use Client Credentials grant (OAuth 2.0):
Your organization requires OAuth2 compliance.
You need to consume Spark System APIs that do not support API Keys. See Authorization - API keys for more details.
Require fully auditable, revocable, and supports fine-grained scopes.
Integrate with zero trust principles, including strong authentication and access controls.
Example: You have a Python script that runs every 12 hours, acquires an access token via the OAuth2 Client Credentials grant, uses the token to access your Spark tenant, and generates a report on tenant service consumption.
You need to integrate with your Spark-transformed Excel-to-API services.
Example: You created a Spark rating service to generate quotes based on input parameters. The service is published through an API management solution, which provides an URL for anonymous users. The API management software can securely forward requests to the Rater Service with an included API key for authorization.
Last updated