Adding OIDC support to Aerie

[jmorton]

Background

This proposal is about adding OIDC to Aerie in order to remove a substantial technical barrier to adoption. SAML 2.0 is another standard that may be worth supporting in the future. However, this proposal focuses solely on OIDC.

Priority of Constituencies

Inspired by the Priority of Constituencies principle from the W3C Design Principles, this proposal assumes the following constituencies (collectively referred to as "users") for Aerie:

1. Planners
2. Modelers
3. Operators
4. Maintainers

When trade-offs need to be made, the interests of these different constituents need to be prudently balanced against eachother. This proposal will reference any such priorities, but does not seek to establish them here.

Use Cases

There is one essential use case:

1. Operators must be able configure Aerie to work with OIDC Identity Providers so that planners and modelers can authenticate with a trusted external system to obtain user credentials used to interact with Aerie through its user interface.

This proposal considers two additional use cases. However, we should discuss if this is reasonable to include as in-scope for our first iteration.

1. Operators should be able to configure external systems to obtain service account credentials that can be used to interact with Aerie's external machine interfaces (e.g., GraphQL, Gateway).

2. Operators should be able to configure Aerie to obtain service account credentials so that Aerie can interact with external systems.

Technical Considerations

What authentication flow should be used?

There are several different authorization flows. OIDC Authorization Code Flow with PKCE is the best choice because it’s secure, works seamlessly with SPAs, avoids leaking tokens in URLs, and integrates well with Hasura and Swagger-based services. Implicit flow is obsolete and insecure. Client Credentials flow isn’t for user-based login. Device Code flow is for devices without browsers.

The need for service account support is orthogonal to the authorization flow. External systems will use Client Credentials Flow to get the same type of OIDC (access) tokens from an identity provider and pass them to Aerie machine interfaces. Aerie, will consume service account and user provided tokens the same way.

What additional libraries are required to facilitate authentication?

We want to ensure we use well-maintained libraries instead of implementing our own. Ideally, libraries are released under the same license as Aerie. Any proposed libraries licensed under different terms should be discussed.

• Arctic: Provides functions for interacting with a wide variety of identity providers. MIT License.
• JwtDecode: Transforms raw base64 encoded into typed data structures. MIT License.

What configuration is needed?

A URL to an OIDC provider's well known configuration. The configuration contains URLs to resources for initiating authorization, requesting, and refreshing tokens.

Name	Example
OIDC_WELL_KNOWN_URL	https://keycloak.platform.intelligent.space/realms/master/.well-known/openid-configuration
OIDC_CLIENT_ID	development-client
OIDC_REDIRECT_URI	http://localhost:5173/auth/callback
OIDC_AUDIENCE	development-client
OIDC_SCOPE	openid profile email

What verification should be performed by the client application?

• The application must verify the 'state' value exchanged during authentication.
• The application must verify the token Issuer, Audience, Expiration.

How are routes protected?

There are two options: a centralized route protecion using server.hooks or distributed across layouts and pages. Aerie currently uses a hooks based approach. Although it's best to make minimal changes, if there is a time to reconsider this decision, now would be it!

What tokens are used?

1. An Access Token: Contains claims about what a user may do.
2. An Identity Token: Contains information about the user.
3. A Refresh Token: Used to obtain new access, identity, and refresh tokens.

What values are needed and how are they made available?

Value	Sensitivity	Cookie?	Expire	Path	Svelte State?
Provider URL	Low	No	–		No
Verifier	Very High	Yes	300s		No
Verifier Hash	Low	No	–		No
Authorization Code	High	No	–		No
State	Low	Yes	300s		No
Identity Token	Low	Yes	session	/auth	Yes
Access Token	High	Yes	session	/auth	Yes
Refresh Token	Very High	Yes	session	/auth	No
Next Refresh Time	Low	No	–		Yes
"Back" Context	Low	Yes	–		No

Important:
All authentication cookies are stored in HttpOnly, Secure tokens. Cookies containing tokens expire at the end of a session (when the browser is closed). Very-High sensitivity values are never available to client side javascript. Use cases that require these values MUST be executed on the server side in +server.ts or +page.server.ts functions. In addition, the path of these very-high sensitivty values is limited to the /auth path.

The access token is must be available to client side javascript so it can be added in the authorization header for requests to backing services (i.e., Hasura and Gateway). Access tokens should be set to expire within to mitigate the risk of a compromised token. However, this is up to the discretion of the Aerie operator to the extent they control the identity provider.

How are tokens refreshed?

Tokens are refreshed using a hidden component mounted in all pages. The component calculates the remaining shelf-life of a token and uses setTimeout to schedule refreshing tokens (if a refresh token is available). This component watches a reactive access token value to determine when it should schedule a refresh.

This component does not need the refresh token value. It invokes a backend service to perform the refresh token.

How does a user end a session?

1. Closing the browser window will end a session. This will automatically clear all tokens becaues they are contained in session cookies.
2. By activating the logout feature of the app. This will execute server side code that deletes cookies containing tokens.

• What is the client application responsible for doing? Safely managing tokens, preventing leaks, refreshing expired tokens. Adding the access token to authorization header for requests to backing services.
• What are downstream token consumers responsible for doing? Issuer, Audience, Expiration
• How does rotating key material affect the client and downstream consumers?
• When stored as cookies, what precautions are taken to protect secrets?
• How is token invalidation handled?
• What is done with existing JWTs issued by gateway?

Notional Structure for Aerie UI

We should discuss how to arrange modules so that the current authz mechanisms can co-exist. This structure is notional, it should not be construed as a suggestion to either remove the current mechanism or to commingle the two modules.

├── lib
│   ├── components
│   │   └── auth
│   │       └── Refresh.svelte
│   ├── server
│   │   └── auth.ts
│   └── stores
│       └── auth.ts
└── routes
    ├── auth
    │   ├── callback
    │   │   └── +page.server.ts
    │   ├── login
    │   │   └── +page.server.ts
    │   ├── logout
    │   │   └── +server.ts
    │   └── refresh
    │       └── +server.ts
    └── ...

Libraries

The server module provides reusable functions for creating an Arctic OIDC client (using environment variables), and decoding base64 encode tokens in cookie into JwtPayloads.

No reusable client-side module functions have been identified as of yet.

The refresh component manages access token refresh using setTimeout. It works in tandem with the /auth/refresh route and sets client state to newly obtained tokens. This component calculates the time until an access token will expire and refresh a few seconds before scheduled expiration. The current implementation provides a countdown clock and a button to manually invoke the refresh workflow. It is not intended to be visible in normal circumstances.

The auth store makes access and identity tokens available in-memory. This approach avoids the need to process cookies client-side and allows us consistently rely on the default cookie setting httpOnly: false.

Routes

The essential routes are:

1. Login
2. Callback
3. Refresh
4. Logout

A fifth route for displaying token details is also implemented, but does not need to exist in a real-world implementation.

Login

Login is implemented as a page because browsers should navigate to a page to initiate login instead of initiating login using fetch.

OIDC login requires a browser redirect to the identity provider. However, you can’t perform a login redirect from the result of a fetch because fetch requests don’t follow redirects that change the browser’s top-level URL.

Login will...

• Preserve the original location from which a login was initiated if a back query parameter was supplied.
• Generate a verifier cookie (using the Arctic library) and store it in a cookie.
• Generate a state (using the Arctic library) and store it in a cookie.
• Generate a URL to the authorization endpint (using the Arctic library).
• Redirect to the URL.

All values stored in cookies are short-lived and cleared when the identity provider redirects back to the callback route.

Callback

Callback is also implemented as a page. It will:

1. Verify the identity provider's actual state matches the expected state (generated by /auth/login and stored in a cookie).
2. Use the authorization code and previously generated verifier to request access, identity, and refresh tokens.
3. Verify the identity token issuer against previously resolved issuer configuration (specified by OIDC_WELL_KNOWN_URL).
4. Verify the application's configured audience matches the access token's audience (specified by OIDC_AUDIENCE).
5. Cleanup cookies generated by /auth/login (retaining the original location in a 'back' cookie).
6. Set session cookies for the access, identity, and refresh tokens.
7. Redirect to the original location specified by the back cookie.

Refresh

Refresh should be invoked by fetch requests from the Auth component a few seconds before the access token will expire. The fetch request automatically sends cookies to this handler. The handler obtains a new set of tokens from the identity provider. It returns a JSON object that contains the access and identity tokens so the Auth component can update in memory values of the same. If this request fails, the server sends a 401 to the client; the client should initiate login but it may display an error instead.

Logout

Currently, logout should be invoked by sending a POST via form submit or fetch requests from a navigation component. The /auth/logout route will delete the token related cookies and redirect to the home page.

For fetch requests, the client application can decide what to do next.

Hasura

We have successfully demonstrated that Hasura will work with an external identity provider and can successfully validate access tokens.

Aerie Gateway

Additional time is required to assess the impact to Aerie Gateway.

Next Steps

1. I am eager to see what questions or ideas people have and to discuss the implications for Aerie Gateway.
2. I have a 80% implemented a proof of concept in a clean SvelteKit project using Keycloak server as an IdP. The other 80% of the work I need to do before making that public and linking to it, is figuring out a comprehensive automation testing strategy.

[jmorton]

I wanted to follow up my original post with some insights gleaned from an initial implementation of OIDC. Let me start by saying that I am strongly motivated to keep token management simple. If we get this right, most of the Aerie team should be able to explain exactly what guarantees the OIDC system provides and how it works.

Since my initial post, I have realized that storing tokens in-memory subtly works against this goal. It adds inherent complexity without providing any additional real safety against a motivated attacker.

Last week, I discovered an edge cases where server-side initiated refresh of tokens is needed. There are ways to make a server-side request with stale access or id tokens and a valid refresh token. For example, you can have multiple tabs open, access Aerie UI in one, close that Aerie tab, wait a few minutes for your tokens to expire and return to Aerie in a new tab. The expected behavior of the system is dependent on enough other factors to amount to "undefined."

The solution should offer these guarantees:

1. If you make a request with invalid tokens in cookies those cookies will be deleted.
2. If you make a request with a valid refresh token and do not have a valid identity or access token, the server will attempt to obtain one for you.
3. If the cookie containing your access token changes for any reason, client-side Aerie UI will reschedule any previously scheduled refresh to a new time a short time before it expires.

The first two guarantees rely on a server side hook that performs these steps:

1. Remove any invalid access or identity tokens. Invalid means that a token has expired, malformed, does not match the expected signature, issuer, or audience. This step simplifies the next step.

2. Refresh tokens if (and only if a refresh token is present). This step doesn't need to check if an access or identity is token is expired, because it would be removed during the first step if it is. New tokens are validated and then set as httpOnly: false cookies.

Aside: A third step could also be added to this hook to improve developer experience w.r.t. defining access related rules for routes. It would set server side local values to contain the decoded access + identity token and a list of roles extracted from a specific claim in the access token.

The third guarantee requires client-side functionality. I have experimented with a solution that uses a combination of the CookieStore, setTimeout, and clearTimeout APIs to enable refresh of tokens with rescheduling. The refresh behavior relies on server-side code to obtain new refresh tokens as before, but no longer stores a JSON response in-memory on the client side.

Because this approach relies strictly on cookies, fetch requests to Gateway and Hasura are expected to read access token values from cookies.

I'm eager to hear what others think about this approach.

[GodwinShen]

Overall this looks really good. A few clarification questions below:

1. Regarding OIDC Configuration
   a. OIDC_Client_Secret is also needed along with some way of protecting the client secret in the Aerie deployment
   b. A set of valid redirect URIs to be configured on the OIDC Provider side (e.g., KeyCloak) to permit redirects back to Aerie
   c. Client authentication method for sending client secret should be specified (e.g., when using KeyCloak as identity broker with LaunchPad ADFS OIDC service the client secret is sent as HTTP POST)
   d. PKCE method should be specified, can't be plain text (this is probably assumed, but good to state explicitly and say what method, e.g., S256)
   e. TLS is assumed throughout, per https://openid.net/specs/openid-connect-core-1_0.html#TLSRequirements
2. Regarding Client verification
   a. Technically alg value should also be validated, assuming it's S256
3. Regarding how to end a user session:
   a. Do we also need to handle the case where an Aerie operator terminates a user session?
4. Regarding authN validation outside of Aerie UI, as we discussed earlier this week, Hasura and Gateway also need authN validation of the access tokens
   a. Does authN validation in Hasura and Gateway user the HTTP Authorization Header Bearer token? I guess you said already that Hasura can do it, so that's great. Sounds like Gateway is still being considered.
   b. How does refresh token work with Hasura and Gateway? Maybe Hasura already handles this as well?
5. For the programmatic access that was described earlier this week, how does a user obtain tokens that they can use in HTTP Authorization Bearer when making programmatic calls to Hasura or Gateway?
   a. Does there need to be another endpoint added that a user can hit that will "dispense a token"?
6. Regarding AuthZ:
   a. How will authZ utilize Identity Token user info to perform role based access control?
   b. Is there a schema that it relies on that jives with the existing Aerie authZ implementation? You showed an example earlier this week, it'd be good to have that written down somewhere for folks to review in more detail.
   c. Will the Aerie authZ implementation need to be adapted to handle OIDC-based authZ?
7. How does user access the OIDC logout endpoint? Will it be integrated with the existing Aerie UI logout button?
8. Will Aerie login page be augmented to include an OIDC login button? If so, will direct login to Aerie still be allowed via username and password? CAM is integrated with the existing Aerie login, so wasn't sure if the intent is to preserve the existing Aerie login method to avoid having to re-implement a different solution for CAM/JPL login. I'm assuming the main Aerie login page will live on with built-in CAM/JPL login support and a new button will be added below username/password for the OIDC login.
9. Will un-authenticated requests to any arbitrary Aerie UI route get automatically redirected to the login page?

That's all I can think of for now.

[jmorton]

We have had some synchronous conversations about how to align the existing authentication related behavior in Aerie Gateway and the proposed design introduced by PR-1746. This comment captures some background and rationale for evolving the current authorization-related endpoints in Aerie Gateway toward a set of endpoints that are compliant with OpenID Connect (OIDC).

Background

Aerie Gateway currently provides a set of authentication-related endpoints that abstract away specific identity mechanisms through an adapter pattern. Two adapters are currently supported:

JPL CAM – an integration with JPL’s enterprise identity system.

No-Auth Mode – a development mode that bypasses authentication for ease of use when an identity system is unavailable or unnecessary.

These endpoints are used to issue, validate, and revoke JWT-encoded access tokens, which are then consumed by Aerie UI and Aerie CLI tools.

When we began adding OIDC support to Aerie, we found it challenging to use the existing abstractions to implement a full OIDC Authorization Code Flow with Proof Key for Code Exchange (PKCE). For example, the current design does not natively support refresh tokens. Because we wanted to deeply understand OIDC before making architectural changes, and because OIDC best practices often recommend implementing the Authorization Code + PKCE flow in the user application (e.g., the web client or mobile or desktop app), we initially handled OIDC authentication directly within the Aerie UI, using server-side SvelteKit endpoints.

Key Insight

As our understanding of OIDC matured, we realized that Aerie Gateway itself could provide a set of OIDC-conforming endpoints that delegate to CAM (or another IdP), effectively replacing the existing authorization endpoints. This would allow the Aerie UI to use a consistent, standards-based authentication flow regardless of which identity system a mission chooses.

However, migrating to an OIDC-compliant interface would significantly affect how the Aerie CLI obtains and refreshes tokens.

Aerie CLI

CLI tools typically obtain tokens through one of two approaches:

Device Authorization Flow – The CLI presents the user with a link and a short verification code. The user opens the link in a browser, authenticates with the IdP, and the CLI polls until it receives the token set.

Headless/Service Account Flow – For automated scenarios, the CLI may use client credentials or a pre-provisioned refresh token to obtain access tokens non-interactively.

Both approaches need to handle token refresh seamlessly (e.g., storing and using refresh tokens securely, or re-prompting the user if the refresh token expires).

Next Steps

• Get and respond to feedback from Aerie team members to achieve consensus.
• Specify the changes to Aerie Gateway in more detail (e.g., what endpoints will be added, what flows will be supported).
• Build a functional prototype of Aerie CLI that works with an OIDC backend to prove this approach will work.