8000 add documentation fo HTTP Basic authentication ingress annotations su… · nginx/kubernetes-ingress@452190a · GitHub
[go: up one dir, main page]
Skip to content

Commit 452190a

Browse files
svvacsvvac
committed
add documentation fo HTTP Basic authentication ingress annotations support
1 parent f492d0f commit 452190a

File tree

2 files changed

+116
-0
lines changed

2 files changed

+116
-0
lines changed

‎docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ The following Ingress annotations currently have limited or no validation:
8787
- `nginx.org/proxy-hide-headers`,
8888
- `nginx.org/proxy-pass-headers`,
8989
- `nginx.org/rewrites`,
90+
- `nginx.org/basic-auth-secret`,
91+
- `nginx.org/basic-auth-realm`,
9092
- `nginx.com/jwt-key`,
9193
- `nginx.com/jwt-realm`,
9294
- `nginx.com/jwt-token`,
@@ -148,6 +150,8 @@ The table below summarizes the available annotations.
148150
|``nginx.org/hsts-max-age`` | ``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) | |
149151
|``nginx.org/hsts-include-subdomains`` | ``hsts-include-subdomains`` | Adds the ``includeSubDomains`` directive to the HSTS header. | ``False`` | |
150152
|``nginx.org/hsts-behind-proxy`` | ``hsts-behind-proxy`` | Enables HSTS based on the value of the ``http_x_forwarded_proto`` request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https`` annotation. | ``False`` | |
153+
|``nginx.org/basic-auth-secret`` | N/A | Specifies a Secret resource with a user list for HTTP Basic authentication. | N/A | |
154+
|``nginx.org/basic-auth-realm`` | N/A | Specifies a realm. | N/A | |
151155
|``nginx.com/jwt-key`` | N/A | Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). |
152156
|``nginx.com/jwt-realm`` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). |
153157
|``nginx.com/jwt-token`` | N/A | Specifies a variable that contains a JSON Web Token. | By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). |

‎examples/basic-auth/README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Support for HTTP Basic Authentication
2+
3+
NGINX supports authenticating requests with [ngx_http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html).
4+
5+
The Ingress controller provides the following 4 annotations for configuring JWT validation:
6+
7+
* Required: ```nginx.org/basic-auth-secret: "secret"``` -- specifies a Secret resource with a htpasswd user list. The htpasswd must be stored in the `htpasswd` data field. The type of the secret must be `nginx.org/htpasswd`.
8+
* Optional: ```nginx.org/basic-auth-realm: "realm"``` -- specifies a realm.
9+
10+
```
11+
12+
## Example 1: The Same Htpasswd for All Paths
13+
14+
In the following example we enable HTTP Basic authentication for the cafe-ingress Ingress for all paths using the same htpasswd `cafe-htpasswd`:
15+
```yaml
16+
apiVersion: networking.k8s.io/v1
17+
kind: Ingress
18+
metadata:
19+
name: cafe-ingress
20+
annotations:
21+
nginx.org/basic-auth-secret: "cafe-passwd"
22+
nginx.org/basic-auth-realm: "Cafe App"
23+
spec:
24+
tls:
25+
- hosts:
26+
- cafe.example.com
27+
secretName: cafe-secret
28+
rules:
29+
- host: cafe.example.com
30+
http:
31+
paths:
32+
- path: /tea
33+
backend:
34+
serviceName: tea-svc
35+
servicePort: 80
36+
- path: /coffee
37+
backend:
38+
serviceName: coffee-svc
39+
servicePort: 80
40+
```
41+
* The keys must be deployed separately in the Secret `cafe-jwk`.
42+
* The realm is `Cafe App`.
43+
44+
## Example 2: a Separate Htpasswd Per Path
45+
46+
In the following example we enable JWT validation for the [mergeable Ingresses](../mergeable-ingress-types) with a separate JWT key per path:
47+
48+
* Master:
49+
```yaml
50+
apiVersion: networking.k8s.io/v1
51+
kind: Ingress
52+
metadata:
53+
name: cafe-ingress-master
54+
annotations:
55+
kubernetes.io/ingress.class: "nginx"
56+
nginx.org/mergeable-ingress-type: "master"
57+
spec:
58+
tls:
59+
- hosts:
60+
- cafe.example.com
61+
secretName: cafe-secret
62+
rules:
63+
- host: cafe.example.com
64+
```
65+
66+
* Tea minion:
67+
```yaml
68+
apiVersion: networking.k8s.io/v1
69+
kind: Ingress
70+
metadata:
71+
name: cafe-ingress-tea-minion
72+
annotations:
73+
nginx.org/mergeable-ingress-type: "minion"
74+
nginx.org/basic-auth-secret: "tea-passwd"
75+
nginx.org/basic-auth-realm: "Tea"
76+
spec:
77+
rules:
78+
- host: cafe.example.com
79+
http:
80+
paths:
81+
- path: /tea
82+
pathType: Prefix
83+
backend:
84+
service:
85+
name: tea-svc
86+
port:
87+
number: 80
88+
```
89+
90+
* Coffee minion:
91+
```yaml
92+
apiVersion: networking.k8s.io/v1
93+
kind: Ingress
94+
metadata:
95+
name: cafe-ingress-coffee-minion
96+
annotations:
97+
nginx.org/mergeable-ingress-type: "minion"
98+
nginx.org/basic-auth-secret: "coffee-passwd"
99+
nginx.org/basic-auth-realm: "Coffee"
100+
spec:
101+
rules:
102+
- host: cafe.example.com
103+
http:
104+
paths:
105+
- path: /coffee
106+
pathType: Prefix
107+
backend:
108+
service:
109+
name: coffee-svc
110+
port:
111+
number: 80
112+
```

0 commit comments

Comments
 (0)
0