SSORule CRD can be used to configure OAuth or SAML specific properties for L7 virtual services that are created by the AKO from Kubernetes Ingress and Openshift Route objects. The SSORule CRD specifies an fqdn field, which is used to attach the SSORule to a virtual service. A given SSORule is applied to a virtual service if the virtual service hosts the fqdn specified in the SSORule CRD object.

The SSORule CRD can be used to configure either OAuth/OIDC properties or SAML service provider properties, along with the SSO policy. A sample SSORule CRD object with OAuth/OIDC properties looks like this:

apiVersion: ako.vmware.com/v1alpha2
kind: SSORule
metadata:
  name: my-ssorule
  namespace: default
spec:
  fqdn: my-ssorule.test.com
  oauthVsConfig:
    cookieName: OAUTH_XYZ
    cookieTimeout: 120
    logoutURI: https://my-ssorule.test.com/oauth/logout
    oauthSettings:
    - appSettings:
        clientID: my-client-id
        clientSecret: my-oauth-secret
        oidcConfig:
          oidcEnable: true
          profile: true
          userinfo: true
        scopes: ["scope1"]
      authProfileRef: okta-oauth
      resourceServer:
        accessType: ACCESS_TOKEN_TYPE_OPAQUE
        introspectionDataTimeout: 60
        opaqueTokenParams:
          serverID: my-server-id
          serverSecret: my-oauth-secret
    redirectURI: https://my-ssorule.test.com/oauth/callback
    postLogoutRedirectURI: https://my-ssorule.test.com/oauth/postLogoutRedirectURI
  ssoPolicyRef: oauth

A sample SSORule CRD object with SAML properties looks like this:

apiVersion: ako.vmware.com/v1alpha2
kind: SSORule
metadata:
  name: my-ssorule
  namespace: default
spec:
  fqdn: my-ssorule.test.com
  samlSpConfig:
    authnReqAcsType: SAML_AUTHN_REQ_ACS_TYPE_NONE
    cookieName: saml-cookie
    cookieTimeout: 120
    entityID: my-ssorule.test.com
    singleSignonURL: https://my-ssorule.test.com/sso/acs/
    signingSslKeyAndCertificateRef: my-test-app-secret
    useIdpSessionTimeout: false
  ssoPolicyRef: saml-app
Note:

The SSORule CRD is supported only for NSX Advanced Load Balancer Controller version 22.1.3 and above. It only supports the configuration of OAuth and SAML SSO protocols currently. Also, the SSORule CRD is only supported for Enhanced Virtual Hosting (EVH). When the shard virtual service size is LARGE or MEDIUM or SMALL, the OAuth and SAML settings will only be configured on the EVH child virtual services.

Specific Usage of SSORule CRD

SSORule CRD can be created in a given namespace where the operator intends to have more control. The section below walks over the details and associated rules for using each field of the SSORule CRD.

SSORule to VS Matching Using FQDN

A given SSORule is applied to a virtual service if the VS hosts the fqdn mentioned in the SSORule CRD. This FQDN must exactly match the one the virtual service is hosting.

fqdn: my-ssorule.test.com

Express OAuth/OIDC Configuration for Virtual Service

The SSORule CRD can be used to configure the OAuth/OIDC properties of an L7 virtual service. The OAuth/OIDC configuration needs to be specified in the oauthVsConfig field.

 oauthVsConfig:
    cookieName: OAUTH_XYZ
    cookieTimeout: 120
    logoutURI: https://my-ssorule.test.com/oauth/logout
    oauthSettings:
    - appSettings:
        clientID: my-client-id
        clientSecret: my-oauth-secret
        oidcConfig:
          oidcEnable: true
          profile: true
          userinfo: true
        scopes: ["scope1"]
      authProfileRef: okta-oauth
      resourceServer:
        accessType: ACCESS_TOKEN_TYPE_OPAQUE
        introspectionDataTimeout: 60
        opaqueTokenParams:
          serverID: my-server-id
          serverSecret: my-oauth-secret
    redirectURI: https://my-ssorule.test.com/oauth/callback
    postLogoutRedirectURI: https://my-ssorule.test.com/oauth/postLogoutRedirectURI

The properties under the oauthVsConfig field are discussed in detail below:

Express Name for Authorized Session Cookie

The cookieName property can be used to express the name of HTTP cookie for an authorized session. If this field is not specified, NSX Advanced Load Balancer will create the authorized session cookie with a random name.

cookieName: OAUTH_XYZ
Express Timeout for Authorized Session Cookie

The cookieTimeout property can be used to specify the HTTP cookie timeout in minutes for an authorized session. It supports values from 1 to 1440 and defaults to 60.

cookieTimeout: 120
Express Logout URI for OAuth

The logoutURI property can be used to express the URI that will trigger OAuth logout.

logoutURI: https://my-ssorule.test.com/oauth/logout
Express Application and IDP settings for OAuth/OIDC

The oauthSettings property can be used to express the application specific OAuth configuration and Identity Provider (IDP) settings for OAuth/OIDC. The application specific properties are specified as a list of appSettings properties.

Express Client ID

The clientID property can be used to express the client ID for the application. It is an application-specific identifier registered with the authorization server or Identity Provider (IDP).

clientID: my-client-id
Express Client Secret

The clientSecret field can be used to express the client secret for the application. It is an application specific identifier secret registered with the authorization server, or IDP. Since clientSecret is a sensitive field in NSX Advanced Load Balancer, AKO requires it to be specified inside a Kubernetes Secret object. So, this clientSecret field must be the name of the Kubernetes secret object that specifies the actual client secret value (Base64 encoded) in the clientSecret data field. This Kubernetes secret object must be created in the same namespace as the SSORule.

clientSecret: my-oauth-secret

A sample Kubernetes secret object, with the actual value for client and secret (Base64 encoded) in the clientSecret data field is shown below:

  apiVersion: v1
  data:
    clientSecret: bXktY2xpZW50LXNlY3JldA==
    serverSecret: bXktc2VydmVyLXNlY3JldA==
  kind: Secret
  metadata:
    name: my-oauth-secret
  type: Opaque
Express OpenID Connect Configuration

The oidcConfig property can be used to express OpenID Connect specific configuration.

  oidcConfig:
    oidcEnable: true
    profile: true
    userinfo: true

  • oidcEnable: If set to true, adds OpenID as one of the scopes enabling the OpenID Connect flow.

  • profile: If set to true, will allow fetching profile information by enabling profile scope. It is set to true by default.

  • userinfo: If set to true, will allow fetching profile information from the Userinfo Endpoint.

Express Scope for OAuth

The scopes property can be used to express the scope for OAuth to give limited access to the application.

scopes: ["scope1"]
Express Authentication Profile for OAuth

SSORule CRD can be used to express the authentication profile reference for OAuth. The authentication profile must be created in the NSX Advanced Load Balancer Controller before referring to it.

authProfileRef: okta-oauth

The Auth Profile must specify all the endpoints and configurations associated with the Identity Provider (IDP) and will be used for validating users.

Express Resource Server OAuth Configuration

The accessType property can be used to express the access token type. The access token type can either be opaque or JWT.

accessType: ACCESS_TOKEN_TYPE_OPAQUE

Or

accessType: ACCESS_TOKEN_TYPE_JWT
Express Introspection Data Timeout

The introspectionDataTimeout property can be used to set the lifetime of the cached introspection data in minutes. It supports values from Zero (0) to 1440 and defaults to Zero (0). However, it will be set only if the access token type is opaque.

introspectionDataTimeout: 60
Express Opaque Token Parameters

The opaqueTokenParams property must be specified if the accessType property is ACCESS_TOKEN_TYPE_OPAQUE. It can be used to express the validation parameters to be used when the access token type is opaque. This Kubernetes secret object must be created in the same namespace as the SSORule.

opaqueTokenParams: serverID: my-server-id serverSecret: my-oauth-secret

The serverID property can be used to express the server ID for the resource server. It is the resource server specific identifier registered with the authorization server or Identity Provider(IDP), and is used to validate against the introspection endpoint when the access token type is opaque. The serverSecret field can be used to express the server secret for the resource server. It is a resource server specific identifier secret registered with the authorization server, or IDP. Since serverSecret is a sensitive field in NSX Advanced Load Balancer, AKO requires it to be specified inside a Kubernetes Secret object. So, this serverSecret field must be the name of the Kubernetes secret object that specifies the actual server secret value (Base64 encoded) in the serverSecret data field. This Kubernetes secret object must be created in the same namespace as the SSORule. The server and client secrets can be specified in the same or different Kubernetes objects, as already shown in Express Client Secret.

Express Redirect URI for OAuth

SSORule CRD can be used to express the redirect URI that is specified in the request to the authorization server or Identity Provider (IDP). The redirect URI is the callback entry point of the application where the authorization server sends the user once the application has been successfully authorized and granted an authorization code.

redirectURI: https://my-ssorule.test.com/oauth/callback
Express Post Logout Redirect URI for OAuth

SSORule CRD can be used to express the post-logout redirect URI for the application. It is the URI to which the Identity Provider (IDP) will redirect after application logs out of the IDP.

postLogoutRedirectURI: https://my-ssorule.test.com/oauth/postLogoutRedirectURI
Express Application Specific SAML configuration

SSORule CRD can be used to express the application specific configuration, namely, SAML service provider configuration for the L7 virtual service. The SAML service provider configuration needs to be specified in the samlSpConfig field.

  samlSpConfig:
    acsIndex: 64
    authnReqAcsType: SAML_AUTHN_REQ_ACS_TYPE_INDEX
    cookieName: saml-cookie
    cookieTimeout: 120
    entityID: my-ssorule.test.com
    singleSignonURL: https://my-ssorule.test.com/sso/acs/
    signingSslKeyAndCertificateRef: my-test-app-secret
    useIdpSessionTimeout: false

The properties under the samlSpConfig field are discussed in detail below.

Express Assertion Consumer Service Index

The acsIndex property can be used to express the index to be used in the AssertionConsumerServiceIndex attribute of the authentication request. It will be set only if the authnReqAcsType is set to SAML_AUTHN_REQ_ACS_TYPE_INDEX. It supports values from 0 to 64.

acsIndex: 64
Express Assertion Consumer Service Type for Authentication Request

The authnReqAcsType property can be used to express the assertion consumer service type for authentication requests. It will determine the ACS attributes that will be set in the authentication request. It supports the following three values:

Value

Description

SAML_AUTHN_REQ_ACS_TYPE_NONE

No ACS attributes will be set in the SAML authentication request

SAML_AUTHN_REQ_ACS_TYPE_URL

The AssertionConsumerServiceURL attribute will be set in the SAML authentication request. The ACS URL must be equal to the single sign on URL set for the virtual service

SAML_AUTHN_REQ_ACS_TYPE_INDEX

The AssertionConsumerServiceIndex attribute of the SAML authentication request will be set with the value specified in the acsIndex property
Express Name for Authenticated Session Cookie

The cookieName property can be used to express the name of HTTP cookie for an authenticated session. If this field is not specified, NSX Advanced Load Balancer will create the authenticated session cookie with a random name.

cookieName: saml-cookie
Express Timeout for Authenticated Session Cookie

The cookieTimeout property can be used to specify the timeout for HTTP cookie in minutes for an authenticated session. It supports values from 1 to 1440 and defaults to 60.

cookieTimeout: 120
Express Entity IP for SAML Service Provider Application

The entityID property can be used to express the globally unique entity ID for the SAML Service Provider application. The SAML application entity ID on the Identity Provider (IDP) must match this.

entityID: my-ssorule.test.com
Express SslKeyAndCertificateRef for SAML Service Provider Application

The signingSslKeyAndCertificateRef property can be used to express SslKeyAndCertificate reference for the SAML Service Provider application. The SslKeyAndCertificate must be created in the NSX Advanced Load Balancer Controller before referring to it. The service provider will use this SSL certificate to sign requests going to the Identity Provider (IDP) and decrypt the assertions coming from IDP.

signingSslKeyAndCertificateRef: my-test-app-secret
Express Single Sign on URL for SAML

The singleSignonURL property can be used to express the single sign on URL for the application. It specifies the endpoint to receive the authentication response and the destination endpoint to be configured for the application on the IDP. If the authnReqAcsType is set to SAML_AUTHN_REQ_ACS_TYPE_URL, this endpoint will be sent in the AssertionConsumerServiceURL attribute of the authentication request.

singleSignonURL: https://my-ssorule.test.com/sso/acs/
Express IDP Control for Service Provider Session Timeout

The useIdpSessionTimeout property can be used to enable the Identity Provider (IDP) to control the duration in which the Service Provider (SP) session can exist through the SessionNotOnOrAfter field in the AuthNStatement of the SAML Response.

useIdpSessionTimeout: false
Express SSO Policy for the Virtual Service

The SSORule CRD can be used to express the SSO policy reference for the virtual service. The SSO Policy must be created in the NSX Advanced Load Balancer Controller before referring to it. The SSO policy can be of type OAUTH or SAML, depending on the SSO protocol that needs to be configured for the virtual service.

ssoPolicyRef: my-sso-policy

The oauthVsConfig and samlSpConfig are one of fields, and only one of them can be configured since a virtual service can specify either OAuth or SAML as the SSO protocol.

Status Messages

The status messages are used to give instantaneous feedback to the users about the reference objects specified in the SSORule CRD.

Following are some sample status messages:

$ kubectl get ssorule
NAME         STATUS     AGE
my-sso-rule   Accepted   3d5s

Accepted SSORule Object

$ kubectl get ssorule
NAME         STATUS     AGE
my-sso-rule   Accepted   3d5s

An SSORule is accepted only when all the reference objects specified inside it exist in the NSX Advanced Load Balancer Controller.

Rejected SSORule object

$ kubectl get ssorule
NAME            STATUS     AGE
my-sso-rule-alt  Rejected   2d23h

The detailed rejection reason can be obtained from the status:

 status:
    error: authprofile "okta-oauth" not found on controller
    status: Rejected

Caveats

  1. SSORule is only supported for Enhanced Virtual Hosting (EVH)

    SSORule CRD is only supported for Enhanced Virtual Hosting (EVH). The OAuth and SAML settings will only be configured on virtual services when EVH is enabled. When shard virtual service size is LARGE or MEDIUM or SMALL, the OAuth and SAML settings will only be configured on the EVH child virtual services.

  2. SSORule can get rejected on OpensShift if useDefaultSecretsOnly is true in the AKO configuration

    An SSORule, created on an OpenShift cluster to configure OAuth settings for a virtual service, might get rejected if useDefaultSecretsOnly is set to true in AKO configuration. This is because AKO will only handle default secrets in the namespace where AKO is installed.

  3. SSORule deletion

    If an SSORule is deleted, all the settings for the FQDNs are withdrawn from the NSX Advanced Load Balancer Controller.

  4. SSORule admission

    An SSORule CRD is only admitted if all the objects referenced in it exist in the NSX Advanced Load Balancer Controller. If, after admission, the object references are deleted out-of-band, the AKO does not re-validate the associated SSORule CRD objects. The user needs to manually edit or delete the object, for new changes to take effect.

  5. Duplicate FQDN rules

    Two SSORule CRDs cannot be used for the same FQDN information across namespaces. If AKO finds a duplicate FQDN in more than one SSORule, AKO honours the first SSORule that gets created and rejects the others. In the case of AKO reboots, the CRD that gets honoured might not be the same as the one honoured earlier.