You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/04/20 05:19:24 UTC
[GitHub] [apisix-ingress-controller] navendu-pottekkat commented on a diff in pull request #972: Doc: add 'enable authentication and restriction' document
navendu-pottekkat commented on code in PR #972:
URL: https://github.com/apache/apisix-ingress-controller/pull/972#discussion_r853733195
##########
docs/en/latest/practices/enable-authentication-and-restriction.md:
##########
@@ -0,0 +1,362 @@
+---
+title: enable authentication and restriction
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Description
+
+Consumers are useful when you have different consumers requesting the same API and you need to execute different Plugin and Upstream configurations based on the consumer. These need to be used in conjunction with the user authentication system.
+
+## Attributes
+
+### Authentication
+
+| Name | Type | Requirement | Value | Description |
Review Comment:
Could you change the table structure similar to this?
https://github.com/apache/apisix/pull/6877/files
##########
docs/en/latest/practices/enable-authentication-and-restriction.md:
##########
@@ -0,0 +1,362 @@
+---
+title: enable authentication and restriction
Review Comment:
Use sentence case.
```suggestion
title: Enable authentication and restriction
```
##########
docs/en/latest/practices/enable-authentication-and-restriction.md:
##########
@@ -0,0 +1,362 @@
+---
+title: enable authentication and restriction
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Description
+
+Consumers are useful when you have different consumers requesting the same API and you need to execute different Plugin and Upstream configurations based on the consumer. These need to be used in conjunction with the user authentication system.
+
+## Attributes
+
+### Authentication
+
+| Name | Type | Requirement | Value | Description |
+|-----------|--------|-------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------|
+| keyAuth | object | required | `value:{ key: ${key} }` | Consumers add their key either in a header `apikey` to authenticate their requests. |
+| basicAuth | object | required | `value:{ username: ${username}, password: ${password}}` | Consumers add their key either in a header `Authentication` to authenticate their requests. |
+
+### Restriction
+
+|Name | Type | Requirement | Value | Description |
+|--------------------|---------------|-------------|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| whitelist | array[string] | required | `"${namespace}_${name}"` |Grant full access to all users specified in the provided list , **has the priority over `allowed_by_methods`** |
+| blacklist | array[string] | required | `"${namespace}_${name}"` | Reject connection to all users specified in the provided list , **has the priority over `whitelist`** |
+| allowed_by_methods | array[object] | optional | `{user: "${namespace}_${name}", methods:["GET", "POST"...]}`| HTTP methods can be `methods:["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"]` |
+
+* **consumer_name**: Add the `username` of `consumer` to a whitelist or blacklist (supporting single or multiple consumers) to restrict access to services or routes.
+
+## Example
+
+### Prepare env
+
+Kubernetes cluster:
+
+1. [apisix-ingress-controller](../deployments/minikube.md).
+2. httpbin.
+
+```shell
+#Now, try to deploy it to your Kubernetes cluster:
+kubectl run httpbin --image kennethreitz/httpbin --port 80
+kubectl expose pod httpbin --port 80
+```
+
+### How to enable `Authentication`
+
+The following is an example. The `keyAuth` is enabled on the specified route to restrict user access.
+
+Create ApisixConsumer foo:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: foo
+spec:
+ authParameter:
+ keyAuth:
+ value:
+ key: foo-key
+EOF
+```
+
+ApisixRoute:
+
+```shell
+kubectl apply -f -<<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixRoute
+metadata:
+ name: httpserver-route
+spec:
+ http:
+ - name: rule1
+ match:
+ hosts:
+ - local.httpbin.org
+ paths:
+ - /*
+ backends:
+ - serviceName: httpbin
+ servicePort: 80
+ authentication:
+ enable: true
+ type: keyAuth
+EOF
+```
+
+Requests from foo:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:foo-key' -v
+
+HTTP/1.1 200 OK
+...
+```
+
+### How to enable `Restriction`
+
+We can also use the `consumer-restriction` Plugin to restrict our user from accessing the API.
+
+The configure:
+
+> Use `whitelist` or `blacklist` restrict `consumer_name`
+>
+> ```yaml
+> config:
+> whitelist:
+> - "${namespace}_${name:1}"
+> "${namespace}_${name:...}"
+> ```
+>
+> Restrict `allowed_by_methods`
+>
+> ```yaml
+>config:
+> allowed_by_methods:
+> - user: "${namespace}_${name:1}"
+> methods:
+> - "$(method)["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE"]"
+> - user: "${namespace}_${name:...}"
+> methods:
+> - "$(method)["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE"]"
+> ```
+>
+
+#### How to restrict `consumer_name`
+
+The following is an example. The `consumer-restriction` plugin is enabled on the specified route to restrict consumer access.
+
+Create ApisixConsumer jack1:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: jack1
+spec:
+ authParameter:
+ keyAuth:
+ value:
+ key: jack1-key
+EOF
+```
+
+Create ApisixConsumer jack2:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: jack2
+spec:
+ authParameter:
+ keyAuth:
+ value:
+ key: jack2-key
+EOF
+```
+
+ApisixRoute:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixRoute
+metadata:
+ name: httpserver-route
+spec:
+ http:
+ - name: rule1
+ match:
+ hosts:
+ - local.httpbin.org
+ paths:
+ - /*
+ backends:
+ - serviceName: httpbin
+ servicePort: 80
+ authentication:
+ enable: true
+ type: keyAuth
+ plugins:
+ - name: consumer-restriction
+ enable: true
+ config:
+ whitelist:
+ - "default_jack1"
+EOF
+```
+
+How to get `default_jack1`:
+
+> view ApisixConsumer resource object from this namespace `default`
+>
+> ```shell
+> $ kubectl get apisixconsumers.apisix.apache.org -n default
+> NAME AGE
+> foo 14h
+> jack1 14h
+> jack2 14h
+> ```
+>
+> `${namespace}_${name}` --> `default_foo`
+> `${namespace}_${name}` --> `default_jack1`
+> `${namespace}_${name}` --> `default_jack2`
+
+**Test Plugin**
+
+Requests from jack1:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack1-key' -v
+
+HTTP/1.1 200 OK
+...
+```
+
+Requests from jack2:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack2-key'
+HTTP/1.1 403 Forbidden
+...
+{"message":"The consumer_name is forbidden."}
+```
+
+#### How to restrict `allowed_by_methods`
+
+This example restrict the user `jack2` to only `GET` on the resource.
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixRoute
+metadata:
+ name: httpserver-route
+spec:
+ http:
+ - name: rule1
+ match:
+ hosts:
+ - local.httpbin.org
+ paths:
+ - /*
+ backends:
+ - serviceName: httpbin
+ servicePort: 80
+ authentication:
+ enable: true
+ type: keyAuth
+ plugins:
+ - name: consumer-restriction
+ enable: true
+ config:
+ allowed_by_methods:
+ - user: "default_jack1"
+ methods:
+ - "POST"
+ - "GET"
+ - user: "default_jack2"
+ methods:
+ - "GET"
+EOF
+```
+
+**Test Plugin**
+
+Requests from jack1:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack1-key' -v
+
+HTTP/1.1 200 OK
+...
+```
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack1-key' -d '' -v
+
+HTTP/1.1 200 OK
+...
+```
+
+Requests from jack2:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack2-key' -v
+
+HTTP/1.1 200 OK
+...
+```
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack2-key' -d '' -v
+
+HTTP/1.1 403 Forbidden
+...
+```
+
+### Disable Plugin
+
+When you want to disable the `consumer-restriction` plugin, it is very simple,
Review Comment:
Could you change this line to the disable plugin line in this PR? https://github.com/apache/apisix/pull/6877/files
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org