pirogoeth / lsso

Nginx SSO middleware for protecting your internets.

lsso

lsso is a SSO middleware written in Lua to sit between Nginx and server endpoints.

lsso uses client-side cookies alongside a Redis database of session hashes to track session. In our setup, we use a fork of Osiris with a Redis token store as an OAuth endpoint.

Features:

• OAuth authentication
• Raven / Sentry support
• Cross-domain-authentication
• Backend session store in Redis
• Auth and session event logging to Redis
• CLI management tool, lssoctl (In Progress!)
• Management API (In Progress!)
• Temporary access token generation
• 2FA Support

Requirements

• Lua51 (nginx-lua requirement)
• LuaSec >= 0.5
• Raven-Lua (modified version included in external/raven.lua; includes HTTPS support for Sentry)
• Nginx-resty-cookie (included in external/resty/)
• lua-cjson (https://github.com/efelix/lua-cjson)
• redis-lua (https://github.com/nrk/redis-lua)
• OAuth server (recommended: https://github.com/pirogoeth/osiris; has been tested)
• authy-lua (required for authy-2fa; pkg: authy-lua >= 0.1.0-4, src: https://github.com/pirogoeth/authy-lua)
  • lua-resty-http (required for authy-2fa; pkg: lua-resty-http 0.07-0, src: https://github.com/pintsized/lua-resty-http)

Installation

• Clone this repo..
• Copy external/* to your lua5.1 package dir (/usr/local/share/lua/5.1/ or similar)
• Use the file from nginx/sso-init.conf to set up the main nginx conf.
  • Make sure to adjust the request rate limit to your desire.
• Use the template from nginx/sso-site.conf to set up your SSO endpoint.
  • Adjust any endpoints as you wish, but make sure to update config.lua as well.
• Grab the src/config.lua, configure it, and stick it where you want
• Change config_path in src/init.lua to point to your newly configured config.lua.
• Insert access_by_lua_file /path/to/lsso/src/access.lua; in any location, server block, etc, that you want to protect.
• Restart nginx.
• Done! (?)

Roadmap

• Authentication:
  • HTTP Basic authentication support for endpoints.
    • Stage: Researching
  • Implement SAML 2.0 authentication
    • Stage: Researching & implementing
  • Implement U2F Registration / Authentication process
    • Stage: Researching
  • Use JWT cookie instead of unsigned client cookies (? | lua-resty-jwt)
    • Stage: Researching
  • Per-location auth scoping (customizable scopes for each protected location: set $lsso_location_scope 'admin'; before access_by_lua_file)
• API:
  • API access tokens
    • Inherently different from regular access tokens, but possibly managed/requested through the same endpoint?
    • If using a different endpoint, possibly /api/auth (?).
  • Some user-facing endpoints for managing sessions:
    • /auth/logout - kill the active user session, if any.
  • API for token requests, management, health, etc.
    • /api/_health - simple status
    • /api/token/request - request access token
    • Log access endpoints
      • /log/api - api event log
      • /log/auth - authentication event log
      • /log/session - session event log
      • ...
    • ...
• Metadata:
  • Metadata store implementation
    • Required for U2F and other 2FA implementations
    • Should be an ephemeral data store, possibly key-value or record-based
    • Implementation language does not need to be Lua...
    • Should be simplistic, have an HTTP API, HTTP client
    • Should not depend on a temporal data store such as Redis (unless configured as persistent store)
    • Stage: Researching
• Miscellaneous:
  • More documentation!
  • Stats collection for info about user sessions, login attempts, page accesses (?)
    • Stats export via statsd for aggregation (?)
  • Status portal (with content_by_lua_file and lustache)
• Multi-Factor Auth:
  • Implement base for 2FA...
  • Major 2FA types:
    • Authy
      • Stage: Researching & implementation
    • U2F
      • Stage: Researching

Contributing

Pull requests and issues are more than welcome! I need as much feedback on this as possible to continue improving the SSO.

To discuss code or anything else, you can find us on IRC at irc.maio.me in #dev.

Licensing

This project is licensed under the MIT License. You can view the full terms of the license in /LICENSE.txt.

lsso's Issues

0.4: ensure API requests are allowed.

This is something to keep in the mind for the future and partially take care of now.

The access token API call should be able to be toggled via a configuration switch for security measures.
The same goes for any future API calls that may expose access keys for protected resources.

0.4: U2F support

Exactly as it sounds -- I want to support U2F registration and auth in the typically lsso workflow.

Error messages slightly misleading...

On a bad username or password, the SSO should return msg_bad_credentials through the ?error call back to the auth portal, but returns msg_upstream_error.

0.4: "cumulative" scoping for new requests and upgrades

When creating a new session for a scoped location, ensure that we not only request a token for the location's specified scope, but also for the config.oauth_auth_scope to keep the number of session upgrades that need to happen at a minimum.

Example:

current_scope = none
location -> /auth/test/scope-testing [scope: unix-wheel]
<session creation>
new_current_scope = sso unix-wheel

During a session upgrade, we should make sure to compound current scopes to reduce the number of session upgrades.

Example:

current_scope = sso unix-wheel
location -> /auth/test/scope-testing [scope: container-manage]
<session is killed and recreated>
new_current_scope = sso unix-wheel container-manage

0.5: move to client credentials grant style OAuth flow.

From the way RFC 6749 reads, client credentials style grant is similar to resource owner password credentials grant, but provides more flexibility.

With the client credentials grant, the main differences are the lack of username and password in the authentication request, as they are provided as HTTP BASIC auth in the Authorization header.

POST /token HTTP/1.1
Host: auth.example.org
Authorization: Basic <base64-mime encoded payload>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=space separated scopes

In the case of pyled, authentication and authorization are taken care of in one step, so this request hits a single endpoint and is essentially finished. As for other OAuth systems, I am not sure.

0.4: add scoping to access tokens

Scoping needs to be added to the access token code so temporary tokens can be limited to a subsection of protected pages.

Now, tokens are created with the default config.oauth_auth_scope scope. Scoped access tokens should only be created if the requested scope is in a whitelist/not in a blacklist.

0.4: allow passing login username through request headers for proxy auth.

Around access.lua#L429, we should be able to add an ngx.req.set_header call to set a header (X-LSSO-Session -- but configurable?) so that the upstream service can use that as an auth method.

This is particularly useful for web applications supporting proxy auth, such as Grafana. This is a good step toward making lsso more powerful.

0.4: testing

There needs to be some way of testing various parts of the codebase.

Both functional and "production" tests need to be run. Maybe this warrants a small Docker-based build with nginx, Redis, etc with a Python test suite to make requests and hit pages?

Without HTTP Basic auth, things get a tad bit more difficult, but still manageable.