> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/identity-and-access-management/single-sign-on/idp-recommendations.md).

# IdP 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](https://www.keycloak.org/documentation) is the application used by Spark for identity and access management. Spark SaaS operates with tenants, each integrated with its own isolated Keycloak realm serving as the identity provider (IdP) for authentication and isolation.

## Glossary

| Term                    | Definition                                                                                                                                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.                                |
| Identity provider (IdP) | 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](/support/shared-responsibility-model.md).

## 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](/identity-and-access-management/break-glass-account.md).

## 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 corporate policies. See [Benefits of identity provider versus local accounts](/identity-and-access-management/single-sign-on/benefits-of-identity-provider-versus-local-accounts.md).

| Feature            | OIDC                                                          | SAML                                |
| ------------------ | ------------------------------------------------------------- | ----------------------------------- |
| 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

The documentation includes guides for the following:

* [Microsoft Entra ID (OIDC)](/identity-and-access-management/single-sign-on/microsoft-entra-id-oidc.md)
* [Microsoft Entra ID (SAML v2.0)](/identity-and-access-management/single-sign-on/microsoft-entra-id-saml-v2.0.md) and [Importance of validating signatures in SAML](/identity-and-access-management/single-sign-on/importance-of-validating-signatures-in-saml.md)
* [Okta (OIDC)](/identity-and-access-management/single-sign-on/okta-oidc.md)
* [Okta (SAML v2.0)](/identity-and-access-management/single-sign-on/okta-saml-v2.0.md) and [Importance of validating signatures in SAML](/identity-and-access-management/single-sign-on/importance-of-validating-signatures-in-saml.md)

Keycloak can also be integrated with any IdP that supports OpenID Connect (OIDC) or SAML protocols.

### 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.

#### Use app roles instead of groups with Microsoft Entra ID

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:

* OIDC: [Microsoft Entra ID (OIDC)](/identity-and-access-management/single-sign-on/microsoft-entra-id-oidc.md#configure-app-roles-to-spark-user-groups)
* SAML: [Microsoft Entra ID (SAML v2.0)](/identity-and-access-management/single-sign-on/microsoft-entra-id-saml-v2.0.md#configure-entra-id-app-roles-to-spark-user-groups)

### Enhance productivity with a centralized application dashboard

A recommended best practice is to provide a centralized application dashboard. 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:

* [Microsoft Apps](/identity-and-access-management/single-sign-on/microsoft-apps.md)
* [Okta My Apps dashboard](/identity-and-access-management/single-sign-on/okta-my-apps-dashboard.md)

### 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](/identity-and-access-management/single-sign-on/identity-provider-redirector.md).

### Set up your own notifications for expired client secrets or certificates

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](/identity-and-access-management/break-glass-account.md) to regain access and replace the expired secret or certificate immediately.