ADC

API authentication with the NetScaler appliance

September 27, 2025

Contributed by:

C H

There is a paradigm shift in the way modern applications interact with their clients. Traditionally, browser clients were used to access services. Applications 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 NetScaler need to evolve to support these clients. A NetScaler appliance provides a way for administrators to handle such traffic. NetScaler 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 comply with the OAuth or OpenID Connect (OIDC) protocol. Access tokens that are used only for “delegated access” comply with the OAuth protocol, whereas ID Tokens that comply with OIDC carry the user information as well.

Access tokens are normally an opaque or random blob of data. However, they can sometimes be signed tokens that comply with JSON Web Token (JWT) standards. ID Tokens are always signed JWTs.

API Access with OAuth

OAuth authentication type on a NetScaler appliance can be used to handle both OAuth and OIDC protocols. OIDC is an extension to the OAuth protocol.

OAuthAction on a NetScaler appliance can be used to handle interactive clients such as browsers and native clients such as client apps. Interactive clients are redirected to the identity provider for login using the OIDC protocol. Native clients can obtain tokens out of band and can present those tokens at a NetScaler 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>
  <!--NeedCopy-->

The following sections describe the API access method performed by native clients.

Virtual server for API Access

To deploy a NetScaler 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
  <!--NeedCopy-->

Note:

You would need to bind a service to the traffic management virtual server, 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 NetScaler 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 <URL at which public keys of IdP are published>
  <!--NeedCopy-->

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 NetScaler 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 NetScaler appliance. These need to be validated on the Authorization server. A NetScaler appliance uses ‘introspection protocol’ mentioned in the OAuth specifications to verify these tokens. A new option, introspectURL, is provided in the OAuth configuration for verifying opaque tokens.

  set oauthAction oauth-api-acccess -introspectURL <URL of the Authorization Server for introspection>
  <!--NeedCopy-->

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
  <!--NeedCopy-->

Binding policy to Authentication virtual server

Once OAuthAction is created, a 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
  <!--NeedCopy-->

Additional security settings on a NetScaler 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 NetScaler 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 oAuthAction oauth-api-access -audience oauth_audiences
  <!--NeedCopy-->

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 the wrong authorization server are not allowed.

SkewTime: Specifies the allowed clock skew in number of minutes that a NetScaler 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
  <!--NeedCopy-->

After the preceding configuration is performed, 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 NetScaler 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
  <!--NeedCopy-->

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.

The official version of this product documentation is in English. Any non-English version is solely provided for your convenience and may include machine-translated content. For more information, please refer to the Machine Translation Disclaimer on Cloud Software Group home.

Was this helpful

NetScaler Secure Deployment Guide

API authentication with the NetScaler appliance

September 27, 2025

Contributed by:

C H

September 27, 2025

Contributed by:

C H

API authentication with the NetScaler appliance

Token types

API Access with OAuth

Virtual server for API Access

OAuth Configuration for ID Tokens

OAuth Configuration for opaque access tokens

Binding policy to Authentication virtual server

Additional security settings on a NetScaler appliance

Bypassing certain traffic from authentication

In this article