Skip to content

Latest commit

 

History

History
150 lines (93 loc) · 6.62 KB

overview.md

File metadata and controls

150 lines (93 loc) · 6.62 KB
Raw
title uid description author keywords topic envir client
Minimal C# application
minimal_csharp_app_overview
Minimal C# application
github-id
tutorial
cloud
online

Minimal C# application

So - you want to build applications that work in the SuperOffice Online Development (SOD) environment. Let's look at how to use a system user when interacting with SuperOffice Online tenant web services.

This example is based on C# ASP.NET MVC and a console application.

Assumptions

We assume that you understand what SuperOffice CRM Online is and that you have a working knowledge of programming in C#, certificates, and JWT tokens.

Prerequisites

  • Visual Studio 2013 (or later)
  • .Net 4.8 framework
  • You have configured certificates on your SOD machine
  • You have a Temp folder on the C:\ drive to store system user tokens.

Tip

Run Visual Studio as administrator. If the SuperOffice.Online.SuperIdDemoApp project fails to load, it is probably because your Visual Studio is not run as administrator.

Functional components

There are 4 projects in the SystemUserApps.sln solution:

ASP.NET MVC application

This is an application that represents the minimum an App Store application is required to handle. The essentials include:

  • authenticating an administrator installing the application
  • obtaining a system user ticket

Console application

This is a mock-up of a partner service that periodically checks the file for new tenants. It demonstrates how to obtain a system user ticket from a system user token.

Shared partner data source

This example uses an XML file to store system user tokens for SuperOffice online tenants.

CustomerDataSource is located in the SuperOffice.DevNet.Online.SystemUser.PartnerDBLibrary project.

Application overview

The 1st time the web application runs, the default page will detect that the current user hasn't signed in to this application and it will redirect the user to the SuperOffice federation gateway (SuperID) for authentication.

The client ID is added to the URL that is passed to SuperID. The ID is registered in SuperID’s Operation Center (OC). By looking up the ID, SuperID can learn the redirect URLs of your application.

x

Application approval page

After successful authentication, the application approval page is presented to the user. This page displays an I approve button, which must be clicked to allow the application to access to the customers’ web services and database.

In the future, the approval page may expose additional controls such as checkboxes for more specific rights.

x

HomeController

HomeController.cs is the default action and its responsibility is to check if the current user is signed in. If the current user is not signed in, the home controller will redirect the user to the SuperID sign-in URL (SuperOffice Federation Gateway).

The home controller uses a security attribute class defined in SuperOfficeAuthorizeAttribute.cs, located in the SuperOffice.Online.PartnerLogin project.

Tip

The URL for SuperID is located in the appSettings section of the App.Config file and Web.Config file.

The client ID is appended to the URL when redirected to SuperID. This is done so that SuperID knows what application sent the user to sign in, and where SuperID must redirect the user once the user has been successfully authenticated.

CallbackController

The responsibility of CallbackController.cs is to validate the JWT token issued by SuperID and establish a user context. It is called after a user is successfully authenticated by SuperID.

The token contains all of the claims a partner's application needs to connect to and communicate with the user tenant in SuperOffice Online.

The user context will be used by the web application for all successive calls to the tenant web services. It is managed in the PartnerHttpContext class defined in the SuperOffice.Online.PartnerLogin project.

  1. SuperID will use the client ID to determine where the user is redirected. The default redirect URL of the example application is http://localhost/SuperOffice.Online.SuperIdDemoWeb/Callback

  2. SuperID passes the JWT token with claims in the redirect response.

  3. The callback controller establishes the current user context.

  4. It also adds the system user token to a database.

  5. The user is redirected to the application default page after completion.

Note

The redirect URL can be changed if requested. Future capabilities will enable you to change it yourself, but for now, you must send an email to have it changed for you. Redirect URL change requests can be sent to sdk@SuperOffice.com.

ContactEntityController

ContactEntityController.cs is used to demonstrate how to create a new company using the current user.

SystemUserController

SystemUserController.cs is used to demonstrate how to create a new company using the system user.

This controller leverages the SystemUserHelper class and then redirects the results to the ContactEntityController for displaying the new company details.

SystemUserHelper

SystemUserHelper.cs contains the code that demonstrates the key aspects of this example:

  1. Sign a system user token with a private key
  2. Exchange a system user token for a security token that contains a system user ticket
  3. Validate a security token
  4. Use the security token to establish a tenant context (Database Context)
  5. Authenticate as a system user using the system user ticket

Private key

The private key (partnerprivatekey.xml) is responsible for signing the system user token before sending a request to receive a system user ticket from SuperID.

This happens in step 8 of our scenario.

When a user clicks Install SuperOffice Maps, the application checks to see if you are already logged into SuperID:

  • If logged in, the user is redirected to the LoginRedirect.aspx page.
  • If not, the application redirects to the SuperID login page.