SSO - OpenID Connect

SSO - OpenID Connect#

This is a generic identity provider function that allows Bacularis to integrate with a wide range of identity provider (IdP) services. They may or may not support single sign-on (SSO) features. The most important thing is that they are compatible with the OpenID Connect protocol.

This feature is available in Bacularis from version 5.4.0.

Requirements#

Before using this identity provider with Bacularis, please make sure that your IdP environment fulfills the following criterias:

  • TLS/SSL connection - both the identity provider service and Bacularis use encrypted HTTPS connection. The TLS/SSL certificates are valid and not expired.

  • OpenID Connect - the identity provider supports this protocol.

  • RS256 - identity provider signs tokens using this RS256 algorithm. This is RSA Digital Signature Algorithm with the SHA-256 hash function.

Organization support#

The IdP users have to belong to the organization using the identity provider. The identity provider users cannot be used outside organizations (without organization assigned).

The username/login has to be unique inside organization but it does not have to be unique globally across organizations. Each organization using identity provider provides its own namespace for users. This means that there is supported to have users with the same login name in multiple organizations.

In other words USER1 in ORGANIZATION 1 and USER1 in ORGANIZATION 2 are two different users and they are treated separately.

This is shown on the image below.

../../_images/bacularis_authentication_idp_identity_provider_organization.png

User provisioning#

This authentication method fully supports user provisioning. Because users can be provisioned to only one selected organization, in environments with multiple organizations you can create a temporary organization for users and use it for provisioning. After that, you can move newly created user accounts to destination organizations.

User attributes#

If user attributes are changed on the identity provider side, they can be updated on the Bacularis side as well. Bacularis provides four user attributes:

  • username - that users use as a login name

  • long name - that can be for example the user full name.

  • email - that is the user e-mail address

  • description - that stores other information about user

Only username is required to define and it is not taken into account in synchronization. Rest attributes is optional and they can be synchronized.

The ID token claims can be mapped to these Bacularis attributes. There is possible for example to do the following mapping:

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

In this case the ID token should provide the following claims:

  • preferred_username

  • name

  • email

  • age

The ID token claims can be configured on the identity provider side.

So far Bacularis supports two attribute synchronization policies:

  • Do not synchronize - attributes are not synchronized.

  • Synchronize on each login - attributes are synchronized on each user authentication.

Security#

In the OAuth2 nomenclature, the Bacularis OpenID Connect client is a confidencial client. This means that Bacularis is able to securely authenticate to the authorization server and to keep the registered client secrets in a safe way.

All confidential OAuth2 data is stored on the application backend side. End users do not have access to this data and it is not loaded to the web browser during all the OAuth2 authorization flow.

Even though Bacularis is not the OAuth2 public client, it supports PKCE (Proof Key for Code Exchange) security extension for OAuth2 because this is a good security practice. This adds an extra layer of security to the authorization process.

Single Sign-On#

Sessions#

Identity provider manages the user session. Bacularis manages its own PHP session that is different from the identity provider session. To provide SSO functionality, both sessions cooperate together.

To proper SSO working with Bacularis, there is required that the Bacularis PHP session expiration time is greater than the identity provider session expiration time. Otherwise the PHP session will end before the identity provider session and it will not be possible to automatically refresh the session. The relation between both sessions will be lost and end user will need to re-authenticate.

Please check the ID token lifespan value (token TTL) on the identity provider side and compare it with the PHP session expiration time which you can find in the PHP php.ini configuration file. The directive responsible for that is named session.gc_maxlifetime. For example, if ID token expiration time is 60 minutes, you can set the PHP session time to 65 minutes (3900 seconds) or longer, as in the example below:

session.gc_maxlifetime = 3900

User information#

Bacularis can retrieve user attributes from the ID token claims or from the UserInfo endpoint. It is recommended to provide the user information in ID token but if it is not possible, then using the UserInfo endpoint for that is also valid. When using the UserInfo endpoint in environments with a large number of users, Bacularis will send slightly more HTTP requests to the identity provider when users are authenticated.

Single logout#

Bacularis supports OpenID Connect Single Logout (SLO) both from the identity provider side and from the Bacularis side.

The URL to backchannel logout from the identity provider side is the following

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

Where:

  • {bacularis-host} is the Bacularis instance address. It must be accessible from the identity provider side.

  • {idp-id} is the identity provider identifier. You can find it in the identity provider configuration form in Bacularis.

For example, if the Bacularis address is bacularis:9097 and the identity provider identifier is main then the backchannel logout URL can be following:

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

Settings form#

The identity providers you can configure on this page:

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

Below you can see 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. On the video guide below you can see how to integrate Keycloak single sign-on features with Bacularis.


Okta#

Okta is an enterprise-grade identity management service. Okta provides comprehensive identity and access management (IAM) platform. Here you can see example usage Bacularis with Okta single sign-on (SSO) functions.