NetScaler as an OAuth IdP
NetScaler can now be configured as an identity provider by using the OpenID-Connect (OIDC) protocol. OIDC protocol strengthens the identity providing capabilities of NetScaler. You can now access the enterprise wide-hosted application with a single sign-on as OIDC offers more security by not transferring the user password but using tokens with specific lifetime. OpenID is also designed to integrate with non-browser clients such as apps and services. Therefore, the OIDC protocol is widely adopted by many implementations.
Note
NetScaler must be on version 12.1 or later to work as an OAuth IdP using the OIDC protocol.
Advantages of having NetScaler as an OAuth IdP
- Eliminates the overhead of maintaining multiple authentication passwords as the user has a single identity across an organization.
- Provides a robust security for your password as the password is shared only with your identity provider and not with any application you access.
- Provides vast interoperability with various systems, making it easier for the hosted applications to accept OpenID.
Note
NetScaler Advanced Edition and higher is required for the solution to work.
To configure NetScaler as an OAuth IdP using the GUI
-
Create an authentication OAuth IdP policy.
- Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > OAuth IDP > Policies.
- Under Policies, click Add.
-
On the Create Authentication OAuth IDP Policy page, set values for the following parameters and click Create.
- Name: The name of the authentication policy.
- Action: Name of authentication OAuth IdP profile to apply to requests or connections that match this policy. See step 2 for detailed steps.
- Log Action: Name of the message log action to use when a request matches this policy. See step 3 for detailed steps. This field is optional.
- Undefined-Result Action: Action to perform if the result of the policy evaluation is undefined. An undefined event indicates an internal error condition. Available actions are DROP and RESET. This field is optional.
- Expression: Advanced expression that the policy uses to respond to specific requests. For more information about policies and expressions, see Policies and expressions.
-
Create an authentication OAuth IdP action.
- On the Create Authentication OAuth IDP Policy page, click Add in the Action field.
-
On the Create Authentication OAuth IDP Profile page that appears, set values for the following parameters and click Create.
- Name: Name for the new OAuth IdP single sign-on profile.
- Client ID: Unique identity of the relying party requesting for authentication. Maximum allowed length is 127 characters.
- Client Secret: Unique secret string to authorize the relying party at the authorization server. Maximum allowed length is 239 characters.
- Redirect URL: The relying party URL endpoint to which the OAuth token needs to be sent. Maximum allowed length is 255 characters.
- Issuer Name: The name to be used in requests sent from NetScaler to the IdP to uniquely identify NetScaler. Maximum allowed length is 127 characters.
- Audience: Target recipient for the token being sent by the IdP. This is the entity name or the URL that represents the recipient. Maximum allowed length is 127 characters.
- Skew Time: This option specifies the duration for which the token sent by the NetScaler IdP is valid. For example, if the skew time is set to 10 minutes, then the token would be valid from (current time minus 10) minutes to (current time plus 10) minutes; 20 minutes in total. Default duration is 5 minutes.
- Default Authentication Group: Group added to the session’s internal group list. This is useful for admins to determine the configuration for the relying party in an nFactor flow. It can be used in the expression
AAA.USER.IS_MEMBER_OF("group name")for authentication policies to identify the relying party-related nFactor flow. Maximum allowed length is 63 characters. - Relying Party metadata URL: Endpoint where the NetScaler IdP can get details about the relying party being configured. Metadata response must include endpoints for
jwks_urifor the relying party public keys. Maximum allowed length is 255 characters. - Refresh Interval: Intervals at which the relying party metadata is refreshed.
- Signature Service: Select this option to encrypt the token when the NetScaler IdP sends one.
- Attributes: Name-Value pairs of attributes to be inserted in the ID token. Configuration format is
name=value_expr@@@name2=value2_expr@@@. The@@@format is used as a delimiter between the name-value pairs. - Send Password: Select this option to send the encrypted password in the ID token.
- Create an audit message action.
- On the Create Authentication OAuth IDP Policy page, click Add in the Log Action field.
- On the Create Audit Message Action page, set values for the following parameters and click Create.
- Name: Name of the audit message action.
- Log Level: Audit log level, which specifies the severity level of the log message being generated.
- Expression: Default-syntax expression that defines the format and content of the log message.
- Log in newnslog: Sends the message to the new NSLOG server.
-
Create an authentication OAuth server.
- Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > Actions > OAUTH Actions and click Add.
- On the Create Authentication OAuth Server page, set values for the required parameters and click Create.
- Bind the OAuth IdP policy to the authentication OAuth server.
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
To configure NetScaler as an IdP using the OIDC protocol by using the CLI
At the command prompt, type the following commands:
add authentication OAuthIDPProfile <name> [-clientID <string>][-clientSecret ][-redirectURL <URL>][-issuer <string>][-audience <string>][-skewTime <mins>] [-defaultAuthenticationGroup <string>]
add authentication OAuthIdPPolicy <name> -rule <expression> [-action <string>] [-undefAction <string>] [-comment <string>][-logAction <string>]
add authentication ldapAction aaa-ldap-act -serverIP 10.0.0.10 -ldapBase "dc=aaa,dc=local"
ldapBindDn <administrator@aaa.local> -ldapBindDnPassword <password> -ldapLoginName sAMAccountName
add authentication policy aaa-ldap-adv-pol -rule true -action aaa-ldap-act
bind authentication vserver auth_vs -policy <ldap_policy_name> -priority 100 -gotoPriorityExpression NEXT
bind authentication vserver auth_vs -policy <OAuthIDPPolicyName> -priority 5 -gotoPriorityExpression END
bind vpn global –certkey <>
<!--NeedCopy-->
Notes:
You can bind more than one key. Public parts of certificates bound are sent in response to
jwks\_uri query (https://gw/oauth/idp/certs).The OAuth IdP introspective endpoint supports the property
active: true.If the authentication virtual server is configured as an OAuth IdP, the well-known OAuth IdP discovery endpoint URL must be
https://<netscaler-oauth-idp-fqdn>/oauth/idp/.well-known/openid-configuration.NetScaler configured as an OAuth IdP does not display the
client_secret_post,client_secret_jwt,private_key_jwt, andclient_secret_basictoken endpoint authentication methods in the.well-known-Endpointresponse sent to the OAuth SP.
Encrypted tokens support on OIDC protocol
NetScaler with the OIDC mechanism now supports the sending of encrypted tokens along with signed tokens. NetScaler uses JSON web encryption specifications to compute the encrypted tokens and supports only compact serialization of encrypted tokens. To encrypt an OpenID token, NetScaler requires the public key of the relying party (RP). The public key is obtained dynamically by polling the relying party’s well-known configuration endpoint.
A new “relyingPartyMetadataURL” option is introduced in the “authentication OAuthIDPProfile.” profile.
To configure the relying party’s endpoint by using CLI
At the command prompt, type:
set authentication OAuthIDPProfile <name> [-relyingPartyMetadataURL <URL>] [-refreshInterval <mins>] [-status < >]
<!--NeedCopy-->
-
relyingPartyMetadataURL - Endpoint at which NetScaler IdP can get details about the relying party being configured. Metadata response must include endpoints for jwks_uri for RP public keys.
-
refreshInterval - Defines the rate at which this endpoint must be polled to update the certificates in minutes.
-
status - Reflects the status of the polling operation. The status is complete once NetScaler successfully obtains the public keys.
Example,
set authentication OAuthIDPProfile sample_profile -relyingPartyMetadataURL https://rp.customer.com/metadata -refreshInterval 50 -status < >
<!--NeedCopy-->
After the endpoint is configured, NetScaler first polls the relying party’s well-known endpoint to read the configuration. Currently, NetScaler processes only the ‘jwks_uri’ endpoint.
- If the ‘jwks_uri’ is absent in the response, the status of the profile is not complete.
- If the ‘jwks_uri’ is present in the response, NetScaler polls that endpoint also to read the public keys of the relying party.
Note:
Only RSAES-OAEP and AES256 GCM encryption type algorithms are supported for token encryption.
Custom attributes support on OpenID Connect
The OpenID relying parties might require more than a user name or a user principal name (UPN) in the token to create the user profile or make authorization decisions. Most commonly, the user groups are required to apply authorization policies for the user. Sometimes, more details, such as the first or the last name is required for provisioning a user account.
NetScaler configured as an IdP can be used to send extra attributes in the OIDCid_token using expressions. Advanced policy expressions are used to send the custom attributes as per the requirement. The NetScaler OAuth IdP evaluates the expressions corresponding to the attributes and then computes the final token.
NetScaler automatically applies JSONify in the output data. For example, numbers (such as SSN) or boolean values (true or false) are not surrounded by quotes. Multi-valued attributes, such as groups are placed within an array marker (“[” and “]”). The complex type attributes are not automatically computed, and you can configure the PI expression of those complex values as per your requirement.
To configure the relying party’s endpoint by using CLI
At the command prompt, type:
set oauthidpprofile <name> -attributes <AAA-custom-attribute-pattern>
<!--NeedCopy-->
The <AAA-custom-attribute-pattern> can be described as:
Attribute1=PI-Expression@@@attribute2=PI-Expression@@@
‘attribute1’,’attribute2’ are literal strings that represent the name of the attribute to be inserted in the ID token.
Note:
In the following example, the maximum value of the
"q{myname=http.req.user.name@@@ssn="123456789"@@@jit="false"@@@groups=http.req.user.groups}"expression can be 2000 bytes. It contains 4 custom attributes (myname, ssn, jit, groups). The maximum value of each custom attribute is 10000 bytes. For example, the groups attribute (evaluated based on the PI expressionhttp.req.user.groups) can contain upto 10000 bytes of data in the OIDCid_token.Example:
set oauthidpprofile sample_1 -attributes "q{myname=http.req.user.name@@@ssn="123456789"@@@jit="false"@@@groups=http.req.user.groups}"
- Preceding PI expression is an advanced policy expression that represents the value to be used against the attribute. The PI expression can be used to send a string literal, such as “‘hardcoded string”’. The string literal is surrounded by double quotes around single quotes or double quotes around a start pattern (the start pattern is
"q()"). If the value of the attribute is not a string literal, the expression is evaluated at runtime and its value is sent in token. If the value at runtime is empty, the corresponding attribute is not added to the ID token.- As defined in the example, “false” is a literal string for the attribute “jit”. Also, “
ssn” has hardcoded value for reference. Groups and “myname” are PI expressions that yield strings.
Support for active-active GSLB deployments on NetScaler Gateway
NetScaler Gateway configured as an Identity Provider (IdP) using the OIDC protocol can support active-active GSLB deployments. The active-active GSLB deployment on NetScaler Gateway IdP provides the capability to load balance an incoming user login request across multiple geographic locations.
Important
We recommend you to bind CA certificates to the SSL service and enable certificate validation on the SSL service for enhanced security. For more information on configuring a GSLB setup, see Example of a GSLB setup and configuration.