Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update "Authentication" Plugins #6824

Merged
merged 19 commits into from
Apr 15, 2022
Merged

docs: update "Authentication" Plugins #6824

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
36f6cb6
Update authz-casbin docs
pottekkat Apr 11, 2022
c203fe4
Update authz-casdoor docs
pottekkat Apr 11, 2022
31753d4
Update authz-keycloak docs
pottekkat Apr 11, 2022
51857ba
Update basic-auth docs
pottekkat Apr 11, 2022
486ff56
Update forward-auth docs
pottekkat Apr 11, 2022
608722f
Update hmac-auth docs
pottekkat Apr 11, 2022
7f4841c
Update jwt-auth docs
pottekkat Apr 11, 2022
ee0fccc
Update key-auth docs
pottekkat Apr 11, 2022
6431ccb
Update ldap-auth docs
pottekkat Apr 11, 2022
7035f0c
Update opa docs
pottekkat Apr 11, 2022
8fc1430
Update openid-connect docs
pottekkat Apr 11, 2022
9d829c7
Update wolf-rbac docs
pottekkat Apr 11, 2022
a7570b0
Merge branch 'master' into docs/plugin-authentication/6734
pottekkat Apr 11, 2022
9145dc9
fix lint errors
pottekkat Apr 11, 2022
7308275
Merge branch 'docs/plugin-authentication/6734' of https://github.com/…
pottekkat Apr 11, 2022
96bea0f
Merge remote-tracking branch 'upstream/master' into docs/plugin-authe…
pottekkat Apr 12, 2022
ec18d92
Update docs/en/latest/plugins/hmac-auth.md
pottekkat Apr 12, 2022
141e0b4
apply suggestions from the review
pottekkat Apr 12, 2022
0f57da8
apply suggestions from review
pottekkat Apr 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 51 additions & 38 deletions docs/en/latest/plugins/authz-casbin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: authz-casbin
keywords:
- APISIX
- Plugin
- Authz Casbin
- authz-casbin
description: This document contains information about the Apache APISIX authz-casbin Plugin.
---

<!--
Expand All @@ -23,34 +29,40 @@ title: authz-casbin

## Description

`authz-casbin` is an authorization plugin based on [Lua Casbin](https://github.com/casbin/lua-casbin/). This plugin supports powerful authorization scenarios based on various access control models.

For detailed documentation on how to create model and policy, refer [Casbin](https://casbin.org/docs/en/supported-models).
The `authz-casbin` Plugin is an authorization Plugin based on [Lua Casbin](https://github.com/casbin/lua-casbin/). This Plugin supports powerful authorization scenarios based on various [access control models](https://casbin.org/docs/en/supported-models).

## Attributes

| Name | Type | Requirement | Default | Valid | Description |
| ----------- | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
| model_path | string | required | | | The path of the Casbin model configuration file. |
| policy_path | string | required | | | The path of the Casbin policy file. |
| model | string | required | | | The Casbin model configuration in text format. |
| policy | string | required | | | The Casbin policy in text format. |
| username | string | required | | | The header you will be using in request to pass the username (subject). |
| Name | Type | Required | Description |
|-------------|--------|----------|----------------------------------------------------------------------------------------|
| model_path | string | True | Path of the Casbin model configuration file. |
| policy_path | string | True | Path of the Casbin policy file. |
| model | string | True | Casbin model configuration in text format. |
| policy | string | True | Casbin policy in text format. |
| username | string | True | Header in the request that will be used in the request to pass the username (subject). |

:::note

You must either specify the `model_path`, `policy_path`, and the `username` attributes or specify the `model`, `policy` and the `username` attributes in the Plugin configuration for it to be valid.

**NOTE**: You must either specify `model_path`, `policy_path` and `username` in plugin config or specify `model`, `policy` and `username` in the plugin config for the configuration to be valid. Or if you wish to use a global Casbin configuration, you can first specify `model` and `policy` in the plugin metadata and only `username` in the plugin configuration, all routes will use the plugin metadata configuration in this way.
If you wish to use a global Casbin configuration, you can first specify `model` and `policy` attributes in the Plugin metadata and only the `username` attribute in the Plugin configuration. All Routes will use the Plugin configuration this way.

:::

## Metadata

| Name | Type | Requirement | Default | Valid | Description |
| ----------- | ------ | ----------- | ------- | ----- | ---------------------------------------------------------------------- |
| model | string | required | | | The Casbin model configuration in text format. |
| policy | string | required | | | The Casbin policy in text format. |
| Name | Type | Required | Description |
|--------|--------|----------|--------------------------------------------|
| model | string | True | Casbin model configuration in text format. |
| policy | string | True | Casbin policy in text format. |

## Enabling the Plugin

## How To Enable
You can enable the Plugin on a Route by either using the model/policy file paths or using the model/policy text in Plugin configuration/metadata.

You can enable the plugin on any route either by using the model/policy file paths or directly using the model/policy text.
### By using model/policy file paths

### By using file paths
The example below shows setting up Casbin authentication from your model/policy configuration file:

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -72,9 +84,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

This will create a Casbin enforcer from the model and policy files at your first request.
### By using model/policy text in Plugin configuration

### By using model/policy text
The example below shows setting up Casbin authentication from your model/policy text in your Plugin configuration:

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand Down Expand Up @@ -113,11 +125,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

This will create a Casbin enforcer from the model and policy text at your first request.
### By using model/policy text in Plugin metadata

### By using model/policy text using plugin metadata
First, you need to send a `PUT` request to the Admin API to add the `model` and `policy` text to the Plugin metadata.

First, send a `PUT` request to add the model and policy text to the plugin's metadata using the Admin API. All routes configured in this way will use a single Casbin enforcer with plugin metadata configuration. You can also update the model/policy this way, the plugin will automatically update itself with the updated configuration.
All Routes configured this way will use a single Casbin enforcer with the configured Plugin metadata. You can also update the model/policy in this way and the Plugin will automatically update to the new configuration.

```shell
curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/authz-casbin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
Expand All @@ -143,7 +155,7 @@ g, alice, admin"
}'
```

Then add this plugin on a route by sending the following request. Note, there is no requirement for model/policy now.
Once you have updated the Plugin metadata, you can add the Plugin to a specific Route:

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -163,11 +175,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

**NOTE**: The plugin route configuration has a higher precedence than the plugin metadata configuration. Hence if the model/policy configuration is present in the plugin route config, the plugin will use that instead of the metadata config.
:::note

## Test Plugin
The Plugin Route configuration has a higher precedence than the Plugin metadata configuration. If the model/policy configuration is present in the Plugin Route configuration, it is used instead of the metadata configuration.

We defined the example model as:
:::

## Example usage

We define the example model as:

```conf
[request_definition]
Expand All @@ -194,34 +210,35 @@ p, admin, *, *
g, alice, admin
```

This means that anyone can access the homepage (`/`) using `GET` request method while only users with admin permissions can access other pages and use other request methods.
See [examples](https://github.com/casbin/lua-casbin/tree/master/examples) for more policy and model configurations.

The above configuration will let anyone access the homepage (`/`) using a `GET` request while only users with admin permissions can access other pages and use other request methods.

For example, here anyone can access the homepage with the GET request method and the request proceeds normally:
So if we make a get request to the homepage:

```shell
curl -i http://127.0.0.1:9080/ -X GET
```

If some unauthorized user `bob` tries to access any other page, they will get a 403 error:
But if an unauthorized user tries to access any other page, they will get a 403 error:

```shell
curl -i http://127.0.0.1:9080/res -H 'user: bob' -X GET
HTTP/1.1 403 Forbidden
```

But someone with admin permissions like `alice`can access it:
And only users with admin privileges can access the endpoints:

```shell
curl -i http://127.0.0.1:9080/res -H 'user: alice' -X GET
```

## Disable Plugin

Remove the corresponding json configuration in the plugin configuration to disable the `authz-casbin` plugin.
APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
To disable the `authz-casbin` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/*",
Expand All @@ -234,7 +251,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}
}'
```

## Examples

Checkout examples for model and policy conguration [here](https://github.com/casbin/lua-casbin/tree/master/examples).
55 changes: 29 additions & 26 deletions docs/en/latest/plugins/authz-casdoor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: authz-casdoor
keywords:
- APISIX
- Plugin
- Authz Casdoor
- authz-casdoor
description: This document contains information about the Apache APISIX authz-casdoor Plugin.
---

<!--
Expand All @@ -23,24 +29,32 @@ title: authz-casdoor

## Description

`authz-casdoor` is an authorization plugin based on [Casdoor](https://casdoor.org/). Casdoor is a centralized authentication / Single-Sign-On (SSO) platform supporting OAuth 2.0, OIDC and SAML, integrated with Casbin RBAC and ABAC permission management.
The `authz-casdoor` Plugin can be used to add centralized authentication with [Casdoor](https://casdoor.org/).

## Attributes

| Name | Type | Requirement | Default | Valid | Description |
| ----------- | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
| endpoint_addr | string | required | | | The url of casdoor. |
| client_id | string | required | | | The client id in casdoor. |
| client_secret | string | required | | | The client secret in casdoor. |
| callback_url | string | required | | | The callback url which is used to receive state and code. |
| Name | Type | Required | Description |
|---------------|--------|----------|----------------------------------------------|
| endpoint_addr | string | True | URL of Casdoor. |
| client_id | string | True | Client ID in Casdoor. |
| client_secret | string | True | Client secret in Casdoor. |
| callback_url | string | True | Callback URL used to receive state and code. |

*Note: endpoint_addr and callback_url should not end with '/'*
:::info IMPORTANT

## How To Enable
`endpoint_addr` and `callback_url` should not end with '/'.

You can enable the plugin on any route by giving out all attributes mentioned above.
:::

### Example
:::info IMPORTANT

The `callback_url` must belong to the URI of your Route. See the code snippet below for an example configuration.

:::

## Enabling the Plugin

You can enable the Plugin on a specific Route as shown below:

```shell
curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
Expand All @@ -62,23 +76,12 @@ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f
}
}
}'

```

In this example, using apisix's admin API we created a route "/anything/*" pointed to "httpbin.org:80", and with "authz-casdoor" enabled. This route is now under authentication protection of Casdoor.

#### Explanations about parameters of this plugin

In the configuration of "authz-casdoor" plugin we can see four parameters.

The first one is "callback_url". This is exactly the callback url in OAuth2. It should be emphasized that this callback url **must belong to the "uri" you specified for the route**, for example, in this example, http://localhost:9080/anything/callback obviously belong to "/anything/*". Only by this way can the visit toward callback_url can be intercepted and utilized by the plugin(so that the plugin can get the code and state in Oauth2). The logic of callback_url is implemented completely by the plugin so that there is no need to modify the server to implement this callback.

The second parameter "endpoint_addr" is obviously the url of Casdoor. The third and fourth parameters are "client_id" and "client_secret", which you can acquire from Casdoor when you register an app.

#### How it works?
## Example usage

Suppose a new user who has never visited this route before is going to visit it (http://localhost:9080/anything/d?param1=foo&param2=bar), considering that "authz-casdoor" is enabled, this visit would be processed by "authz-casdoor" plugin first. After checking the session and confirming that this user hasn't been authenticated, the visit will be intercepted. With the original url user wants to visit kept, he will be redirected to the login page of Casdoor.
Once you have enabled the Plugin, a new user visiting this Route would first be processed by the `authz-casdoor` Plugin. They would be redirected to the login page of Casdoor.

After successfully logging in with username and password(or whatever method he uses), Casdoor will redirect this user to the "callback_url" with GET parameter "code" and "state" specified. Because the "callback_url" is known by the plugin, when the visit toward the "callback_url" is intercepted this time, the logic of "Authorization code Grant Flow" in Oauth2 will be triggered, which means this plugin will request the access token to confirm whether this user is really logged in. After this confirmation, this plugin will redirect this user to the original url user wants to visit, which was kept by us previously. The logged-in status will also be kept in the session.
After successfully logging in, Casdoor will redirect this user to the `callback_url` with GET parameters `code` and `state` specified. The Plugin will also request for an access token and confirm whether the user is really logged in. This process is only done once and subsequent requests are left uninterrupted.

Next time this user want to visit url behind this route (for example, http://localhost:9080/anything/d), after discovering that this user has been authenticated previously, this plugin won't redirect this user anymore so that this user can visit whatever he wants under this route without being interfered.
Once this is done, the user is redirected to the original URL they wanted to visit.
Loading