Authentication Plugin Specification

Since v0.0.58, Magda allows you to build external authentication plugins to add support to different authorization servers / identity providers. It also allow you to customise the process of creating & mapping the user’s profile to a local user (e.g. assign specific roles depends on users’s profile).

An authentication plugin, technically, is a set of HTTP services that are integrated with Magda gateway and the frontend UI. Although it is not compulsory, we recommend you to use express.js & passport.js to build the HTTP services for your authentication plugin. You will find all our existing authentication plugins are build with express.js & passport.js.

For general usage info of Authentication Plugin, please refer to this document.

Build Your Own Authentication plugin

For ease of deployment, Magda requires an authentication plugin to be build as a docker image, packed as a Helm Chart and to be used by your Magda deployment as Helm chart dependencies.

you don’t have to start from scratch to create your own authentication plugin. Instead, you can use this Github template repo to create a blank project. Github template repo can help to generate a new repository with the same directory structure and files as an existing template repository. You can find out more details from here.

After a new repo is generated from the template, you can start to implement your own authentication logic and required HTTP endpoints in src/createAuthPluginRouter.ts. If you use passport.js, you can find passport.js strategies that support different IDPs (identity providers) or authentication servers from passportjs website Strategies section.

The template also comes with CI scripts that can automatically pushing docker image to docker hub and publish helm chart to s3. For more details, please check magda-auth-template repo README.md file.

Magda also provides NPM packages @magda/authentication-plugin-sdk and @magda/auth-api-client that can assist you with implementing your authentication logic.

Common Parameters Available Through MAGDA

When deploy with MAGDA, here are a list of common parameters are made available to the authentication plugin via various ways.

Auth Plugin Redirect Url

This config value is available through Helm chart value global.authPluginRedirectUrl.

The Auth Plugin’s helm chart config should also let you config / override the redirect url via Auth Plug’s helm chart config field config.authPluginRedirectUrl.

Once the authentication plugin complete the authentication process, the plugin is required to redirect user agent / web browser to the url specified by this config value.

When the user agent / web browser is redirected, the plugin can choose to passing the following query parameters to flag the authentication outcome:

The default value of this config value is /sign-in-redirect which is a default landing route that leads to the user’s account page.

The authPluginRedirectUrl config can also be an full URL string rather than a URL path (which imply current domain).

However, unless an external domain is added to authPluginAllowedExternalRedirectDomains config, an auth plugin should never redirect the user to the external domain.

authentication-plugin-sdk provides function redirectOnSuccess, redirectOnError & getAbsoluteUrl to generate the redirection.

Allowed External Redirect Domains

An auth plugin should never redirect the user to an external domain unless an external domain is added to a whitelist.

The external domain whitelist can be configured via global.authPluginAllowedExternalRedirectDomains helm chart config value.

The auth plugin should simply ignore the domain part of the url, when the host part of the url is not on the whitelist. And only redirects the user to the URL path under the current domain.

Cookie options are required by authentication-plugin-sdk to create session that meet Gateway’s requirements.

This parameter is made available through configMaps gateway-config key cookie.json.

Required HTTP endpoints

Your auth plugin can choose to serve any endpoints as you want. All HTTP endpoint will be exposed by Magda Gateway at path /auth/login/plugin/[your auth plugin key]/*.

Below are a list of compulsory HTTP endpoints that an auth plugin is required to implement in order to integrate with Magda Gateway & UI.

GET /config Endpoint

This endpoint is required to response the auth plugin’s config information in JSON format. Possible fields are:

Please note: any url fields required as part of the auth config don’t have to be an absolute url. If you supply a relative URL (e.g. /config), other components of Magda know to how to convert it to an external accessible URL (e.g. /auth/login/plugin/[your auth plugin key]/config).

GET / Endpoint

The GET / Endpoint is supported by all authentication plugins types. When accessed by a user’s web browser:

If you use Passport.js to build your auth plugin, this will be handled via passport.authenticate() method.

POST / Endpoint

The POST / Endpoint is only supported by PASSWORD type plugin. The plugin expects two fields username & password are posted to this endpoint in application/x-www-form-urlencoded encoding (HTML form post).

If you use Passport.js to build your auth plugin, this will be handled via passport.authenticate() method.

Auth Plugin Icon Endpoint

An auth plugin is required to serve an 36x36 image file to be used by Magda UI to be displayed on the authentication options list. This url is required to be set as the value of iconUrl field of the auth plugin config (see GET/configEndpoint above).

Get /logout Endpoint (Optional)

If the auth plugin want to request identity provider to log a user out when the user logs out Magda in order. The auth plugin can choose to: