You can set up multiple BlueCat Gateway instances to authenticate behind a load balancer. This is useful for balancing distribution loads, or (when authenticating with BlueCat Address Manager) as part of a High Availaibilty strategy, to maintain functionality when a single Gateway instance fails or becomes otherwise unavailable. Once a user authenticates with the primary Gateway instance, any Gateway instance behind the load balancer can process any other incoming request from the same user without having to log in again.
IMPORTANT: When setting up Gateway behind a load balancer, you must configure all Gateway instances identically. In particular, the Secret key configured in all Gateway instances must be the same.
During authentication, the cookie is signed with the secret key and sent to the user's browser. If the secret key differs between Gateway instances, Gateway cannot unpack values from cookies and API requests will fail.
To set the secret key in a Gateway instance:
In Gateway, go to the General configuration page. (Click
Settings at the bottom of the navigator on the left, expand
Configurations, then click General
configuration)Scroll down to and expand the Certificates section.
In the Secret key field, enter the desired secret key value.
How Gateway works behind a load balancer
Gateway uses cookies to manage user sessions and tokens received from the platform it authenticates with upon the initial login to that platform. With these cookies, after authenticating with that platform, other Gateway instances behind a load balancer can make requests to the platform without having to log in again. Cookies are valid as long as the access token is valid. There is a timeout period for the access token, determined by the session timeout.
Gateway creates these cookies using Flask Session (an extension of the Flask web framework). It stores the user login ID, stores the BAM access token, and contains other related data needed for authentication. Gateway creates these cookies based on a Secret key that a user can provide in the Gateway UI. (This is the same Secret key used to encrypt passwords for Mongo and Mail UI.)
When a user logs in to Gateway, Gateway creates and returns a cookie, which is stored in the web browser. Any further requests that the browser sends to Gateway will include this cookie. During these requests, Gateway checks the cookie for the authentication token and checks other information stored in the cookie. If the request is deemed valid, Gateway will process the request and send back a response.
Assuming you configure all Gateway instances behind a load balancer to use the same secret key to pack and unpack the session cookie, any Gateway instance can decrypt and verify the session data regardless of which Gateway instance initially set the cookie. This makes sure that the session remains valid across different servers and that the user does not have to re-login when requests go to different instances of Gateway.