README.md.gotmpl

{{ template "chart.header" . }}

{{ template "chart.deprecationWarning" . }}

{{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }}{{ template "chart.appVersionBadge" . }}

{{ template "chart.description" . }}

Requires MAGDA version 0.0.58 or above.

### How to Use

1. Add the auth plugin as a [Helm Chart Dependency](https://helm.sh/docs/helm/helm_dependency/)
```yaml
- 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
```yaml
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](https://helm.sh/docs/helm/helm_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](https://github.com/magda-io/magda/blob/master/deploy/helm/internal-charts/gateway/README.md))
```yaml
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](deploy/magda-auth-template/values.yaml) comments and template [README.md.gotmpl](./README.md.gotmpl) using [helm-docs](https://github.com/norwoodj/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](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template).

If you are new to this, please have a read [Authentication Plugin Specification](https://github.com/magda-io/magda/blob/master/docs/docs/authentication-plugin-spec.md).

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](./src/createAuthPluginRouter.ts)
  - You can find passport.js `strategies` that support different IDPs (identity providers) or authentication servers from [here](http://www.passportjs.org/packages/).
- Update authentication config in [index.ts](./src/index.ts)
- Update environment variable defined in [github action workflow files](./.github/workflows) to your config to get [Github Action](https://docs.github.com/en/free-pro-team@latest/actions) CI running.

> Magda provides NPM packages [@magda/authentication-plugin-sdk](https://www.npmjs.com/package/@magda/authentication-plugin-sdk) and [@magda/auth-api-client](https://www.npmjs.com/package/@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](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/managing-releases-in-a-repository#creating-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](https://github.com/magda-io/magda-auth-google/commit/f8d6ce53c64b8f1de9a64daf1a6ee2358177d39e) (based on [magda-auth-google](https://github.com/magda-io/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


{{ template "chart.maintainersSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesHeader" . }}

{{ template "chart.valuesTable" . }}