Skip to content

Commit 710420e

Browse files
sreejithgssreejithgs
authored
Merge pull request #381 from citrix/doc-update-1.14
updates for 1.13.20 release
2 parents a4b8fb5 + 873843d commit 710420e

3 files changed

Lines changed: 258 additions & 47 deletions

File tree

‎crd/auth/README.md‎

Lines changed: 126 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -95,24 +95,33 @@ spec:
9595
required: [tls_secret]
9696
- properties:
9797
required: [preconfigured]
98-
vip:
98+
ingress_name:
9999
description: |+
100-
'Frontend IP of ingress for which the authentication
101-
using forms is applicable. This refers to frontend-ip provided
102-
with Ingress'
100+
'Ingress name for which the authentication using forms
101+
is applicable.'
103102
type: string
103+
maxLength: 63
104104
lb_service_name:
105105
description: |+
106106
'Service of type LoadBalancer for which the authentication using forms
107107
is applicable.'
108108
type: string
109109
maxLength: 63
110+
vip:
111+
description: |+
112+
'Frontend IP of ingress for which the authentication
113+
using forms is applicable. This refers to frontend-ip provided
114+
with Ingress. It is suggested to use vip, if more than one Ingress
115+
resource use the same frontend-ip'
116+
type: string
110117
required: [authentication_host, authentication_host_cert]
111118
oneOf:
112119
- properties:
113-
required: [vip]
120+
required: [ingress_name]
114121
- properties:
115122
required: [lb_service_name]
123+
- properties:
124+
required: [vip]
116125
oneOf:
117126
- properties:
118127
using_request_header:
@@ -149,6 +158,22 @@ spec:
149158
items:
150159
type: string
151160
maxLength: 127
161+
jwks_uri:
162+
description: |+
163+
'URL of the endpoint that contains JWKs (Json Web Key) for
164+
JWT (Json Web Token) verification'
165+
type: string
166+
maxLength: 127
167+
introspect_url:
168+
description: ' URL of the introspection server'
169+
type: string
170+
maxLength: 127
171+
client_credentials:
172+
description: |+
173+
'secrets object that contains Client Id and secret as known
174+
to Introspection server'
175+
type: string
176+
maxLength: 253
152177
token_in_hdr:
153178
description: |+
154179
'custom header name where token is present,
@@ -177,27 +202,46 @@ spec:
177202
items:
178203
type: string
179204
maxLength: 127
180-
jwks_uri:
205+
metadata_url:
206+
description: 'URL used to get OAUTH/OIDC provider metadata'
207+
type: string
208+
maxLength: 255
209+
user_field:
181210
description: |+
182-
'URL of the endpoint that contains JWKs (Json Web Key) for
183-
JWT (Json Web Token) verification'
211+
'Attribute in the token from which username should be extracted.
212+
by default, ADC looks at email attribute for user id'
184213
type: string
185214
maxLength: 127
186-
introspect_url:
187-
description: ' URL of the introspection server'
215+
default_group:
216+
description: |+
217+
'group assigned to the request if authentication succeeds,
218+
this is in addition to any extracted groups from token'
188219
type: string
189-
maxLength: 127
190-
client_credentials:
220+
maxLength: 63
221+
grant_type:
222+
description: 'used to specify the type of flow to the token end point, defaults to CODE'
223+
type: array
224+
items:
225+
type: string
226+
enum: ['CODE','PASSWORD']
227+
pkce:
228+
description: 'specify whether to enable Proof Key Code Exchange, defaults to ENABLED'
229+
type: string
230+
enum: ['ENABLED', 'DISABLED']
231+
token_ep_auth_method:
191232
description: |+
192-
'secrets object that contains Client Id and secret as known
193-
to Introspection server'
233+
'authentication method to be used with token end point,
234+
defaults to client_secret_post'
194235
type: string
195-
maxLength: 253
236+
enum: ['client_secret_post', 'client_secret_jwt']
237+
196238
anyOf:
197239
- properties:
198240
required : [jwks_uri]
199241
- properties:
200242
required : [introspect_url, client_credentials]
243+
- properties:
244+
required : [metadata_url]
201245

202246
ldap:
203247
description: 'LDAP authentication provider'
@@ -465,7 +509,6 @@ spec:
465509

466510
required:
467511
- servicenames
468-
469512
```
470513
471514
## Auth CRD attributes
@@ -500,8 +543,9 @@ The following are the attributes for forms based authentication.
500543
| --------- | ----------- |
501544
| `authentication_host` | Specifies a fully qualified domain name (FQDN) to which the user must be redirected for authentication. This FQDN should be unique and should resolve to the front-end IP address of Citrix ADC with Ingress or service type LoadBalancer.|
502545
| `authentication_host_cert` | Specifies the name of the SSL certificate to be used with the `authentication_host`. This certificate is mandatory while performing authentication using the form.|
503-
| `vip` | Specifies the front-end IP address of the ingress for which the authentication using forms is applicable. This attribute refers to the `frontend-ip` provided with the Ingress.|
546+
|`ingress_name`| Specifies the Ingress name for which the authentication using forms is applicable.|
504547
| `lb_service_name`| Specifies the name of the service of type LoadBalancer for which the authentication using forms is applicable.|
548+
| `vip` |Specifies the front-end IP address of the Ingress for which the authentication using forms is applicable. This attribute refers to the `frontend-ip` address provided with the Ingress. If there is more than one Ingress resource which uses the same frontend-ip, it is recommended to use vip.|
505549

506550
**Note:** While using forms, authentication can be enabled for all types of traffic. Currently, granular authentication is not supported.
507551

@@ -531,6 +575,18 @@ The following are the attributes for OAuth authentication:
531575
|`signature_algorithms`| Specifies the list of signature algorithms which are allowed. By default HS256, RS256, and RS512 algorithms are allowed.|
532576
| `introspect_url`| The URL of the introspection endpoint of the authentication server (IdP). If the access token presented is an opaque token, introspection is used for the token verification.|
533577
| `client_credentials`| The name of the Kubernetes secrets object that contains the client id and client secret required to authenticate with the authentication server.|
578+
| `claims_to_save`| The list of claims to be saved. Claims are used to create authorization policies.|
579+
580+
OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. OIDC allows clients to verify the identity of the end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user. In addition to the OAuth attributes, you can use the following attributes to configure OIDC.
581+
582+
| Attribute | Description |
583+
| --------- | ----------- |
584+
| `metadata_url` | Specifies the URL that is used to get OAUTH or OIDC provider metadata.|
585+
| `user_field` | Specifies the attribute in the token from which the user name should be extracted. By default, Citrix ADC examines the email attribute for user ID.|
586+
| `default_group` | Specifies the group assigned to the request if authentication succeeds. This group is in addition to any extracted groups from the token. |
587+
| `grant_type` | Specifies the type of flow to the token end point. The default value is `CODE`.|
588+
| `pkce` | Specifies whether to enable Proof Key for Code Exchange (PKCE). The default value is `ENABLED`.|
589+
| `token_ep_auth_method` | Specifies the authentication method to be used with the token end point. The default value is `client_secret_post`.|
534590

535591
#### SAML authentication
536592

@@ -573,7 +629,7 @@ The following are the attributes for LDAP authentication.
573629
| `security_type` | Specifies the type of security used for communications between the Citrix ADC and the LDAP server. The default is TLS.|
574630
| `validate_server_cert` | Validates LDAP server certificates. The default value is `NO`.|
575631
|`hostname`|Specifies the host name for the LDAP server. If `validate_server_cert` is `ON`, this value must be the host name on the certificate from the LDAP. A host name mismatch causes a connection failure.|
576-
|`sub_attribute_name`| Specifies the LDAP group sub-attribute name. This attribute is used for group extraction from the LDAP server.|
632+
|`sub_attribute_name`| Specifies the LDAP group subattribute name. This attribute is used for group extraction from the LDAP server.|
577633
|`group_attribute_name`| Specifies the LDAP group attribute name. This attribute is used for group extraction on the LDAP server.|
578634
|`search_filter`| Specifies the string to be combined with the default LDAP user search string to form the search value. For example, if the search filter "vpnallowed=true" is combined with the LDAP login name "samaccount" and the user-supplied user name is "bob", the result is the LDAP search string ""(&(vpnallowed=true)(samaccount=bob)"". Enclose the search string in two sets of double quotation marks.|
579635
|`auth_timeout`| Specifies the number of seconds the Citrix ADC waits for a response from the server. The default value is 3.|
@@ -622,7 +678,7 @@ Perform the following to deploy the Auth CRD:
622678

623679
## How to write the authentication policies
624680

625-
After you have deployed the CRD provided by Citrix in the Kubernetes cluster, you can define the authentication policy configuration in a `.yaml` file. In the `.yaml` file, use `authpolicy` in the `kind` field and in the `spec` section add the Auth CRD attributes based on your requirement for the policy configuration.
681+
After you have deployed the CRD provided by Citrix in the Kubernetes cluster, you can define the authentication policy configuration in a `.yaml` file. In the `.yaml` file, use `authpolicy` in the `kind` field and in the `spec` section add the **Auth CRD** attributes based on your requirement for the policy configuration.
626682

627683
After you deploy the `.yaml` file, the Citrix ingress controller applies the authentication policy configuration on the Ingress Citrix ADC device.
628684

@@ -725,15 +781,15 @@ The sample authentication policy performs the following:
725781

726782
- The Citrix ADC does not perform the authentication for the **products** and **GET** endpoints.
727783

728-
- The Citrix ADC performs the oAuth JWT verification as specified in the provider `jwt-auth-provider` for the requests to the **reviews** endpoint.
784+
- The Citrix ADC performs the OAuth JWT verification as specified in the provider `jwt-auth-provider` for the requests to the **reviews** endpoint.
729785

730-
- The Citrix ADC performs the oAuth introspection as specified in the provider `introspect-provider` for the requests to the **customers** endpoint.
786+
- The Citrix ADC performs the OAuth introspection as specified in the provider `introspect-provider` for the requests to the **customers** endpoint.
731787

732788
- The Citrix ADC requires the `scope` claim with `read` and `write` permissions to access the **customers** endpoint and **POST**.
733789

734790
- The Citrix ADC does not need any authorization permissions to access the **products** endpoint with GET operation.
735791

736-
For oAuth, if the token is present in a custom header, it can be specified using the `token_in_hdr` attribute as follows:
792+
For OAuth, if the token is present in a custom header, it can be specified using the `token_in_hdr` attribute as follows:
737793

738794

739795
oauth:
@@ -752,7 +808,7 @@ Similarly, if the token is present in a query parameter, it can be specified usi
752808

753809
### Creating a secrets object with client credentials for introspection
754810

755-
A Kubernetes secrets object is needed for configuring the oAuth introspection.
811+
A Kubernetes secrets object is needed for configuring the OAuth introspection.
756812
You can create a secret object in a similar way as shown in the following example:
757813

758814

@@ -818,6 +874,53 @@ spec:
818874
819875
```
820876

877+
### OpenID Connect authentication using forms
878+
879+
The following is an example for creating OpenID Connect authentication to configure Citrix ADC in a Relaying Party (RP) role to authenticate users for an external identity provider. The `authentication_mechanism` must be set to `using_forms` to trigger the OpenID Connect procedures.
880+
881+
```yml
882+
apiVersion: citrix.com/v1beta1
883+
kind: authpolicy
884+
metadata:
885+
name: authoidc
886+
spec:
887+
servicenames:
888+
- frontend
889+
authentication_mechanism:
890+
using_forms:
891+
authentication_host: "10.221.35.213"
892+
authentication_host_cert:
893+
tls_secret: "oidc-tls-secret"
894+
vip: "10.221.35.213"
895+
896+
authentication_providers:
897+
898+
- name: "oidc-provider"
899+
oauth:
900+
audience : ["https://app1.citrix.com"]
901+
client_credentials: "oidcsecret"
902+
metadata_url: "https://10.221.35.214/oauth/idp/.well-known/openid-configuration"
903+
default_group: "groupA"
904+
user_field: "sub"
905+
pkce: "ENABLED"
906+
token_ep_auth_method: "client_secret_post"
907+
908+
authentication_policies:
909+
910+
- resource:
911+
path: []
912+
method: []
913+
provider: ["oidc-provider"]
914+
915+
authorization_policies:
916+
917+
#default - no authorization requirements
918+
- resource:
919+
path: []
920+
method: []
921+
claims: []
922+
```
923+
821924
### LDAP authentication using the request header
822925

823926
The following is an example for LDAP authentication using the request header.

0 commit comments

Comments
 (0)