Javascript Sample to demonstrate managing the lifecycle of your application

Roger K

As a developer on OpenText Cloud Platform, the lifecycle of your application can be represented by the flow above. You deploy your application; when they sign-up you provision your subscriber; your subscriber adds users to the application and then they use the application. The Develop Application step is really just a special iterative case of all the other following steps and so this article will follow the flow from Deploy Application onwards.

OpenText has now provided an open source Javascript sample which implements this flow using the Developer Admin API (see here) and the sample can be downloaded from Github here. Additional information on working with Developer can be found here.

Managing all of this are a number of key concepts:

• An Organization is your business account within a Region
• The Org owner is a Developer who is authenticated with the OT platform using our OT Connect customer system
• The Developer creates multi-tenanted apps owned by the Organization
• Organization creates, owns and manages tenants for application subscribers
• A Subscriber’s tenant is subscribed to the developer’s application

API Authentication

For secure API access from your application to the platform to perform these management actions you will make use of two different Oauth security schemes or contexts:

1. The organization security scheme is for APIs which manage Org owned entities – the entities you own – the Organization itself, your applications and your subscriber tenants
2. The tenant security scheme is for APIs which manage Tenant owned entities – Tenant or Subscriber owned entities such as users, which applications they use and how they are authenticated AND the sandboxed information management service API calls made by users - e.g. to content storage, workflow, etc.

The Developer Admin API documentation here covers how to authenticate with the platform using these two security schemes. The sample application provides implementations of these two security schemes to gain the required access tokens for the proceeding API calls in the sample.

Retaining IDs

When performing the above lifecycle for real you will need to maintain key entity IDs returned in responses. You will retain these as references within your application database. These references are UUIDs generated by the platform. Examples are:

1. applicationId
2. tenantId
3. authenticatorId
4. userId

The sample webapp presents these ids in the response data within the UI from where they can be copy and pasted into subsequent requests within the webapp.

Deploy Application

Assuming you have successfully developed and tested your application, the first thing you’re going to need to do is deploy your application.

There are two steps to this:

1. Creating the application
2. Configuring the callback URL for your user authentication flows

All of this can be done via the Console UI as it is an infrequent activity but the sample app will show how you do it with API calls using the organization security scheme. Within the sample webapp, steps 1 & 2 are performed from the Organization page. 

Provision Subscriber

Having deployed your application onto the platform – you now need to provision a subscriber to use the application – and you’ll do this each time you on-board a subscriber. Within the sample, steps 1 & 2 are also performed from the Organization page of the sample webapp.

There are three core steps to provisioning a subscriber:

1. Provision subscriber sandbox – in OpenText terminology, the tenant
   • A tenant provides full isolation between subscriber data
   • Only tenant users can be given access to the tenant and its data
2. Provision your application to the newly created subscriber tenant
   • Users are given access to applications and their data via a tenant with which they authenticate
   • Multiple applications can be provisioned to the same tenant
3. Set-up external identity provider, which is your application or an IdP you application uses, for tenant users, in OpenText terminology, authenticators

The sample application shows how steps 1 and 2 are performed via API call within the organization security scheme. Within the sample, steps 1 & 2 are also performed from the Organization page of the sample webapp. 

Step 3 is performed using an identity authenticated using the tenant security scheme. Within the sample, step 3 is performed from the Tenant page of the sample webapp. However, since most, if not all your users will use a custom rather than the built-in platform authenticator then you will create the authenticator before you create users, and so the order above represents the order you are likely to perform subscriber provisioning.

Add Subscriber Users to Application

There are two simple steps to this - and you'll do this each time you onboard a new user for a subscriber:

1. Create the user within the tenant/sandbox
2. Add them to the application

The sample application shows how steps 1 and 2 are performed via API call within the tenant security scheme. When the user is created the request body of user meta-data contains the authenticatorId of the external authenticator (IdP) configured for your application. Within the sample, steps 1 & 2 are performed from the Tenant page of the sample webapp.

Use the Application

Having done all of that - your users are now in a position to login and use your application – but in order for that to work there are a number of key requests each time a user logs-in:

1. Authenticate the subscriber user using your identity provider, using the authenticator previously configured for the user. The sample shows how this can be done from a Single Page App (SPA) – a public or untrusted Oauth client - using Auth Code grant flow with PKCE
   1. Authenticate the user against IdP using their authenticator and obtain an Authorization Code
   2. Exchange the Auth Code for an Access Token to OT platform and get back other tokens in the response
2. Call the required Information Management APIs as the user in the context of the subscriber’s sandbox/tenant using the Access Token

The sample web app shows how step 1a is performed via a browser request and step 1b via API call within the tenant security scheme. Step 2 is also uses the tenant security scheme using the access token obtained in step 1b. The sample webapp illustrates Step 2 through API calls to the CMS API to upload and download a JSON document.

Within the sample, steps 1 & 2 are performed from the User page of the sample webapp.