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. Athough 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.

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 assit you with implementing your authentication logic.

Common Parameters Available Through MAGDA

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

Auth Plugin Redirect Url

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

Its default value can be found from magda-core helm chart document.

Once the authentication plugin complete the authentication process, the plugin is required to redirect user agent to the url specified by this parameter.

When redirect the user agent, the plugin can choose to passing the following query parameters:

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

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 endpioints 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).