Single Sign On setup documentation

Updated 11 months ago by Jane

Before you start, please note of the roles mentioned in this article:

  • B3 partner: The person you work with, a bridge between you and B3networks.
  • CRM provider: it's you who supplies the CRM solution to the end user.
  • End user: your customer who is using your CRM system. This person is the one who will use the Single Sign On.

Introduction

Single Sign On (SSO) is implemented based on industry standard Json Web Token.

  1. SSO attempt requires a pair of public key and private key (click HERE to learn how to set up the keys).
  2. Public key needs to be uploaded to Partner’s authentication server. Once the public key is uploaded and accepted by authentication server, SSO is automatically enabled.
  3. Private key must be kept and secured by CRM provider's server.
  4. SSO JWT is signed by using private key.
  5. SSO JWT is sent along with application access request to CRM provider's server.
  6. B3 partner's authentication server verifies the token using public key. After the verification, the end user can access web application, e.g. BizPhone, Wallboard, etc.

Setup Requirements

You, the CRM provider, must store the following:

  1. A mapping between your end user account and partner's portal organization identity (called as orgUuid)
    1. OrgUuid of each CRM user is created by B3 partner and provided through email.
  2. A mapping between CRM user account’s user/agent and Partner's Portal organization’s member identity (called as identityUuid)
    1. IdentityUuid of each user/agent is created by B3 partner and provided through email.
  3. A mapping between CRM customer account and their private key. Private key & public key can be generated by:
    1. CRM provider (strongly recommended)
    2. or by the B3 partner. The partner then gives you the keys via email.
  4. A list of application ID of partner's portal, e.g. appID for BizPhone, WallBoard, etc.
    1. This list is provided by B3 partner through email.

Signing SSO JWT (Json Web Token)

Important notes

When signing JWT, IdentityUuid must be used as Claim so that Partner's authentication server can identify which user is accessing the app.
SSO Token must have an expiry time, Partner's authentication server will reject the token if no expiration is recognized.

Java

  1. Library: Java JWT
  2. Convert private key to PKCS8 by OpenSSL (click HERE to see how to set up OpenSSL)
openssl pkcs8 -in private.pem -topk8 -nocrypt -outform DER -out pkcs8.key
  1. Example code: 
File resource = new ClassPathResource("pkcs8.key").getFile(); 

byte[] privateKeyBytes = Files.readAllBytes(resource.toPath());

KeyFactory keyFactory = KeyFactory.getInstance("RSA"); 

RSAPrivateKey privateKey = (RSAPrivateKey) keyFactory.generatePrivate(new PKCS8EncodedKeySpec(keyBytes));

Algorithm algorithm = Algorithm.RSA256(null, privateKey);

String ssoToken = JWT.create().withClaim("userUuid", <identity_uuid>).sign(algorithm);

Ruby

  1. Library: Ruby JWT
  2. Example code: 
require 'jwt'

# 'Load private key from file'

private_key = OpenSSL::PKey::RSA.new(File.read('private.pem'))

# Prepare payload with userUuid as Claim

payload = { 'userUuid': '66463719-xxxx-4905-8b92-93c104a95e7e' }

# Sign Token

token = JWT.encode payload, private_key, 'RS256'

puts token

Portal Applications Access

  • Endpoint: https://<portal_domain>/sso/ 
/’ character after “sso” is required.
  • Query Params:
    • ssoToken: Signed JWT token as described above
    • orgUuid: orgUuid of the customer account in Partner's portal
    • appId: the application that the user wants to access 
  • URL pattern: https://<portal_domain>/sso/?ssoToken=<jwt>&orgUuid=<orgUuid>&appId=<appId>
  • The URL can be opened either within an iFrame or new tab of browser.
  • Example link: ​
    https://portal.hoiio.net/sso/?ssoToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1c2VyVXVpZCI6IjY2NDYzNzE5L ThkNzgtNDkwNS04YjkyLTkzYzEwNGE5NWU3ZSJ9&orgUuid=9ace93b2-69ab-4dce-8ac0-1849fe242a07&appId=4ESLmjmXaWH0jcxT
This link is an example and for reference only.


How did we do?


Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)