magda-auth-template

A Magda Authentication Plugin Template. You can use this as a base to build your own Magda Authentication Plugin.

Requires MAGDA version 0.0.58 or above.

How to Use

1. Add the auth plugin as a Helm Chart Dependency

- name: magda-auth-xxx
  alias: magda-auth-my-idp
  version: x.x.x
  repository: https://charts.magda.io

Please note: alias field is optional. Its purpose is to give the helm chart an alias name (rather than the default magda-auth-xxx chart name) so it's possible to use magda-auth-xxx plugins multiple times (for different idps) in your deployment. When alias is not specified, you should reference its name as magda-auth-xxx.

2. Config the auth plugin with required parameters

magda-auth-my-idp:
  param1: value1
  param2: value2
  # setting authPluginConfig is optional; only when you've specified alias name and want to support multiple oidc idps at the same time
  authPluginConfig:
    key: "my-idp"
    name: "Login to My IDP"

When alias is not specified when define Helm Chart Dependency, you should reference its name as magda-auth-xxx in your config.

3. Config Gatway to add the auth plugin to Gateway's plugin list (More details see here)

gateway:
  authPlugins:
  # key should match the `authPluginConfig.key` you set above.
  # If you didn't specify, it should be `xxx` by default
  - key: "my-idp"
    # baseUrl should be http://[alias name of the auth plugin].
    # If you didn't specify, it's `http://magda-auth-xxx` by default.
    baseUrl: http://magda-auth-my-idp

About this document

This document is auto-generated from helm chart values file comments and template README.md.gotmpl using helm-docs.

Once you installed helm-docs, you can re-generate the docs by running:

yarn helm-docs

How to use this template repo

To generate a new repo from this template repo, please see here.

If you are new to this, please have a read Authentication Plugin Specification.

Once you create a new repo, you can:

• Replace magda-auth-template keywords with your auth plugin name
• Add your authentication logic to createAuthPluginRouter.ts
  • You can find passport.js strategies that support different IDPs (identity providers) or authentication servers from here.
• Update authentication config in index.ts
• Update environment variable defined in github action workflow files to your config to get Github Action CI running.

Magda provides NPM packages @magda/authentication-plugin-sdk and @magda/auth-api-client that you may need to implement your authentication logic.

To release a docker hub image & helm chart, just create a release in your Github repo. This will trigger the CI job to:

• Run test cases (if any)
• Build the docker image
• Publish docker image to Docker Hub
• Publish the helm chart to your S3 bucket

How to Customise Authentication Process

Here is an example (based on magda-auth-google) to show: How you can :

• Decide & Set user's organisation unit by matching user's profile
• Decide & set user's role by matching user's profile
• Customised session data
• More non-authentication related HTTP endpoints

Requirements

Kubernetes: >= 1.14.0-0

Repository	Name	Version
https://charts.magda.io	magda-common	1.0.0-alpha.4

Values

Key	Type	Default	Description
authPluginConfig.authenticationMethod	string	"IDP-URI-REDIRECTION"	The authentication method of the plugin. Support values are: IDP-URI-REDIRECTION: the plugin will redirect user agent to idp (identity provider) for authentication. e.g. Google & facebook oauth etc. PASSWORD: the plugin expect frontend do a form post that contains username & password to the plugin for authentication. QR-CODE: the plugin offers a url that is used by the frontend to request auth challenge data. The data will be encoded into a QR-code image and expect the user scan the QR code with a mobile app to complete the authentication request. See Authentication Plugin Specification for more details
authPluginConfig.iconUrl	string	"/icon.svg"	the display icon URL of the auth plugin.
authPluginConfig.key	string	"test-auth-plugin"	the unique key of the auth plugin. Allowed characters: [a-zA-Z0-9-]
authPluginConfig.loginFormExtraInfoContent	string	""	Optional; Only applicable when authenticationMethod = "PASSWORD". If present, will displayed the content underneath the login form to provide extra info to users. e.g. how to reset password Can support content in markdown format.
authPluginConfig.loginFormExtraInfoHeading	string	""	Optional; Only applicable when authenticationMethod = "PASSWORD". If present, will displayed the heading underneath the login form to provide extra info to users. e.g. how to reset password
authPluginConfig.loginFormPasswordFieldLabel	string	"Password"	Optional; Only applicable when authenticationMethod = "PASSWORD".
authPluginConfig.loginFormUsernameFieldLabel	string	"Username"	Optional; Only applicable when authenticationMethod = "PASSWORD".
authPluginConfig.name	string	"Test Auth Plugin"	the display name of the auth plugin.
authPluginConfig.qrCodeAuthResultPollUrl	string	""	Only applicable & compulsory when authenticationMethod = "QR-CODE". The url that is used by frontend to poll the authentication processing result. See Authentication Plugin Specification for more details
authPluginConfig.qrCodeExtraInfoContent	string	""	Only applicable & compulsory when authenticationMethod = "QR-CODE". If present, will displayed the content underneath the login form to provide extra info to users. e.g. how to download moile app to scan the QR Code. Can support content in markdown format.
authPluginConfig.qrCodeExtraInfoHeading	string	""	Only applicable & compulsory when authenticationMethod = "QR-CODE". If present, will displayed the heading underneath the QR Code image to provide extra instruction to users. e.g. how to download moile app to scan the QR Code
authPluginConfig.qrCodeImgDataRequestUrl	string	""	Only applicable & compulsory when authenticationMethod = "QR-CODE". The url that is used by frontend client to request auth challenge data from the authentication plugin. See Authentication Plugin Specification for more details
authPluginRedirectUrl	string	nil	the redirection url after the whole authentication process is completed. Authentication Plugins will use this value as default. The following query parameters can be used to supply the authentication result: result: (string) Compulsory. Possible value: "success" or "failure". errorMessage: (string) Optional. Text message to provide more information on the error to the user. This field is for overriding the value set by global.authPluginRedirectUrl. Unless you want to have a different value only for this auth plugin, you shouldn't set this value.
autoscaler.enabled	bool	false	turn on the autoscaler or not
autoscaler.maxReplicas	int	3
autoscaler.minReplicas	int	1
autoscaler.targetCPUUtilizationPercentage	int	80
defaultAdminUserId	string	"00000000-0000-4000-8000-000000000000"	which system account we used to talk to auth api The value of this field will only be used when global.defaultAdminUserId has no value
defaultImage.imagePullSecret	bool	false
defaultImage.pullPolicy	string	"IfNotPresent"
defaultImage.repository	string	"docker.io/data61"
global	object	{"authPluginRedirectUrl":"/sign-in-redirect","externalUrl":"","image":{},"rollingUpdate":{}}	only for providing appropriate default value for helm lint
image.name	string	"magda-auth-template"
replicas	int	1	no. of initial replicas
resources.limits.cpu	string	"50m"
resources.requests.cpu	string	"10m"
resources.requests.memory	string	"30Mi"