Hosted Applications

Applications Overview

The ‘application’ concept includes several key concepts:

1. Authentication Clients. These are called ‘client id’ or ‘applications’ in other Single-Sign On and Identity platforms
2. Roles. A Role is an intrinsic set of permissions a user might have (e.g. Administrator, Editor, etc)
3. Rules. A Rule is an authorisation firewall configuration. E.g. /admin/.* can be accessed via GET/POST/PUT for Administrators
4. Image Runtime. If the application is hosted on the Agilicus platform this will be a container (or a runtime for a bundle)
5. Bundle. A zip file which will be mounted into a Runtime. This might be the output of a npm build for example, or a set of PHP files
6. Proxy. This is a feature which remaps, provides security, upgrades security headers.
7. Instance. Applications can have multiple concurrent running configurations. An ‘Instance’ is a specific subset (e.g. production versus staging)
8. Status. For hosted applications this will show their running state.

In the lifecycle of an Application, you may create it with ‘New’ following a guided setup process. You may then refine or edit the configuration with ‘Define’. You may also define an application from empty using ‘Define’.

The Overview screen shows the current applications and allows editing them.

New

This will create a New application using a guided process. Typically use the ‘a new application’ option unless there is a pre-configured template for your well-known application.

Prior to starting here you should have created a Network Connector to the site hosting the web application / API.

After the first question, you will be asked to provide 3 facts in ‘Define Application’:

1. Enter the application name. This will become a HOSTNAME in DNS, so it must be valid (no spaces)
2. Describe the application. This is for you, it will show later in some reports.
3. Enter the application category. This is for you, it will allow aggregating some reports. E.g. ‘HR’

Next, you will be asked if you wish a hostname alias. This allows you to override the well-known pattern of the Agilicus platform (APPNAME.DOMAINNAME) with a special one. This might be e.g. ‘wiki.mycompany’ instead of ‘wiki.cloud.mycompany’.

1. I access via <appname>.<domainname>
2. I access via an alternate hostname that I have setup manually

Next, you will setup how the users Access this application. You have 4 choices:

• Over the public Internet. The application is hosted by a SaaS provider or is otherwise publicly available without a firewall. The Agilicus platform can be used to provide authentication services via the Authentication Clients. No firewall rules are applid.
• From my site via an onsite connector. The application runs inside a private datacentre or a virtual private cloud and an Agilicus Connector is used to reach and expose it.
• From my site via a point-to-point VPN. Similar to the onsite connector but an ipsec site-to-site VPN has been pre-configured
• From the Agilicus Cloud. The application is hosted within the Agilicus platform

Typically Option #2 will be used (From my site via an onsite connector). Once you select this, a new set of options to configure the web application firewall will appear:

• My application expects to receive requests using its internal hostname. — Some web applications require a remap from e.g. https://EXTERNALNAME to http://INTERNALNAME, the firewall will make these changes.

• Select Connector. Here you will select he previously configured network connection.
• Data Path Processing. Here you will configure the encryption and logging method. If you select ‘Fine Graind Access Logs”, there will be two TLS segments, with the Agilicus web application firewall in the middle. If you select ‘End to End Transparent TLS” the encryption will be done within your site, and there will be no access logs generated.
• Enter upstream Service. Here you will put the hostname and port as if you were accessing from onsite. This should be resolvable by the onsite connector. It might be e.g. “web.internal” and port “8888”. If you select “my service is accessed via TLS” this means that the *internal* site currently is encrypted (the external one will always be). You may also indicate if the TLS certificate of the internal site is publicly valid.

Next you will configure the Authentication. You may:

• Does not require authentication. The site is a read-only website that anyone can use
• Participates in Authentication. The application implements OpenID Connect or SAML
• Is authenticated by proxy. The Agilicus platform will take care of single sign on authentication

You may also see “My application is also launched from a Desktop.”. This applies, for example, to Microsoft ClickOnce where a start-menu icon might be used.

At this stage you may Apply, and then move to the ‘Overview’ screen to observe and refresh status.

Overview

The Applications Overview lets you see at a glance each running application, and select one to edit (define) it.

The ‘Status’ is mostly applicable to hosted applications.

• name: the name you gave the application. This will also be the hostname (e.g. what you type into a browser in https://name)
• Description: as you provided in ‘New’
• Image: this is only pertinent if you are running a hosted application inside the Agilicus platform
• Image Tag: this is only pertinent if you are running a hosted application inside the Agilicus platform
• Admin State: the application can be temporarily rendered inactive for diagnostics
• Status: the running state when hosted inside the Agilicus platform. Multiple concurrent copies are run for redundancy.

The actions that are present here:

• Delete application: remove the definition, remove from service
• Enable application: set the admin state to ‘active’
• Disable application: set the admin state to ‘disabled’
• Define new: create a new application without the guided setup

Additionally, if you click on any row it will navigate directly to the Define screen for updates.

Define

The ‘Define’ screen may be used to create a net new application, or to update the definition of an existing one.

This screen has 4 main tabs (Common/Hosting/Security/Proxy), each configuring a subset.

Common

The ‘Common’ tab setups up configuration which is present on all instances, all configurations. This includes:

• Name: the hostname this application will be addressed (do not include domain name)
• Category: this is for your use, e.g. “HR”
• Description: a textual string shown on the overview screen
• Contact Email: if filled in and there is a problem the Agilicus team may contact this
• Port: This is only used if the application is hosted inside the Agilicus platform on a container you provide.
• Image Runtime: This is either
  • identity-aware WAF proxy — your application is exposed by an identity-providing proxy
  • one of the ‘core’ predfined — your application is a bundle run within this environment
  • unused — your application runs on your site or elsewhere
• Publish Application — the application will appear in https://profile.YOURDOMAIN for your end users to discover
• External — the application exists solely to create an authentication client, there is no data flow
• Logo — this will be shown in https://profile.YOURDOMAIN. The logo should be square (e.g. 256×256) and in png format

Hosting

Only use this tab if you are running an application inside the Agilicus platform. This means you are providing a container image. This is not a common use case, and most users will not use this tab.

There are two areas: “Instances” and “Bundles”

Instances

An ‘instance’ is a separate running copy of the application, which in turn has some specific configuration overrides. For customers who have multiple organisations (e.g. Production, Staging), this allows them to run multiple copies with different versions.

The columns:

• Tag: only set this if you have provided your own container, it will be the image-tag (e.g. group/image:tag). If using one of the built-in runners please leave it set as ‘latest’
• Owner: this column sets which organisation ‘owns’ or can change the application. This is used to share an application into other organisations
• Organisations: which orgs this will show up in
• Bundle Names: Use this to mount a file into a runner (e.g. a zip file of php files)
• Status: this will show the current running status
• Actions: this will go to a details screen (below) to set instance-specific parameters

Instance Details

In the ‘configure instance’ details screen, entered from the action button on the instance, we can configure:

• image(version) tag: Tag: only set this if you have provided your own container, it will be the image-tag (e.g. group/image:tag). If using one of the built-in runners please leave it set as ‘latest’
• Owner: this column sets which organisation ‘owns’ or can change the application. This is used to share an application into other organisations
• Organisations: which orgs this will show up in
• Bundle Names: Use this to mount a file into a runner (e.g. a zip file of php files)
• Fully-qualified domain names: This allows setting an ‘alias’, and is the same affect as setting the ‘I access via’ hostname in the ‘New’. The same caution applies: ensure that your DNS has an alias (CNAME) for the name you enter here. Enter a fully-qualified name (e.g. HOSTNAME.DOMAINNAME).

In addition there are some status fields:

• Status: stale/good
• Running replicas: the number of currently running copies, this will scale up and down
• Error message: any error detail
• Restarts: the number of times the application has unexpectedly restarted
• Last Apply Time: the last time changes were applied to the running system
• Running image: the version currently executing
• Running hash: the container hash currently executing

There is also some configuration related to files/environment/mounts/temp. These are:

• File: this allows you to upload a single file and have it placed in the running image at a given location
• Environment: set environment variables to configure your application
• External Mounts: mount an external filesystem (e.g. SMB) into your running container
• Temporary Directories: Create a directory which will be used for read-write scratch files

Bundles

A bundle is a zip-file containing support files of your application. These will be interpreted by the runtime container, mounted within it.

Security

The security tab allows controlling the Authorisation rules and the Web Application Security. These are discussed separately on their respective pages.

Proxy

The proxy configuration allows setting up HTTP header and body rewriting, overrides, and upstream configuration. This is discussed separately on the Proxy page.

Diagnose

Hosted applications may produce diagnostic logs. These are available by date range and application, and may be downloaded as CSV for offline analysis.