SSO allows you access DbFace without having to log in. Users can log-in DbFace with their username and password from an existing backend system

DbFace implements Single Sign­On using JWT (JSON Web Token), JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

You are required to develop and expose an HTTP endpoint (SSO login URL) which will pass login information to DbFace.

Request flow#

This is SSO happens:

  1. You embed DbFace IFrame Link into your web page.
  2. DbFace IFrame Link will redirect to SSO login URL (HTTP endpoint implemented by you and hosted on your domain)
  3. Your HTTP endpoint valid current login status, and make JWT object which includes the user's email and name. You redirect to DbFace IFrame Link with token parameter, the token value is just the JWT object.
  4. DbFace will unpack and valid the JWT object and full authenticated and final redirect into DbFace.

Enable SSO in DbFace#

To enable SSO in DbFace, sign in DbFace with Administration account, click Settings -> Preference -> SSO.

Enable single sign-on in DbFace

Here is a sample SSO login URL implemented by PHP:

// The DbFace IFrame Link will be provided by the ssocallback parameter
$ssocallback = $_GET['ssocallback'];

// SSO Secret Token configured in DbFace
$key = 'SSO Secret Token';

// JWT PHP library: https://github.com/firebase/php-jwt
require(APPPATH."third_party/php-jwt/JWT.php");

// the email and name should already created in DbFace
// Your DbFace account or sub-account
// rand field make token unique everytime
$token = array(
  'email' => 'my-email@my-company.com',
  'name' => 'my-name',
  'rand' => time()
);
$jwt = JWT::encode($token, $key);

// OK, now we redirect to the DbFace IFrame Link with the token parameter
redirect($ssocallback.'?token='.urlencode($jwt));

Token Definition#

Field NameDescription
emailRequired: the email address of the signed in user
nameRequired: The username of the signed in user
permissionOptional: permission of the signed user, user or developer, no affect to the existed user
groupOptional: user group, no affect to the existed user
passwordOptional: password for the created user, no affect to the existed user

Create DbFace Account via SSO#

You do not need to create SSO account in DbFace one by one. Only View and Developer account can be created.

$token = array(
  'email' => 'my-email@my-company.com',
  'name' => 'my-name',
  'permission' => 'user or developer',
  'group' => 'user group name: optional',
  'password' => 'specified password, if not set, will generated random',
  'rand' => time()
);
$jwt = JWT::encode($token, $key);

If DbFace does not find account by email and name, it will create this account with a random password automatically.

To disable this feature, please open config/config.inc.php and edit

// auto create user, please attach permission field: developer or user
$config['sso_autocreate_account'] = FALSE;