borderpatrol: A Scala repository from blakegilmore

Border Patrol is a type-safe, immutable, functional Scala library built on top of Finagle that provides modular components useful for session management and authentication. This library is used at Lookout for single sign on with support for multiple authentication backends.

The original version (as a server) can be found here (nginx+lua): ngx_borderpatrol

Badges

Modules

Border Patrol uses a multi-project structure and contains the following modules:

core - the core classes/functions
example - the demo app showing sessions and authentication for multiple services
auth - different authentication plugins for core auth
security - different security plugins, e.g. CSRF protection
server - a server composing these modules that can be configured

Installation

Every Border Patrol module is published at Bintray and SNAPSHOT builds are published to JFrog.

stable release (not officially available yet):

libraryDependencies ++= Seq(
  "com.lookout.borderpatrol" %% "[borderpatrol-module]" % "0.1.0"
)

SNAPSHOT release:

libraryDependencies ++= Seq(
  "com.lookout.borderpatrol" %% "[borderpatrol-module]" % "0.1.0-SNAPSHOT" changing()
)

Building Border Patrol

To build Border Patrol you should have sbt installed (prefer v0.13.8+). Run sbt, and then use any of the following commands:

compile: compile the code
project [project]: to switch projects, e.g. "project example"
console: launch a REPL
test: run the tests
unidoc: generate the documentation
scalastyle: run the style-checker on the code
validate: run tests, style-checker, and doc generation

Configuration

secretStore: Secret Store. It can be configured using type as InMemoryStore or ConsulSecretStore.

"secretStore" : {
  "type" : "InMemorySecretStore",
}
"secretStore" : {
  "type" : "ConsulSecretStore",
  "hosts" : "localhost:1234"
}

sessionStore: Session Store. It can be configured using type as InMemorySecretStore or MemcachedStore.

"sessionStore" : {
  "type" : "InMemoryStore",
}
"sessionStore" : {
  "type" : "MemcachedStore",
  "hosts" : "localhost:123"
}

accessManagers: A list of ACCESS Managers. Access endpoints authorize access to protected endpoints.
identityManagers: A list of IDENTITY Managers. Identity managers perform authentication and provisioning
Manager: A
- hosts: A list of upstream URLs (Format: [<http[s]>://<host>:[port]]+)
- path: A path serviced by the upstream manager (i.e. Keymaster IDP endpoint or Keymaster AccesIssuer endpoint)
- name: A unique name that identifies this Manager
loginManagers: A list of LOGIN Managers
loginManager: It defines a
- hosts: A list of upstream URLs (Format: [<http[s]>://<host>:[port]]+)
- path: A path serviced by the upstream host (i.e. login provider host). It typically services the un-authenticated web services
- name: unique name that identifies this Login Manager
- identityManager: Identity manager name used by this Login Manager
- accessManager: Access Issuer used by this Login Manager
- loginPath: The path at which login form posts the login response
serviceIdentifiers: A list of protected service endpoints
serviceIdentifier: A protected service endpoint. The combination of subdomain and path uniqully identifies service.
- hosts: A list of upstream URLs (Format: [<http[s]>://<host>:[port]]+)
- name: A unique name that identifies this Service Identifier
- loginManager: Login Manager used by this Service Identifier
- path: A path serviced by the protected endpoint
- subdomain: A subdomain of the protected endpoint

Running the example

$ sbt
> project example
> run

Documentation

Scaladoc is available at http://lookout.github.io/borderpatrol/docs
Markdown documents are available here. The code examples are fully runnable in a Scala REPL verified with tut. Use sbt tut to compile example code in markdown (docs/src/main/tut) which outputs to target/scala-N.NN/tut

Contributing

We would love to make this better, so please help us!

Submit a PR including an issue label "easy"
Write ScalaDoc comments
Write tutorials and examples
Improve tests
Help with code review
Give it a star
Join us on IRC #borderpatrol on Freenode

License

We use the MIT License License

blakegilmore/borderpatrol