PHP Example Application

Vurderinger
Discusses the minimal PHP online application.

Download Example

The PHP example is located in the Online Downloads section.

Objective

  • Demonstrate Federated authentication and application approval by administrative user.
  • Demonstrate JWT/SAML token signature verification.
  • Demonstrate provisioning tasks, such as creating web panels, list items, etc.
  • Demonstrate exchanging system user token for a system user ticket.
  • Demonstrate tenant web service invocation using a system user ticket.

Application Overview

The first time the application is visited, the user will be redirected to sod.superoffice.com/login to signin to SuperID. Upon successful login, SuperID will redirect the user to the applications redirectURL (https://localhost/php/index.php).

Index.php displays several links, giving the application the opportunity to provision various types of items, as well as create a new company using the logged in admin user, or a system user. 

 

Chosing to create a new company, regardless of option to use the logged in or system user, and upon successfully creating a new company, the application will redirect to the contactEntity.php page and display the results.

 

Sequence of Execution

These sequence diagrams were built using an online resource www.websequencediagrams.com. The text used to generate these diagrams is located at the end of this document.

Create a new company as the current (Login) user.

The following diagram describes how the first link works, how to create a company using the signed in user account.

 

There are several helper classes to make things easier and are described in subsequent sections of this document.

 

Create a new company as a System User

The following diagram describes how create a company using the system user token. The key thing to understand here is that the system user token is not a usable credential. It is used in exchange for a system user ticket. The system user ticket is the usable credential for passing into web service methods.

 

As stated before, there are several helper classes to make things easier. An important one is the SystemUserHelper class. It's used to look up the current user context, gets the stored system user token, sign the token, call the tenant service and returned a server signed token containing claims.

The web application must then validated the new server token, then extract the system user ticket.

class SystemUserHelper
{
   /*
   * Sign system token from callback and authenticate it with the SuperId service
   *
   * return system user token from SuperId service
   */
   public static function GetSystemUserToken($returnTokenType) {
      $context = SessionHelper::getSoContext();

      //get private key and its path is configured in setting.php
      $privateKey = openssl_pkey_get_private(file_get_contents(PRIVATE_KEY), KEYPASSWORD);

      //SuperOffice signed format
      $signThis = ($context->SystemToken).".".date("YmdHi");

      //sign the system token using private key of the application
      openssl_sign($signThis, $signature, $privateKey, OPENSSL_ALGO_SHA256);

      //instantiate the agent to the SuperID endpoint path, NOT the tenant.
      $agent = new SystemUserAgent(LOGIN_PATH, APPTOKEN, $context->ContextIdentifier);

      //return a new JWT or SAML token containing the system user ticket
      return $agent->AuthenticateSystemUser($signThis.".".base64_encode($signature), $returnTokenType);
   }
}

 

The application must validate the new JWT/SAML token using the public SuperOffice certificates. Once validated as an authentic token, the application uses another helper class, ClaimNames, to convert the token into an SoContext class – containing properties such as Name, Company, Ticket and NetServerUrl.

With the new SoContext available, containing the Ticket credentials for a system user, the application proceeds to call the ContactEnitityHelper to create a new company.

 

if($_GET['systemUser'] == 1) {
   //use system user to create a contactEntity

   //exchange system user token for a JWT/SAML token – contains system user ticket
   $returnedToken = SystemUserHelper::GetSystemUserToken(ENABLE_SAML ? "Saml":"Jwt");

   //validate the returned token using SuperOffice public certificates
   if(ENABLE_SAML) {
      require_once('./lib/SoSAML.php');
      $data = SoSAML::decode($returnedToken, PUBLIC_CERTIFICATE);
   } else {
      require_once "./lib/SoJWT.php";
      $data = SoJWT::decode($returnedToken, PUBLIC_CERTIFICATE);
   }

   //extract the claims in the token and cast then to a SoContext class
   if($data != null){
      $context = ClaimNames::ConvertToSoContext($data);
   } else {
      $url = UrlHelper::getBaseUrl().'welcome.php';
      header("Location: $url");
   }

   //using the system user ticket to create a new company
   $contact = ContactEntityHelper::CreateContactEntity($context->NetServerUrl, $context->Ticket, APPTOKEN);

   //view the company details on the contactEntity.php page.
   $id = $contact['ContactId'];
   header("Location: contactEntity.php?contactEntityId=$id");
}

 

More Advanced Scenario

  1. This sequence represents a common scenario where a service exists that communicates with a tenant on a revolving interval.
  2. User navigates to partner application.
  3. User is not authenticated for access to SuperOffice functionality and is therefore redirected.
  4. User is redirected to SuperID with application ID for authentication.
  5. User is successfully authenticated and redirected to the partner applications redirect URL.
  6. Partner application receives SuperID request and JWT/SAML token. Validated using certificates.
  7. Partner application processes/configures user and stored system user token in database.
  8. Partner service polls database for new tenant user tokens.
  9. Partner service signs user token with private key and sends to SuperID for exchange of system user ticket. (demo private key is in the service console certificates folder).
  10. Partner service validates system user token using certificates.
  11. Partner service calls tenant web services using system user ticket.

 

 

System User Lifetime

A system user token is unique for each application authorization in a tenant and will remain the same for the lifetime of the application. Application owners are able to request the system user token be revoked or removed for a particular customer. When the partner app portal is complete, you will be able to do this yourself.

A system user ticket is only good for a short period of time. Therefore, your application must expect to operate as demonstrated for batch operations. When communicating with a tenant on a periodic basis, you must obtain a new system user ticket prior to accessing the tenant web services again.

JWT and SAML Signature Verification

Every application in production must demonstrate their application validates the token upon each successful login to SuperID within the applications callback location.

Each application must also validate each token received by SuperId when exchanging a system user token for a system user ticket. These types of checks are tested when certifying an application.

Public Key Certificates

The machine running this example must have the public certificates installed for this example to work. Please read the Online Install Certificates document.

nuSoapSample Solution

Contents in the solution include:

Solution directory contains the following:

Solution directory contains the following:

  • / web site root
  • certificates directory
    • federatedlogin.cer: certificate for SOD, used to verify tokens from SuperID.
  • helpers directory
    • ClaimHelper
    • ContactEntityHelper
    • SessionHelper
    • SystemUserHelper
    • UrlHelper
  • lib directory
    • soAgents directory
      • Agent classes for each NetServer endpoint.
    • JWT.php: Base class responsible for verifying the JWT token.
    • nusoap.php: Contains Web Services Toolkit for PHP.
    • SoAgent.php: Is the base class for all agents in the soAgents directory.
    • SoJWT.php: SuperOffice wrapper around the base class in JWT.php.
    • SoSAML.php: Class responsible for verifying the SAML token.
    • SystemUserAgent.php: Class responsible for calling PartnerSystemUserService endpoint to exchange a system user token for a JWT or SAML token that contains a system user ticket.
  • WSDL directory: contains the following:
    • 7.3 directory: contains all wsdl files for NetServer 7.3.
    • 7.5 directory: contains all wsdl files for NetServer 7.5.
    • PartnerSystemUserService.wsdl for Token => Ticket exchange with SuperID.
  • callback.php: the page that receives a POST after a user successfully logs into SuperID.
  • contactEntity.php: the page responsible for displaying company details.
  • createFollowUpListItems.php: a page that demonstrates creating a followup list item.
  • createProject.php: a page that demonstrates how to create a new Project.
  • createSaleType: a page that demonstrates how to create a new Sale Type.
  • createUserDefinedField: a page that demonstrates how to create a new user defined field.
  • createWebPanel: a page that demonstrates how to create a new web panel.
  • getWebPanels: a page that demonstrates how to get all web panels.
  • header.php: the page responsible checking authorized session.
  • index.php: the page that starts the federated login process with SuperID.
  • reset.php: the page that removes session state. Useful when relogin is desired.
  • settings.php: the file containing all of the configuration settings this project has.
    • Use this file to specify:
      • Application ID
      • Application Token
      • NetServer Version
      • Protocol
      • SuperID URL
      • Certificate path
      • Token type (JWT/SAML)
  • webServiceCall.php: the page that demonstrates instantiating the ContactAgent and invoking both the GetContactEntity and SaveContactEntity methods.
  • welcome.php: the page that displays a link to the index page.

 

Summary

Building online PHP apps for SuperOffice CRM Online is not only possible, but by leveraging a useful library such as nusoap makes it simple and effective. 

Legg ut kommentar Til toppen