Authenticated Extensions

Introduction

An authenticated embed is a web application that can be embedded into Portal as an extension and receives authentication information about the current user.

Setup

Since embeds are simply web pages embedded in a sandboxed iframe within Portal, you have full control on how to validate the request. Session storage with cookies will work as you might expect with any web browser.

However, for added security you might also consider the following options.

Setting a Content Security Policy

Restricting the domains that are allowed to embed your app is a simple way to ensure that your app is not used outside your preferred contexts. Additionally, if you are trying to embed a web page that has an existing content security policy in place, you will need to update that page’s content security policy accordingly.

The HTTP Content-Security-Policy frame-ancestors directive should be updated as follows:

Content-Security-Policy: frame-ancestors https://*.joinportal.com https://<custom portal domain>;

Get Client Data

To verify that your app is being requested by Portal, you can check the query parameters passed to your application. The query param will either be companyId or clientId that corresponds to the id of the company or client associated with the extension channel that is being rendered.

You can call the Retrieve a client or Retrieve a company endpoint from the Portal API with this id and your provided API key which will return a Client or Company resource that can be used in rendering your app. The client resource includes a companyId so if your extension is setup to pass the clientId query param you can still get company information by first retrieving retrieving a client and then retrieving a company.

The Client resource also includes the values set to their custom fields.

The keys in the customFields property are ids of the different custom field properties. When you create a custom field in your Portal, there will be an id generated for that property. Portal uses that id when setting a value for a client user’s custom field property.

E.g you might have a custom field in your Portal called “Notes” which has a generated id of c9b33f2b-97d8-4bcd-b9ad-2bb8acfc70cc. When you request a client resource that has this property set the custom fields would like like:

"customFields": {
    "c9b33f2b-97d8-4bcd-b9ad-2bb8acfc70cc": "Example Text", // this is the value for the Notes custom field
}

To correlate the keys in the customFields property to their names you can also get the custom field metadata from the Portal API. It is recommended to do this once and store the relevant ids that your application needs so that you do not need to make an extra api call to request this metadata.

Getting Custom Field Metadata

To get further information about the custom fields based to understand what the keys in the customFields property represent you can query the custom fields resource.