hypo-sh / emissary

Clojure OIDC client

Emissary

Outsource user managment to an OIDC identity provider.

Emissary makes it easy to enable your application to act as an OIDC client. It is identity provider-agnostic, meaning your application can use Emissary to connect with any spec-compliant identity provider for user management.

Status

This is pre-alpha software currently used internally at Hypo. The API is unstable and will remain so while we learn more about the nuances of OIDC. We do not recommend using Emissary at this time.

Supported identity providers

Emissary aims to be 100% compliant with the OIDC 1.0 and OAuth 2.0 specifications, and our goal is to ensure that it is compatible with any spec-compliant identity provider.

Supported flows

Flow	Supported?
Authorization	Yes
Implicit	No
Hybrid	No

(Learn more here.)

Please open an issue if you'd like to see support for an unsupported flow.

Client authentication strategies

Strategy	Supported?
client_secret_basic	Yes
client_secret_post	No
client_secret_jwt	No
private_key_jwt	No

(Learn more here.)

Please open an issue if you'd like to see support for an unsupported authentication strategy.

Testing

To run Clojure tests:

clojure -M:test

To run ClojureScript tests: (TODO)

Development

To start Clojure and ClojureScript repls:

# In your shell
clojure -M:dev:cider

;; in emacs
cider-connect-clj

;; In your repl
(user/main)

;; in emacs
cider-connect-sibling-cljs

;; in your repl
(user/main)

emissary's Issues

Gracefully handle absent `origin` remote

Currently the UI assumes that the name of the default remote is origin, but that isn't always the case. Think about how to make this configurable, etc.

Install and configure kondo

Create function that pulls browser-safe values from config map

The goal here being to make it harder to accidentally leak secret config information to the browser. Currently there is no sensitive data in the config map, but there may be in the future.

Test HTTP failures

Write tests describing what happens whenever a get or post request fails in core.

Document that it is not safe to ship config to browser

Validate ID token according to spec

https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation

Ensure all security considerations in OIDC spec are addressed

Context:
https://openid.net/specs/openid-connect-core-1_0.html#Security%Considerations

Where possible, write specs for considerations

Ensure state parameter is round-tripped correctly

See:

• https://openid.net/specs/openid-connect-core-1_0.html

---

• 3.1.2.1
• 3.1.2.5
• 3.1.2.6

Handle authentication response errors

https://openid.net/specs/openid-connect-core-1_0.html#AuthError

When auth errors occur, the error payload documented above will be passed to make-authentication-redirect-handler as part of req. This should take less than an hour to implement.

Test calls to `save-session!`

in core tests, we pass in a save-session! function. We should replace that function with a mock and assert that it is called with appropriate arguments every time it is invoked.

Fix config key for redirect after authentication

Support acr claim to mandate that authentication is phishing-resistant

• https://openid.net/specs/openid-connect-core-1_0.html
• Update 3.1.3.7.12

Validate authentication response according to spec

https://openid.net/specs/openid-connect-core-1_0.html#AuthResponseValidation
In particular, see https://datatracker.ietf.org/doc/html/rfc6749#section-10.12

Factor out hypo-specific code

Pay particular attention to make-handle-logout and make-handle-oidc.

• Make session read and write configurable (:emissary/session-id)
• Think about the relationship between db and session storage and how various users may want to configure that

Run clj tests in CI

Write test that validates that `access_token` is unsigned in make-handle-oidc

We already do this for id-token.

Run cljs tests in CI

Support use of nonce value as described by spec

• Update test 3.1.3.7.11

Handle token error response according to spec

https://openid.net/specs/openid-connect-core-1_0.html#TokenErrorResponse

Create docstrings for every public function

Don't save entire remote config

Instead, use remote config to populate the parts of emissary config necessary for emissary to work. Perform validation after remote config has been fetched.