SSO - OpenID Connect

SSO - OpenID Connect#

This is a generic identity provider feature that allows Bacularis to integrate with a wide range of identity provider (IdP) services. These providers may or may not support single sign-on (SSO) functionality. The most important requirement is compatibility with the OpenID Connect protocol.

This feature is available in Bacularis starting from version 5.4.0.

Requirements#

Before using this identity provider with Bacularis, make sure that your IdP environment meets the following criteria:

  • TLS/SSL connection - Both the identity provider and Bacularis use encrypted HTTPS connections. TLS/SSL certificates must be valid and not expired.

  • OpenID Connect - The identity provider must support this protocol.

  • RS256 - The identity provider must sign tokens using the RS256 algorithm. This is the RSA Digital Signature Algorithm with SHA-256.

Organization support#

Users from the IdP must belong to an organization using the identity provider. They cannot be used outside of organizations (i.e., without an assigned organization).

Usernames must be unique within an organization, but they do not need to be unique across all organizations. Each organization defines its own namespace for users. This allows for the same login name to exist in different organizations.

In other words, USER1 in ORGANIZATION 1 and USER1 in ORGANIZATION 2 are considered two different users.

This is illustrated in the image below.

../../_images/bacularis_authentication_idp_identity_provider_organization.png

User provisioning#

This authentication method fully supports user provisioning. Since users can only be provisioned to a single selected organization, in environments with multiple organizations, you can create a temporary organization for provisioning and then move the new accounts to their target organizations.

User attributes#

If user attributes change on the IdP side, they can be updated in Bacularis. Bacularis supports four user attributes:

  • username - Used as the login name

  • long name - Typically the user’s full name

  • email - The user’s email address

  • description - Other information about the user

Only username is required and is not considered during synchronization. The remaining attributes are optional and can be synchronized.

ID token claims can be mapped to Bacularis attributes. For example:

preferred_username => username
name => long name
email => email
age => description

In this case, the ID token must include the following claims:

  • preferred_username

  • name

  • email

  • age

These claims can be configured on the IdP side.

Bacularis supports two attribute synchronization policies:

  • Do not synchronize - Attributes are not updated.

  • Synchronize on each login - Attributes are updated with every login.

Security#

In OAuth2 terms, Bacularis is a confidential client. This means it can securely authenticate with the authorization server and safely store client secrets.

All sensitive OAuth2 data is stored on the application backend. End users have no access to this data, and it is never loaded into the browser during the OAuth2 flow.

Although Bacularis is not a public OAuth2 client, it supports the PKCE (Proof Key for Code Exchange) extension. This adds an extra layer of security to the authorization process and is considered best practice.

Single Sign-On#

Sessions#

The identity provider manages the user session. Bacularis maintains its own PHP session, which is separate from the IdP session. To enable SSO, both sessions must work together.

For proper SSO functionality, the Bacularis PHP session expiration time must be greater than the IdP session expiration time. Otherwise, the PHP session may end first, disrupting automatic session refresh. This will require the user to re-authenticate.

Check the ID token lifespan (TTL) on the IdP side and compare it with the PHP session timeout in php.ini. The relevant directive is session.gc_maxlifetime. For example, if the ID token expires in 60 minutes, set the PHP session to 65 minutes (3900 seconds), like so:

session.gc_maxlifetime = 3900

User information#

Bacularis can retrieve user attributes from ID token claims or the UserInfo endpoint. It is recommended to use ID token claims. If that’s not possible, using the UserInfo endpoint is also acceptable.

When using the UserInfo endpoint in large environments, Bacularis may send additional HTTP requests to the IdP during authentication.

Single logout#

Bacularis supports OpenID Connect Single Logout (SLO) from both the IdP and Bacularis sides.

The backchannel logout URL from the IdP side is:

https://{bacularis-host}/web/oidc/{idp-id}/logout

Where:

  • {bacularis-host} is your Bacularis instance address, accessible from the IdP side.

  • {idp-id} is the identity provider’s identifier, found in the Bacularis IdP configuration form.

Example:

If the Bacularis address is bacularis:9097 and the IdP identifier is main, the logout URL would be:

https://bacularis:9097/web/oidc/main/logout

Settings form#

You can configure identity providers at:

[Main menu] => [Page: Security] => [Tab: Authentication] => [SubTab: Identity providers]

Below is the identity provider settings form:

../../_images/bacularis_authentication_sso_openid_connect_settings_form.png

Video guides#

Keycloak#

Keycloak is an open source identity and access management (IAM) solution. The video below shows how to integrate Keycloak SSO with Bacularis.


Okta#

Okta is an enterprise-grade identity management platform. Below is an example showing how to use Bacularis with Okta SSO features.