Client and Resource Server for OAuth/OIDC
Overview
Starting with release 21.1.3, NSX Advanced Load Balancer (also known as Avi) can act as Client and Resource Server for OAuth/OIDC use cases. Being a Client and Resource Server, NSX Advanced Load Balancer will get the authorization code from the end user, exchange the authorization code with an access_token, validate the access_token, allow the client to access the resource based on the token validation and authorization policies based on the claims.
The same virtual service will act as a client and resource server.
Request Flow
The request flow is explained below:
- The resource owner tries to access an application.
- The client (NSX Advanced Load Balancer) initiates the flow by directing the resource owner’s user-agent to the authorization endpoint. NSX Advanced Load Balancer as a client stores session information including its client identifier, and a redirection URI/call-back URI to which the authorization server will send the user-agent back once access is granted (or denied).
- The resource owner sends the request to the authorization server at the authorization endpoint.
- The authorization server authenticates the resource owner (using the user agent) and establishes whether the resource owner grants or denies the client’s access request. Assuming the resource owner grants access, the authorization server redirects the user agent back to the client using the redirection URI/call-back URI provided earlier (in the request or during client registration). The redirection URI includes an authorization code.
- The resource owner sends a request with the client redirect URL and the authorization code.
- The client requests an
access_tokenfrom the authorization server’s token endpoint by including the authorization code received in the previous step. When making the request, the client authenticates with the authorization server using the client_id and client_secret. - The authorization server authenticates the client, validates the authorization code. If valid, the authorization server responds back with an
access_tokenand, optionally, a refresh token and if OIDC is enabled thenid_tokenis also issued by the authorization server. - NSX Advanced Load Balancer as a Client sets a session cookie and sends a request to the resource owner with the resource URL.
- The resource owner sends a request with the session cookie. On receiving the request, NSX Advanced Load Balancer retrieves the
access_tokenusing the session cookie. - NSX Advanced Load Balancer being the resource server validates the
access_token. If the Access Token is of type JWT then NSX Advanced Load Balancer validates theaccess_tokenon its own. If the Access Token is of type Opaque, then NSX Advanced Load Balancer sends the request to the introspection endpoint of the authorization server to validate the opaque token. - Based on the validation result, NSX Advanced Load Balancer will either provide access or deny it.
- If the
access_tokenis validated, the request is sent to the backend server. - The server responds back.
- NSX Advanced Load Balancer sends the response to the resource owner. Further requests must carry the session ID and steps 10-14 must be followed.
Responsibilities
Avi Virtual Service as a Client and Resource Server
The responsibilities of the OAuth Client are:
- Redirecting an unauthenticated client to an authorization endpoint of the provider - Generating the state and nonce parameter for the same. Currently, the nonce is not generated since it is not mandatory for authorization code flow.
- Exchanging code with a token for retrieving Access Token and ID Token (in case of OIDC).
- ID token validation (JWT) - OIDC mandates that access token hash also must be validated.
- Storing the session info - Access Token, refresh Token and relevant details from the ID Token.
- Creating the session cookie and setting the client response.
- Delegate the request to the resource server when the end-user presents a proper session cookie.
- Refreshing the
access_tokensafter expiry.
The responsibilities of the OAuth Resource Server are:
- Validating
access_tokenusing:- JWT validation with JWKS URI downloaded from jwks_uri.
- Introspection-based validation in the case of an opaque token.
- JWT validation with JWKS URI downloaded from jwks_uri.
Using Refresh Token to Obtain a New Access Token (Using NSX Advanced Load Balancer)
When the request comes to the Avi Virtual Service, the Access Token is retrieved using the session cookie. If the Access Token is expired, Avi sends the refresh token to the token endpoint of the authorization server to get a new access_token. The authorization server responds with an access_token and id_token. Avi (client) validates the id_token, stores the id_token and access_token, and updates the session cookie. Then the access_token is validated. In case of successful validation, access to the resource is granted.
Using UserInfo Endpoint
Note: After the cookie is issued to the client, the rest of the request flow is the same as depicted in the request flow diagram above.
The UserInfo endpoint can be used to retrieve identity information about a user. Extract the user info from the userinfo-endpoint, if the userinfo flag is configured under the OIDC parameters. If the userinfo flag is not configured under the OIDC parameters, the userinfo is extracted from one of the claims in the id_token.
Configuration
- Following are the unique hosts associated with various endpoints used in the auth profile
For example, OKTA is used as an authorization server for this configuration guide.
Following are the OKTA endpoints:Type of Endpoint Endpoint Authorization Endpoint https://dev-477407.oktapreview.com/oauth2/v1/authorize Token Endpoint https://dev-477407.oktapreview.com/oauth2/v1/token Introspection Endpoint https://dev-477407.oktapreview.com/oauth2/v1/introspect jwks_uri https://dev-477407.oktapreview.com/oauth2/v1/keys Issuer https://dev-477407.oktapreview.com Userinfo Endpoint https://dev-477407.oktapreview.com/oauth2/v1/userinfo Here,
- unique_fqdn = dev-477407.oktapreview.com
- Create a Pool with servers = unique hosts / FQDN or IP address + ports as shown in step 2
Note:
- It is recommended to use OAuth with HTTPS. So, the pool must have SSL enabled with port 443.
- Some Authorization servers can have different FQDN/hosts for different endpoints. In that case, all the hosts must be added as servers in the pool configuration.
-
Pool Configuration
Configure the pool as shown below:
[admin: ctrl]: > configure pool okta-pool [admin: ctrl]: pool> default_server_port 443 [admin: ctrl]: pool> ssl_profile_ref System-Standard [admin: ctrl]: pool> servers [admin: ctrl]: pool:servers> hostname dev-477407.oktapreview.com [admin:ctrl]: pool:servers> resolve_server_by_dns [admin:ctrl]: pool:servers> resolve_server_by_dns [admin:ctrl]: pool:servers> save [admin:ctrl]: pool> save +-------------------------------------------+------------------------------------------------+ | Field | Value | +-------------------------------------------+------------------------------------------------+ | uuid | pool-ae3e31cb-eaf9-4014-b3f0-2a7391b9f767 | | name | okta-pool | | default_server_port | 443 | | graceful_disable_timeout | 1 min | | connection_ramp_duration | 10 min | | max_concurrent_connections_per_server | 0 | | servers[1] | | | ip | 34.236.241.37 | | hostname | dev-477407.oktapreview.com | | enabled | True | | ratio | 1 | | verify_network | False | | resolve_server_by_dns | True | | static | False | | rewrite_host_header | False | | servers[2] | | | ip | 34.236.241.36 | | hostname | dev-477407.oktapreview.com | | enabled | True | | ratio | 1 | | verify_network | False | | resolve_server_by_dns | True | | static | False | | rewrite_host_header | False | | servers[3] | | | ip | 34.236.241.38 | | hostname | dev-477407.oktapreview.com | | enabled | True | | ratio | 1 | | verify_network | False | | resolve_server_by_dns | True | | static | False | | rewrite_host_header | False | | lb_algorithm | LB_ALGORITHM_LEAST_CONNECTIONS | | lb_algorithm_hash | LB_ALGORITHM_CONSISTENT_HASH_SOURCE_IP_ADDRESS | | ssl_profile_ref | System-Standard | | inline_health_monitor | True | | use_service_port | False | | capacity_estimation | False | | capacity_estimation_ttfb_thresh | 0 milliseconds | | vrf_ref | global | | fewest_tasks_feedback_delay | 10 sec | | enabled | True | | request_queue_enabled | False | | request_queue_depth | 128 | | host_check_enabled | False | | sni_enabled | True | | rewrite_host_header_to_sni | False | | rewrite_host_header_to_server_name | False | | lb_algorithm_core_nonaffinity | 2 | | lookup_server_by_name | False | | analytics_profile_ref | System-Analytics-Profile | | tenant_ref | admin | | cloud_ref | Default-Cloud | | server_timeout | 0 milliseconds | | delete_server_on_dns_refresh | True | | enable_http2 | False | | ignore_server_port | False | | routing_pool | False | | append_port | NON_DEFAULT_80_443 | | http2_properties | | | max_http2_control_frames_per_connection | 0 | | max_http2_header_field_size | 4096 bytes | | server_disable_type | DISALLOW_NEW_CONNECTION | | use_service_ssl_mode | False | +-------------------------------------------+------------------------------------------------+ -
Authentication Profile Configuration
Configure the authprofile as shown below:
[admin:ctrl]: > configure authprofile Okta-OAuth [admin:ctrl]: authprofile> type auth_profile_oauth [admin:ctrl]: authprofile> oauth_profile [admin:ctrl]: authprofile:oauth_profile> authorization_endpoint URL of authorization server. cancel Exit the current submode without saving do Execute a show command introspection_endpoint URL of token introspection server. issuer Uniquely identifiable name of the Token Issuer. jwks_timeout Lifetime of the cached JWKS keys. jwks_uri JWKS URL of the endpoint that hosts the public keys that can be used to verify any JWT issued by... no Remove field oauth_resp_buffer_sz Buffering size for the responses from the OAUTH enpoints. pool_ref Pool object to interface with Authorization Server endpoints. save Save and exit the current submode show_schema show object schema token_endpoint URL of token exchange server. userinfo_endpoint URL of the Userinfo Endpoint. watch Watch a given show command where Display the in-progress object [admin:ctrl]: authprofile:oauth_profile> authorization_endpoint https://dev-477407.oktapreview.com/oauth2/v1/authorize [admin:ctrl]: authprofile:oauth_profile> token_endpoint https://dev-477407.oktapreview.com/oauth2/v1/token [admin:ctrl]: authprofile:oauth_profile> introspection_endpoint https://dev-477407.oktapreview.com/oauth2/v1/introspect [admin:ctrl]: authprofile:oauth_profile> jwks_uri https://dev-477407.oktapreview.com/oauth2/v1/keys [admin:ctrl]: authprofile:oauth_profile> issuer https://dev-477407.oktapreview.com [admin:ctrl]: authprofile:oauth_profile> userinfo_endpoint https://dev-477407.oktapreview.com/oau th2/v1/userinfo [admin:ctrl]: authprofile:oauth_profile> pool_ref okta-pool [admin:ctrl]: authprofile:oauth_profile> save [admin:ctrl]: authprofile> save +--------------------------+---------------------------------------------------------+ | Field | Value | +--------------------------+---------------------------------------------------------+ | uuid | authprofile-4b335ccf-8385-48bd-a438-51e72726cc14 | | name | okta | | type | AUTH_PROFILE_OAUTH | | oauth_profile | | | authorization_endpoint | https://dev-477407.oktapreview.com/oauth2/v1/authorize | | token_endpoint | https://dev-477407.oktapreview.com/oauth2/v1/token | | introspection_endpoint | https://dev-477407.oktapreview.com/oauth2/v1/introspect | | jwks_uri | https://dev-477407.oktapreview.com/oauth2/v1/keys | | issuer | https://dev-477407.oktapreview.com | | pool_ref | OKTA | | oauth_resp_buffer_sz | 102400 | | userinfo_endpoint | https://dev-477407.oktapreview.com/oauth2/v1/userinfo | | tenant_ref | admin | +--------------------------+---------------------------------------------------------+ -
SSOPolicy Configuration
Configure the SSO Policy as shown below:
[admin:ctrl]: > configure ssopolicy oauth [admin:ctrl]: ssopolicy> type sso_type_oauth [admin:ctrl]: ssopolicy> save +------------+------------------------------------------------+ | Field | Value | +------------+------------------------------------------------+ | uuid | ssopolicy-8a4cb441-c819-4153-a247-d78f3a2585b3 | | name | oauth | | type | SSO_TYPE_OAUTH | | tenant_ref | admin | +------------+------------------------------------------------+ -
Configure OAuth settings on the Virtual Service
Note: It is assumed that virtual service is already configured. Enable OAuth/OIDC specific configuration in the virtual service.
- Configure the sso_policy_ref as shown below:
[admin:ctrl]: > configure virtualservice OAuth-VS [admin:ctrl]: > virtualservice> sso_policy_ref oauth - Configure the oauth_vs_config as shown below:
[admin:ctrl]: virtualservice> oauth_vs_config [admin:ctrl]: virtualservice:oauth_vs_config> redirect_uri https://100.64.94.61/oauth/callback [admin:ctrl]: virtualservice:oauth_vs_config> oauth_settings New object being created [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings> auth_profile_ref okta [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings> app_settings [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:app_settings> oidc_config [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:app_settings:oidc_config> oidc_enable [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:app_settings:oidc_config> save [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:app_settings> client_id xxxxxxxxxxxxxxx [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:app_settings> client_secret xxxxxxxxxxxxxxxNote: Add the actual
client_idandclient_secretthat your authorization server has provided.[admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:app_settings> save [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server> [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server> access_type access_token_type_opaqueNote: For this example, an opaque token is used with OKTA. JWT token can be chosen instead of an opaque token, if required.
[admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server> opaque_token_params [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server:opaque_token_params> [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server:opaque_token_params> server_id xxxxxxxxxxxxxxx [admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server:opaque_token_params> server_secret xxxxxxxxxxxxxxxNote: In most of the cases,
server_idandserver_secretare the same asclient_idandclient_secretrespectively.[admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server:opaque_token_params> save s[admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings:resource_server> save s[admin:ctrl]: virtualservice:oauth_vs_config:oauth_settings> save s[admin:ctrl]: virtualservice:oauth_vs_config> save [admin:ctrl]: virtualservice> saveThe OAuth configuration is as shown below:
| sso_policy_ref | oauth | | oauth_vs_config | | | redirect_uri | https://okta-test.auth.com/oauth/callback | | cookie_name | OAUTH_IUPKWGLH | | cookie_timeout | 1 min | | oauth_settings[1] | | | auth_profile_ref | okta-oauth | | app_settings | | | oidc_config | | | oidc_enable | True | | profile | True | | userinfo | True | | client_id | xxxxxxxxxxxxxxx | | client_secret | <sensitive> | | resource_server | | | access_type | ACCESS_TOKEN_TYPE_OPAQUE | | opaque_token_params | | | server_id | xxxxxxxxxxxxxxx | | server_secret | <sensitive> | | key[1] | | | name | dc7dde0a-8a64-45b4-8ded-f65adb03c2a4 | | aes_key | b'sdZFYlVECVu9aW7XK4IhVaC8TfakvNSvp6m861tyVNc=' | +------------------------------------+-----------------------------------------------------+
- Configure the sso_policy_ref as shown below:
Troubleshooting/Logs
Check the following for visibility and troubleshooting:
- HTTP Stats
- Application Logs
- HTTP Debug Logs
HTTP Stats
Use show virtualservice <VS-name> detail | grep oauth to view the HTTP Stats:
|. oauth_requests | 167 |
| oauth_auth_requests | 56 |
| oauth_invalid_sessions | 17 |
| oauth_introspection_requests | 56 |
| oauth_introspection_responses | 0 |
| oauth_introspection_resp_failures | 0 |
| oauth_access_token_inactive | 0 |
| jwt_sub_unavailable | 0 |
| oauth_oidc_at_hash_verification_failures | 0 |
| oauth_token_refresh_requests | 0 |
| oauth_token_refresh_responses | 0 |
| oauth_token_refresh_resp_failures | 0 |
| oauth_unauth_requests | 0 |
| oauth_client_idp_redirects | 56 |
| oauth_redirect_resp_with_code | 0 |
| oauth_invalid_redirect_responses | 0 |
| oauth_code_token_exchange_requests | 0 |
| oauth_redirect_resp_state_mismatch | 0 |
| oauth_redirect_resp_code_unavailable | 0 |
| oauth_redirect_resp_state_unavailable | 0 |
| oauth_invalid_handshake_cookie | 11 |
| oauth_invalid_handshake_cookie_missing_uri | 0 |
| oauth_invalid_handshake_cookie_missing_state | 0 |
| oauth_corrupted_cookie | 5 |
| oauth_cookie_key_not_found | 0 |
| oauth_cookie_decode_error | 0 |
| oauth_cookie_decrypt_error | 0 |
| oauth_code_token_exchange_responses | 0 |
| oauth_oidc_validation_failures | 0 |
| oauth_session_create_failures | 0 |
| oauth_sessions_created | 0 |
Application Logs
For the ease of troubleshooting and debugging, there are many significant logs added for error scenarios. Some of the examples are listed below:
-
Wrong resource server secret
-
When the JWT token is missing audience claim
-
Wrong at hash in the ID Token response
Username in the Application Logs
-
During authentication callback
-
When authenticated (post authentication requests)
HTTP Debug logs
HTTP debug logs can also be used to troubleshoot OAuth/OIDC related issues.
More Granular Authorisation using the Policies or the Datascript
Using the Authorization Policies
Starting with NSX Advanced Load Balancer version 21.1.3, the role of the resource server is to validate the Access Token. The scope is not supported in this release, so no Scope-Resource Mapping will be available, that is, there is no native support for scopes, so no match type called scope in Phase 1 will be available.
However, the scope is one of the claims (attribute value(s) pairs) in the Access Token. So, scope-based authorization matches can be indirectly achieved using attribute matches.
For example, if the admin wants to map /apiA to ScopeA and /apiB to ScopeB. This can be written as attribute matches using the following authorization policy:
1+----------------------------+-------------------------------+
2| Field | Value |
3+----------------------------+-------------------------------+
4| authz_rules[1] | |
5| match | |
6| attr_matches[1] | |
7| attribute_name | scope |
8| attribute_value_list | |
9| match_criteria | CONTAINS |
10| match_str[1] | scopeA |
11| path | |
12| match_criteria | BEGINS_WITH |
13| match_str[1] | /apiA |
14| action | |
15| type | ALLOW_ACCESS |
16| authz_rules[2] | |
17| match | |
18| attr_matches[1] | |
19| attribute_name | scope |
20| attribute_value_list | |
21| match_criteria | CONTAINS |
22| match_str[1] | scopeB |
23| path | |
24| match_criteria | BEGINS_WITH |
25| match_str[1] | /apiB |
26| action | |
27| type | ALLOW_ACCESS |
28| authz_rules[3] | |
29| match | |
30| path | |
31| match_criteria | BEGINS_WITH |
32| match_str[1] | / |
33| action | |
34| type | HTTP_LOCAL_RESPONSE |
35| status_code | HTTP_RESPONSE_STATUS_CODE_401 |
36| authz_rules[4] | |
37| index | 1 |
38+----------------------------+-------------------------------+
Use Datascripts with Examples
A scope, that is, part of a claim can easily be used in any custom action using Datascripts also.
| DataScript API | oauth_get_claim |
|---|---|
| Description | Used to map a scope that is a part of a claim |
| Example | To map /apiA to ScopeA and /apiB to ScopeB:
|
Caveats and Limitations
- Only authorization code grant is supported.
- Scope and consent screens are not supported.
- Multiple IDPs cannot be configured with the same virtual service.