Silhouette Documentation Release 2.0-RC1 Christian Kaps February 16, 2015 Contents 1 Basics 3 1.1 Features..................................................3 1.2 Examples.................................................4 1.3 Releases.................................................4 1.4 Contribute................................................6 1.5 Help...................................................8 2 How it works 9 2.1 Environment...............................................9 2.2 Actions..................................................9 2.3 Identity.................................................. 15 2.4 Authenticator............................................... 17 2.5 Providers................................................. 21 2.6 Error handling.............................................. 26 2.7 Caching.................................................. 26 2.8 Events.................................................. 27 2.9 Logging.................................................. 28 2.10 Testing.................................................. 29 3 Configuration 35 3.1 Configuration............................................... 35 i ii Silhouette Documentation, Release 2.0-RC1 Silhouette is an authentication library for Play Framework applications that supports several authentication methods, including OAuth1, OAuth2, OpenID, Credentials, Basic Authentication or custom authentication schemes. It can be integrated as is, or used as a building block and customized to meet specific application requirements, thanks to its loosely coupled design. The project is named after the fictional crime fighter character Silhouette, from the Watchmen graphic novel and movie. Contents 1 Silhouette Documentation, Release 2.0-RC1 2 Contents CHAPTER 1 Basics 1.1 Features Easy to integrate Silhouette comes either with an Activator template for traditional web pages or an Activator template for single-page applications that gives you a complete sample application which is 100% customizable. Simply select the template play-silhouette-seed or play-silhouette-angular-seed in your Activator UI. It has never been easier to start a new Silhouette application. For other examples, please visit the Examples section in the Documentation. Authentication support Out of the box support for leading social services such as Twitter, Facebook, Google, LinkedIn and GitHub. Silhouette also includes a credentials and basic authentication provider that supports local login functionality. Client agnostic Silhouette comes with a set of stateless as well as stateful authenticator implementations which allows an application to handle a wide range of different clients like traditional web browsers as also native(desktop, mobile, ...) apps. Asynchronous, non-blocking operations We follow the Reactive Manifesto. This means that all requests and web service calls are asynchronous, non-blocking operations. For the event handling part of Silhouette we use Akka’s Event Bus implementation. Lastly, all persistence interfaces are defined to return Scala Futures. Very customizable, extendable and testable From the ground up Silhouette was designed to be as customizable, extendable and testable as possible. All compo- nents can be enhanced via inheritance or replaced based on their traits, thanks to its loosely coupled design. Internationalization support Silhouette makes it very easy to internationalize your application by making the Play Framework’s Request and Lang available where they are needed. Well tested Silhouette is a security component which protects your users from being compromised by attackers. Therefore we aim for complete code coverage with unit and integration tests. Follows the OWASP Authentication Cheat Sheet Silhouette implements and promotes best practices such as described by the OWASP Authentication Cheat Sheet like Password Strength Controls, SSL Client Authentication or use of authentication protocols that require no password. 3 Silhouette Documentation, Release 2.0-RC1 1.2 Examples This page lists some examples which show how Silhouette can be used in various kinds of projects. Silhouette Seed Template The Silhouette Seed project is an Activator template which shows how Silhouette can be used in a Play Framework application. It’s a starting point which can be extended to fit your needs. Link Silhouette Angular Seed Template The Silhouette Angular Seed project is an Activator template which shows how Silhouette can be used to create a SPA with AngularJS and Play. It’s a starting point which can be extended to fit your needs. Link Silhouette Slick Seed Template A fork of the Silhouette Seed project which uses Slick as database access library. Link Silhouette Cake Seed Template Seed project for Play Framework with Silhouette, using the Cake Pattern for dependency injection. Link Silhouette Rest Seed Seed project for Play Framework with Silhouette, exposing a rest api for signup and signin. Link Play 2.3 Multidomain Auth Project for Play Framework with Silhouette, using a not strict implementation of Thin Cake Pattern and showing how to add an authentication and authorizaton layer. The project is split in two main subprojects: a public web page that uses a complete authentication layer (including sign up with email confirmation and reset passwords), and an administration web page that uses also a simple authorization layer based on roles. Link 1.3 Releases 1.3.1 Release Versions Silhouette 2.0 This is the first release candidate of the next stable 2.0 release and it’s available for Scala 2.10 / 2.11 and Play 2.3. 4 Chapter 1. Basics Silhouette Documentation, Release 2.0-RC1 Documentation • HTML • HTML (Zip) • PDF • EPUB • API Installation To install this version add the following dependency to your build.sbt file. libraryDependencies ++= Seq( "com.mohiva"%% "play-silhouette"% "2.0-RC1" ) Silhouette 1.0 This is the previous stable release and it’s available for Scala 2.10 / 2.11 and Play 2.3. Documentation • HTML • HTML (Zip) • PDF • EPUB • API Installation To install this version add the following dependency to your build.sbt file. libraryDependencies ++= Seq( "com.mohiva"%% "play-silhouette"% "1.0" ) 1.3.2 Old Versions Silhouette 0.9 Available for Scala 2.10 and Play 2.2. 1.3. Releases 5 Silhouette Documentation, Release 2.0-RC1 Documentation • HTML • HTML (Zip) • PDF • EPUB • API Installation To install this version add the following dependency to your build.sbt file. libraryDependencies ++= Seq( "com.mohiva"%% "play-silhouette"% "0.9" ) 1.3.3 Notes The master branch contains the current development version. It should be working and passing all tests at any time, but it’s unstable and represents a work in progress. Released versions are indicated by tags. Release numbers will follow Semantic Versioning. 1.4 Contribute 1.4.1 How to contribute Silhouette is an open source project. Contributions are appreciated. See the current list of contributors and join them! Some ways in which you can contribute are: reporting errors, improving documentation, adding examples, adding support for more services, fixing bugs, suggesting new features, adding test cases, translating messages, and whatever else you can think of that may be helpful. If in doubt, just ask. 1.4.2 The project structure Silhouette is dived into the api and impl packages. The definition of these both packages is as follow: API Package The collection of traits and utility classes that form the stable API of Silhouette. Impl Package The reference implementation of Silhouette. 6 Chapter 1. Basics Silhouette Documentation, Release 2.0-RC1 Test Package Contains helper classes and objects to easily test an application based on Silhouette. 1.4.3 Development workflow Development is coordinated via GitHub. Ideas for improvements are discussed using issues. For a more streamlined experience for all people involved, we encourage contributors to follow the practices described at GitHub workflow for submitting pull requests. Scala source code should follow the conventions documented in the Scala Style Guide. Additionally, acronyms should be capitalized. To have your code automatically reformatted, run this command before committing your changes: scripts/reformat Important: After submitting your pull request, please watch the result of the automated Travis CI build and correct any reported errors or inconsistencies. 1.4.4 Help to improve the documentation Every software project is only as good as its documentation. So we do our best to cover all the code with a good structured, meaningful and up-to-date documentation. But like in the most open source projects, time is a precious commodity. We appreciate all help to improve the documentation. Edit on GitHub For small typo changes the documentation can be edited directly on GitHub. This is very easy by following the “Edit on GitHub” button at the top of th page. After you have made your changes you can commit it with a meaningful commit message. It will then automatically create a new pull request with your proposed changes. Edit it locally The documentation is written in RST which can be rendered by Sphinx into many output formats like HTML, PDF and many more. To render the documentation into static HTML which looks the same as this documentation on “Read the docs”, you must install Sphinx and the “Read the Docs” theme. pip install sphinx sphinx_rtd_theme Note: Python must be installed on your system. Please consult the documentation of your OS on how to do it. If you have edited the documentation files, you can create the static HTML files by executing the following