How to Set Up OAuth SSO in Calem

OAuth (https://oauth.net) SSO (Single Sign-On) is available in the coming release of Calem R21e. The process flow is similar to Calem SAML SSO.

• A user logging into Calem is redirected to an OAuth ID provider configured in Calem for authentication and authorization
• The user is prompted to use his account to sign into Calem. A sample prompt screen is shown below.
• The user authenticates at the OAuth ID provider, and is logged into Calem.

1. User Info

User info including sub (user Id), email and name can be returned with access token from ID Providers. For instance, the user info (id_token to be configured below) is included as a JWT (JSON Web Token) when access token is returned. Otherwise, an additional service call (Step 7 in the diagram below) is required to fetch the user info from ID providers.  

2. OAuth SSO Enablement

OAuth SSO is enabled by adding a setting in calem.custom.php (at server/conf) of the Calem service. 

• A login screen is prompted when a user accesses Calem from a web browser. Click the login button to launch the OAuth SSO. 
• The OAuth SSO is launched similarly when logging into Calem from Calem Mobile (iOS and Android).

//OAuth SSO
$_CALEM_dist['oauth_conf']['oauth_sso']=true; 

 3. ID Provider Registration

The first step for OAuth SSO is to register a Calem service with an OAuth ID provider. A redirect URL back to the Calem service may be registered with the ID provider. A client Id and secret are generated from the ID provider. 

The registration and the ID provider info are configured in calem.custom.php.

//Client Id and Secret
$_CALEM_dist['oauth_conf']['client_id']='generated client id';
$_CALEM_dist['oauth_conf']['client_secret']='generated client secret';

//Redirect urls should be registered in the ID provider.
//If left null, it is the service address such as https://acme.calemeam.com/index.php
$_CALEM_dist['oauth_conf']['redirect_url']=null;

//ID provider info
$_CALEM_dist['oauth_conf']['auth_url']='https://your.id.provider/oauth2';
$_CALEM_dist['oauth_conf']['token_url']='https://your.id.provider/token';
$_CALEM_dist['oauth_conf']['userinfo_url']='https://your.id.provider/userinfo';



 

4. User Info in JWT

JWT (JSON Web Token) may be used to encapsulate the user info returned from an ID Provider. Additional info is required to tell Calem about the JWT. It is added to calem.custom.php. 

//JWT userInfo with access token response
$_CALEM_dist['oauth_conf']['jwt_in_token']=true;

//JWT attr at token response
$_CALEM_dist['oauth_conf']['jwt_token_attr']='id_token';

//public key to decode JWT by file or by url. If not provided the key file must be provided below.
$_CALEM_dist['oauth_conf']['jwt_key_url']='https://your.provider.id/oauth2/certs';

//the key file needs to be placed at “server/modules/oauth/” directory.
$_CALEM_dist['oauth_conf']['jwt_key_file']='your-provider.pub.json';

//If key url is provided, key file is cached with ttl of 24 hours by default; 0 - will not cache;
$_CALEM_dist['oauth_conf']['jwt_key_ttl_h']=24;

 

5. OAuth User Selection

OAuth ID providers may treat a returning user (successfully authenticated and authorized) in different ways. For instance, a user may be prompted to authenticate at each login, or a user may be logged in directly without authentication and authorization screens.

In the latter case, an option may be enabled in Calem to request prompts at each login. This option may be provided to Calem for enablement.

​6. OAuth User Auto-Provisioning ​

Auto-provisioning OAuth users in Calem is possible as done for the SAML SSO. A custom plug-in will be required to achieve this function.  

Resources

• How to Set up SAML SSO in Calem
• How to Auto-Provision Users in SAML SSO
• Login User Setup in Calem
• User Guide and Admin Guide (customer account required)
• Calem Enterprise Training Site
  
• Calem Enterprise Blogs
  
• Calem Enterprise demo