Configuring the OpenID Connect protocol
A Citrix ADC appliance can now be configured as an identity provider by using OpenID Connect protocol. OpenID connect protocol strengthens identity providing capabilities of the Citrix ADC appliance. You can now access enterprise wide hosted application with a single sign-on as OpenID connect offers more security by not transferring user password but works with tokens with specific lifetime. OpenID also is designed to integrate with non-browser clients such as apps and services. Therefore, OpenID Connect is widely adopted by many implementations.
Advantages of having the OpenID Connect support
- OpenID eliminates overhead of maintaining multiple authentication passwords as the user has a single identity across organization.
- OpenID provides a robust security for your password as the password is shared only with your identity provider and not with any application you access.
- OpenID has vast interoperability with various systems making it easier for the hosted applications to accept OpenID.
- OpenID is a simple protocol that enables native clients to easily integrate with servers.
To configure Citrix ADC appliance as an IdP using the OpenID Connect protocol with the GUI
-
Navigate to Configuration > Security > AAA-Application Traffic > Policies > Authentication > Advanced Policies > OAuth IdP.
-
Click Profile and click Add.
On the Create Authentication OAuth IDP Profile screen, set values for the following parameters and click Create.
- Name – Name of the authentication profile.
- Client ID – Unique string that identifies SP.
- Client Secret – Unique secret that identifies SP.
- Redirect URL – Endpoint on SP to which code/token has to be posted.
- Issuer Name – String that identifies IdP.
- Audience – Target recipient for the token being sent by IdP. This might be checked by the recipient.
- Skew Time – The time for which the token remains valid.
- Default Authentication Group – A group added to the session for this profile to simplify policy evaluation and help in customizing policies.
-
Click Policies and click Add.
-
On the Create Authentication OAuth IDP Policy screen, set values for the following parameters and click Create.
- Name – The name of the authentication policy.
- Action – Name of profile created above.
- Log Action –Name of messagelog action to use when a request matches this policy. Not a mandatory filed.
- Undefined-Result Action – Action to perform if the result of policy evaluation is undenfined(UNDEF). Not a mandatory field.
- Expression – Default syntax expression that the policy uses to respond to specific request. For example, true.
- Comments – Any comments about the policy.
Binding the OAuthIDP policy and LDAP policy to the authentication virtual server
-
Navigate to Configuration > Security > AAA-Application Traffic > Policies >Authentication > Advanced Policies > Actions > LDAP.
-
On LDAP Actions screen, click Add.
-
On Create Authentication LDAP Server screen, set the values for the following parameters, and click Create.
- Name – The name of the ldap action
- ServerName/ServerIP – Provide FQDN or IP of the LDAP server
- Choose appropriate values for Security Type, Port, Server Type, Time-Out
- Make sure Authentication is checked
- Base DN – Base from which to start LDAP search. For example, dc=aaa,dc=local.
- Administrator Bind DN: Username of the bind to LDAP server. For example, admin@aaa.local.
- Administrator Password/Confirm Password: Password to bind LDAP
- Click Test Connection to test your settings.
- Server Logon Name Attribute: Choose “sAMAccountName”
- Other fields are not mandatory and hence can be configured as required.
-
Navigate to Configuration > Security > AAA-Application Traffic > Policies >Authentication > Advanced Policies > Policy.
-
On Authentication Policies screen, click Add.
-
On Create Authentication Policy page, set the values for the following parameters, and click Create.
- Name – Name of the LDAP Authentication Policy.
- Action Type – Choose LDAP.
- Action – Choose the LDAP action.
- Expression – Default syntax expression that the policy uses to respond to specific request. For example, true**.
To configure the Citrix ADC appliance as an IdP using the OpenID Connect protocol with the command line
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>]<!--NeedCopy-->-
add authentication OAuthIdPPolicy <name> -rule <expression> [-action <string> [-undefAction <string>] [-comment <string>][-logAction <string>]<!--NeedCopy--> -
add authentication ldapAction aaa-ldap-act -serverIP 10.0.0.10 -ldapBase "dc=aaa,dc=local"<!--NeedCopy--> ldapBindDn <administrator@aaa.local> -ldapBindDnPassword <password> -ldapLoginName<!--NeedCopy-->
sAMAccountName
-
add authentication policy aaa-ldap-adv-pol -rule true -action aaa-ldap-act<!--NeedCopy--> -
bind authentication vserver auth_vs -policy <ldap_policy_name> -priority 100 -gotoPriorityExpression NEXT<!--NeedCopy--> -
bind authentication vserver auth_vs -policy <OAuthIDPPolicyName> -priority 5 -gotoPriorityExpression END<!--NeedCopy--> -
bind vpn global –certkey <><!--NeedCopy-->
Note
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)).
Encrypted tokens support on OpenID Connect
Citrix ADC appliance with OpenID Connect mechanism now supports sending of encrypted tokens along with signed tokens. The Citrix ADC appliance uses JSON web encryption specifications to compute the encrypted tokens and supports only compact serialization of encrypted tokens. To encrypt OpenID token, Citrix ADC appliance needs 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 “authentication OAuthIDPProfile.”
To configure relying party’s endpoint by using CLI
At the command prompt, type:
`set authentication OAuthIDPProfile <name> [-relyingPartyMetadataURL <URL>] [-refreshInterval <mins>] [-status < >]`
-
relyingPartyMetadataURL - This is the endpoint at which Citrix ADC IdP can get details about 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 Citrix ADC successfully obtains the public keys.
Example
set authentication OAuthIDPProfile sample_profile -relyingPartyMetadataURL https://rp.customer.com/metadata -refreshInterval 50 -status < >
After endpoint is configured, Citrix ADC appliance first polls relying party’s well-known endpoint to read configuration. Currently, the Citrix ADC appliance 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, Citrix ADC polls that endpoint also to read the public keys of the relying party.
Note:
Only RSAES-OAEP and AES GCM encryption type algorithms are supported for token encryption.
Custom attributes support on OpenID Connect
OpenID relying parties may require more than username or user principal name (UPN) in the token to create 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 user account.
Citrix ADC appliance configured as an IdP can be used to send extra attributes in the OpenID Connect id_token using expressions. Advanced policy expressions are used to send the custom attributes as per the requirement. The Citrix IdP evaluates the expressions corresponding to the attributes and then computes the final token.
Citrix ADC appliance automatically JSONify 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 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 relying party’s endpoint by using CLI
At the command prompt, type:
set oauthidpprofile <name> -attributes <AAA-custom-attribute-pattern>
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:
You can configure up to 2,000 bytes of attributes.
Example:
set oauthidpprofile sample_1 -attributes q{myname=http.req.user.name@@@ssn="123456789"@@@jit="false"@@@groups=http.req.user.groups}
- Above 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 and pattern (as stated above, 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, 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.