API authentication with the Citrix ADC appliance
There is a paradigm shift in the way modern applications interact with their clients. Traditionally, browser clients were used to access services. Applications usually set session cookies to track user context. Modern and distributed applications make it hard to maintain user sessions across microservices. Due to this, most of the application accesses have become API based. Clients that communicate with these distributed services have also evolved. Most clients obtain tokens from a trusted entity called Authorization Server to prove user identity and access. These clients then present the token to the application with each access request. Therefore, traditional proxy devices like Citrix ADC need to evolve to support these clients. A Citrix ADC appliance provides a way for administrators to handle such traffic. Citrix ADC can be deployed as an API Gateway to front-end all the traffic that destined to the published services. An API Gateway can be deployed for traditional (Hybrid Multi Cloud or HMC) or Cloud native environments. The API Gateway terminates all the inbound traffic to offer several services such as authentication, authorization, rate limiting, routing, caching, SSL offload, application firewall, and so on. Therefore, it becomes a critical component in the infrastructure.
Token types
Tokens exchanged during the API access mostly conform to the OAuth/OpenID Connect (OIDC) protocol. Access tokens that are used only for ‘delegated access’ conform to the OAuth protocol, whereas ID Tokens that comply with OIDC carry user information as well. Access tokens are normally an opaque or random blob of data. However, they can sometimes be singed tokens conforming to JWT (Json Web Token) standards. ID Tokens are always signed JWTs.
API Access with OAuth
OAuth authentication type on a Citrix ADC appliance can be used to handle both OAuth and OIDC protocols. OIDC is an extension to the OAuth protocol.
OAuthAction on a Citrix ADC appliance can be used to handle interactive clients such as browsers and native clients such as client apps. Interactive clients are redirected to Identity Provider for login using the OIDC protocol. Native clients can obtain tokens out of band and can present those tokens at a Citrix ADC appliance for access.
Note:
The access token obtained from endpoints can be cached for subsequent requests, thereby enhancing the API performance.
To configure token caching support by using the command line interface, type the following command at the command prompt:
set aaaparameter –apITokenCache <ENABLED>
The following sections describe the API access method performed by native clients.
Virtual server for API Access
To deploy a Citrix ADC appliance for an API access, a Traffic Management (TM) virtual server is deployed with 401 Authentication. It is associated with an authentication (authentication, authorization, and auditing) virtual server to hold the authentication and session policies. Following configuration snippet creates one such virtual server.
Add lb vserver lb-api-access SSL <IP> 443 -authn401 On -AuthnVsName auth-api-access
Bind ssl vserver lb-api-access -certkeyName <ssl-cert-entity>
Add authentication vserver auth-api-access SSL
Note:
You would need to bind a service to the TM vserver, and an authentication policy (with OAuthAction described as follows) to the authentication virtual server to complete the configuration.
After creating the virtual server, one needs to add an OAuthAction along with corresponding policy. There are several other options within an OAuth action depending on the token type, and other security mechanisms.
OAuth Configuration for ID Tokens
ID Tokens are always signed JWTs. That is, they carry header, payload and signature. Since these are self-contained tokens, a Citrix ADC appliance can validate these tokens locally. To validate these tokens, the appliance would need to know the public key of the corresponding private key used to sign these tokens.
Following is an example of OAuthAction with certain mandatory arguments along with “certEndpoint”.
Add authentication OAuthAction oauth-api-access -clientid <your-client-id> -clientsecret <your-client-secret> -authorizationEndpoint <URL to which users would be redirected for login> -tokenEndpoint <endpoint at which tokens could be obtained> -certEndpoint <uri at which public keys of IdP are published>
Where,
-
Client ID – Unique string that identifies SP. Authorization server infers client configuration using this ID. Maximum Length: 127.
-
Client Secret – Secret string established by user and authorization server. Maximum Length: 239.
-
authorizationEndpoint - URL at which users would normally log in (when using interactive clients).
-
tokenEndpoint - URL on Authorization Server at which tokens/code are obtained/exchanged
-
certEndpoint - URL at which Authorization Server publishes public keys used to sign the tokens. Authorization Server can publish more than one key and choose one of them to sign tokens.
Note: Client ID/Client Secret/authorizationEndpoint/TokenEndpoint are optional parameters for API Access. However, it is a good practice to provide values for these parameters as the action entity can be reused for different purposes.
In the preceding configuration ‘certEndpointpoint’ is essential for ID Token validation. This endpoint contains public keys of the certificate used to sign the tokens. These public keys must correspond to JWKs (Json Web Keys) specification.
Once the certEndpoint is configured at the Citrix ADC appliance, it polls the endpoint periodically (with the default interval of 1 day that can be customizable in the configuration) to keep the public keys up to date. After the public keys are available, ADC can perform local validation of the incoming ID Tokens.
OAuth Configuration for opaque access tokens
Opaque tokens cannot be verified locally on the Citrix ADC appliance. These need to be validated on the Authorization server. A Citrix ADC appliance uses ‘introspection protocol’ mentioned in OAuth specifications in order to verify these tokens. A new option, introspectURL, is provided in OAuth configuration for verifying opaque tokens.
set oauthAction oauth-api-acccess -introspectURL <uri of the Authorization Server for introspection>
The format of the introspection API conforms to the specification at https://tools.ietf.org/html/rfc7662#section-2.1 as follows:
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
Binding policy to Authentication vserver
Once OAuthAction is created, corresponding policy needs to be created for invoking it.
add authentication policy oauth-api-access -rule <> -action <oauth-api-access>```
bind authentication vserver auth-api-access -policy oauth-api-access -pri 100
Additional security settings on a Citrix ADC appliance
Token validation includes token lifetime checks. Tokens outside of acceptable time are rejected. Following are the additional settings for extra security. Some of these are recommended to be configured always.
Audience: OAuth Action can be configured with an intended recipient of the token. All tokens are matched against this configured URL. A Citrix ADC appliance has an additional capability where the audience field actually points to a pattern set on the appliance. Using this pattern set, an administrator can configure more than one url for the audience.
add policy patset oauth_audiences
bind patset oauth_audiences https://app1.company.com
bind patset oauth_audiences https://app2.company.com
bind patset oauth_audiences httpsL//app1.company.com/path1
set oAuthAccess oauth-api-access -audience oauth_audiences
In the preceding example, more than one audience is specified in a pattern set. Therefore, an incoming token is allowed only if it contains any of the configured URLs in the pattern set.
Issuer: Identity of the server whose tokens are to be accepted. Maximum Length: 127. It is a good practice to configure the issuer of the tokens in OAuth action. This ensures that tokens issued by wrong Authorization Server are not allowed.
SkewTime: Specifies the allowed clock skew in number of minutes that a Citrix ADC appliance allows on an incoming token. For example, if skewTime is 10, then the token would be valid from (current time - 10) min to (current time + 10) min, that is 20 min in all. Default value: 5
AllowedAlgorithms: This option allows administrator to restrict certain algorithms in the incoming tokens. By default, all the supported methods are allowed. However, these can be controlled using this option.
The following configuration ensures only tokens that use RS256 and RS512 are allowed:
set oAuthAction oauth-api-access -allowedAlgorithms RS256 RS512
After above configuration, only tokens that use RS256 and RS512 are allowed.
Bypassing certain traffic from authentication
In many instances, there are some discovery APIs that are publicly accessible to the clients. These APIs typically reveal configuration and capabilities of the service itself. AN administrator can configure the Citrix ADC appliance to bypass authentication from these metadata URLs using ‘No Authentication’ policy described as follows:
add authentication policy auth-bypass-policy -rule <> -action NO_AUTHN
bind authentication vserver auth-api-access -policy auth-bypass-policy -pri 110
NO_AUTHN is an implicit action that results in authentication to be completed when the rule matches. There are other uses of NO_AUTHN action beyond the scope of API access.