Azure AD sidecar¶
This feature is only available in the GCP clusters.
Experimental: this is a new feature. Use it in production, but be aware that bugs might arise.
Report any issues to the #nais channel on Slack.
A reverse proxy that automatically handles of Azure AD login, logout, and front-channel logout.
Ensure that you first enable Azure AD for your application.
Ensure that you also define an ingress for your application.
All HTTP requests to the application will be intercepted by a sidecar ("wonderwall").
If the user does not have a valid local session with the sidecar, the request will be proxied as-is without modifications to the application container.
In order to obtain a local session, the user must be redirected to the
/oauth2/login endpoint, which performs the
OpenID Connect Authorization Code Flow as specified by Microsoft.
If the user successfully completed the login flow, a session is established with the sidecar. All requests that are
forwarded to the application container will now contain an
Authorization header with the user's
access_token from Azure AD,
in addition to an
X-Wonderwall-ID-Token header which contains the
Authorization: Bearer JWT_ACCESS_TOKEN X-Wonderwall-ID-Token: JWT_ID_TOKEN
id_token acquired from this flow is validated and verified by the sidecar in accordance with the
OpenID Connect specifications.
Your application is responsible for validating the
The sidecar will occupy and use the ports
Ensure that you do not bind to these ports from your application as they will be overridden.
spec: azure: sidecar: enabled: true autoLogin: false errorPath: ""
See the NAIS manifest.
The sidecar provides these endpoints under
/oauth2/loginredirects the user to Azure AD to perform the OpenID Connect Authorization Code Flow.
/oauth2/callbackhandles callbacks from Azure AD as part of the OpenID Connect Authorization Code Flow.
/oauth2/logoutimplements self-initiated logout.
/oauth2/logout/frontchannelimplements front-channel logout.
The contract for usage of the sidecar is fairly simple. For any endpoint that requires authentication:
- Validate the
Authorizationheader as specified in the responsibilities section.
- If the
Authorizationheader is missing, redirect the user to the login endpoint.
- If the JWT
Authorizationheader is invalid or expired, redirect the user to the login endpoint.
- If you need to log out a user, redirect the user to the logout endpoint.
See https://github.com/nais/wonderwalled for an example application that does this.
Authenticate a user¶
When you must authenticate a user, redirect to the user to:
Redirect after authentication¶
Redirects after successful authentication follow these rules in ascending priority:
- The URL set in the
- The URL or relative path set in the query parameter
The host and scheme (if provided) are stripped from the redirect URL, which effectively only allows redirects to paths within your own ingress.
If you want all routes to your application to require an authenticated session, you can enable auto-login
by setting the
.spec.azure.sidecar.autoLogin field to
This will make the sidecar automatically redirect
any user to login when attempting to browse to any path for your application. You should still validate and check the
Authorization header and the token within as specified in responsibilitites and guarantees.
When you must log a user out, redirect to the user to:
The user's session with the sidecar will be cleared, and the user will be redirected to Azure AD for global logout.
Authentication should generally not fail. However, in the event that it does happen; the sidecar automatically presents the end-users with a simple error page that allows the user to retry the authentication flow.
If you wish to customize or handle these errors yourselves, set the
.spec.azure.sidecar.errorPath to the absolute path
within your ingress that should handle such requests:
spec: azure: sidecar: errorPath: /login/error
The sidecar will now redirect any errors to this path, along with the following query parameters:
correlation_id- UUID that uniquely identifies the request, for tracing and log correlation.
status_code- HTTP status code which indicates the type of error that occurred.
Responsibilities and Guarantees¶
The following describes the contract for usage of the sidecar.
The sidecar guarantees the following:
Authorizationheader is added to the original request if the user has a valid session.
Authorizationheader is removed from the original request if the user does not have a valid session.
- All HTTP requests to the
/oauth2endpoints defined above are owned by the sidecar and will never be forwarded to the application.
- The sidecar is safe to enable and use with multiple replicas of your application.
- The sidecar stores session data to a highly available Redis service on Aiven, and falls back to using cookies if unavailable.
The sidecar does not:
- Automatically refresh the user's tokens.
- Secure your application's endpoints.
- Validate the user's access token set in the
Authorizationheader. The token may be invalid or expired by the time your application receives it.
Your application should secure its own endpoints. That is, deny access to sensitive endpoints if the appropriate authentication is not supplied.
Your application should also validate the claims and signature for the Azure AD JWT
access_token attached by the sidecar.
That is, validate the standard claims such as
aud must be equal to your application's client ID in Azure AD.