NetScaler as an OAuth SP
The authentication, authorization, and auditing traffic management feature supports OAuth authentication for authenticating users to applications that are hosted on applications such as Google, Facebook, and Twitter.
Points to note
- NetScaler Advanced Edition and higher is required for the solution to work.
- OAuth on NetScaler is qualified for all SAML IdPs that are compliant with “OpenID connect 2.0”.
Important:
NetScaler might respond with a CSRF error when a content-heavy website sends multiple authentication requests on session expiry. As a workaround, it is recommended that when you configure the OAuth policy, ensure that the policy is configured for both the host name and the path which are the main entry points.
Configure OAuth by using the GUI
-
Configure the OAuth action.
-
Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > Actions > OAUTH Actions and click Add.
-
On the Create Authentication OAuth Server page, set the following parameter values and click Create:
- Name: Name for the OAuth Authentication action.
- OAuth Implementation Type: Type of the OAuth implementation. Default value is Generic.
- Client ID: Unique identity of the client/user being authenticated.
- Client Secret: Secret string established by the user and authorization server. MaxLength = 239.
- Authentication: If the authentication is disabled, password is not sent in the request.
- Authorization Endpoint: Authorization endpoint/URL to which the unauthenticated user is redirected. NetScaler redirects the user to this endpoint by adding query parameters including the client ID. If this parameter is not specified then as the default value, NetScaler considers the token Endpoint/URL value.
- Token Endpoint: URL to which the OAuth token is sent to verify its authenticity. Upon successful authentication, the user obtains this token from the authorization server. NetScaler validates the presented token by posting it to the configured URL. Maximum Length: 511. Note: Authorization endpoint or token endpoint are mandatory parameters for OAuth action. Maximum Length: 511.
- ID Token Decrypt Endpoint: URL to which obtained idtoken will be posted to get a decrypted user identity. Encrypted idtoken will be obtained by posting OAuth token to token endpoint. In order to decrypt idtoken, NetScaler posts request to the URL configured Maximum Length: 511. Graph Endpoint: URL of the Graph API service to learn Enterprise Mobility Services (EMS) endpoints. MaxLength = 255
- Cert Endpoint: URL of the endpoint that contains JWKs (Json Web Key) for JWT (Json Web Token) verification. MaxLength = 127
- Audience: Audience for which token sent by Authorization server is applicable. This is typically entity name or url that represents the recipient. MaxLength = 127
- User Name Field: Attribute in the token from which username should be extracted. MaxLength = 127
- User Info URL: URL to which OAuth access token will be posted to obtain user information. MaxLength = 127
- Introspect URL: URL to which access token would be posted for validation. MaxLength = 127
- Skew Time (mins): This option specifies the allowed clock skew in number of minutes that NetScaler allows on an incoming token. For example, if skewTime is 10, then token would be valid from (current time - 10) min to (current time + 10) min, ie 20min in all. MaxLength = 127
- Issuer: Identity of the server whose tokens are to be accepted. MaxLength = 127.
- Certificate File Path: Path to the file that contains JWKs (Json Web Key) for JWT (Json Web Token) verification.
- Refresh Interval: Interval at which services are monitored for necessary configuration. Default = 1440
- Default Authentication Group: This is the default group that is chosen when the authentication succeeds in addition to extracted groups.
- Grant Type: Grant type support. value can be code or password
- Attributes: List of attribute names separated by ‘,’ which needs to be extracted.
- Resource URL: Resource URL for Oauth configuration.
- OAuth Misc Flags
- Base64Encode Authorization With Padding: When sending authorization requests to the token and introspect endpoints, this parameter ensures that the authorization header is Base64 encoded, with padding.
- Enable JWT Request: Enables the JWT-request parameter to be included in the authorization requests sent to the IdP.
- Request Attribute: Indicates the Name-Value pairs of attributes to be inserted in the request parameter.
-
-
Configure the OAuth Policy.
Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > Policy, and create a policy with OAuth as the action type, and associate the required OAuth action with the policy.
-
Associate the OAuth policy with an authentication virtual server.
Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the OAuth policy with the authentication virtual server.
Note:
Attributes (1 to 16) can be extracted in the OAuth response. Currently these attributes are not evaluated. They are added for the future reference.
Configure OAuth by using the CLI
-
Define an OAuth action.
add authentication OAuthAction <name> [-OAuthType <OAuthType>] [-authorizationEndpoint <URL>] [-tokenEndpoint <URL>] [-idtokenDecryptEndpoint <URL>] [-clientID <string>][-clientSecret ] [-defaultAuthenticationGroup <string>][-OAuthMiscFlags (Base64Encode_Authorization_With_Padding | EnableJWTRequest)][-Attribute1 <string>] [-Attribute2 <string>] [-Attribute3 <string>] [-Attributes <string>] [-tenantID <string>] [-GraphEndpoint <string>] [-refreshInterval <positive_integer>] [-CertEndpoint <string>][-audience <string>] [-userNameField <string>] [-skewTime <mins>] [-issuer <string>] [-UserInfoURL <URL>] [-CertFilePath <string>] [-grantType ( CODE | PASSWORD )] [-authentication ( ENABLED | DISABLED )] [-introspectURL <URL>][-allowedAlgorithms <allowedAlgorithms> ...] [-PKCE ( ENABLED | DISABLED )] [-tokenEndpointAuthMethod <tokenEndpointAuthMethod>] [-metadataUrl <URL>] [-resourceUri <URL>] <!--NeedCopy--> -
Associate the action with an advanced authentication policy.
add authentication Policy <name> -rule <expression> -action <string> <!--NeedCopy-->Example:
add authentication oauthAction a -authorizationEndpoint https://example.com/ -tokenEndpoint https://example.com/ -clientiD sadf -clientsecret df <!--NeedCopy-->
For more information on authentication OAuthAction parameters, see authentication OAuthAction.
Note:
- When a certEndpoint is specified, NetScaler polls that endpoint at the configured frequency to learn the keys.
To configure a NetScaler to read the local file and parse keys from that file, a new configuration option is introduced as follows:
set authentication OAuthAction <name> -CertFilePath <path to local file with jwks>
<!--NeedCopy-->
OAuth feature now supports the following capabilities in the token API from the Relying Party (RP) side and from the IdP side of NetScaler Gateway and NetScaler.
-
PKCE (Proof Key for Code Exchange) support
-
Support for client_assertion
Name-value attribute support for OAuth authentication
You can now configure OAuth authentication attributes with a unique name along with the values. The names are configured in the OAuth action parameter either as “Attributes” and the values are obtained by querying for the names. The extracted attributes are stored in the authentication, authorization, and auditing session. Admins can query these attributes either using http.req.user.attribute("attribute name") or http.req.user.attribute(1), based on the chosen method of specifying attribute names.
By specifying the name of the attribute, admins can easily search for the attribute value associated with that attribute name. Also, admins no longer have to remember the “attribute1 to attribute16” by its number alone.
Important
In an OAuth command, you can configure a maximum of 64 attributes separated by comma with a total size less than 1024 bytes.
Note
The session failure can be avoided if the total value size of “attribute 1 to attribute 16” and the values of attributes specified in “Attributes” are not more than 10 KB.
To configure the name-value attributes by using the CLI
At the command prompt, type:
add authentication OAuthAction <name> [-Attributes <string>]
set authentication OAuthAction <name> [-Attributes <string>]
<!--NeedCopy-->
Examples:
add authentication OAuthAction a1 –attributes "email,company" –attribute1 email
set authentication OAuthAction oAuthAct1 -attributes "mail,sn,userprincipalName"
<!--NeedCopy-->