Specific Usage of SSORule CRD

SSORule to VS Matching Using FQDN

fqdn: my-ssorule.test.com

Express OAuth/OIDC Configuration for Virtual Service

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

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,

Avi Load Balancer

will create the authorized session cookie with a random name.

cookieName: OAUTH_XYZ

Copy

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

Copy

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

Copy

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

Copy

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

Avi 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

Copy

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

Copy

Express OpenID Connect Configuration

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

oidcConfig:
    oidcEnable: true
    profile: true
    userinfo: true

Copy

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"]

Copy

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

Avi Load Balancer Controller

before referring to it.

authProfileRef: okta-oauth

Copy

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

Copy

Or

accessType: ACCESS_TOKEN_TYPE_JWT

Copy

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

Copy

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

Copy

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

Avi 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

Copy

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

Copy

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

Copy

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

Copy

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,

Avi Load Balancer

will create the authenticated session cookie with a random name.

cookieName: saml-cookie

Copy

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

Copy

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

Copy

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

Avi 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

Copy

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/

Copy

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

Copy

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

Avi 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

Copy

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

$ 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

Rejected SSORule object

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

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

Caveats

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.
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.
SSORule deletion
If an SSORule is deleted, all the settings for the FQDNs are withdrawn from the
Avi Load Balancer Controller
.
SSORule admission
An SSORule CRD is only admitted if all the objects referenced in it exist in the
Avi 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.
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.