Updated README.md and started HackingOnKeycloak guide

This commit is contained in:
Stian Thorgersen 2015-04-14 09:27:51 +02:00
parent 8ebac35706
commit c0f6b6d8d0
2 changed files with 58 additions and 34 deletions

View file

@ -1,39 +1,54 @@
keycloak
Keycloak
========
Please visit [http://keycloak.org](http://keycloak.org) for more information on Keycloak including how to download, documentation,
and video tutorials.
Keycloak is an SSO Service for web apps and REST services. For more information visit [http://keycloak.org](http://keycloak.org).
Keycloak is an SSO Service for web apps and REST services.
It can be used for social applications as well as enterprise applications. It is based on OpenID Connect with support for SAML 2.0 as well.
Here's some of the features:
* SSO and Single Log Out for browser applications
* Social Broker. Enable Google, Facebook, Yahoo, Twitter, GitHub, LinkedIn social login with no code required.
* Optional LDAP/Active Directory integration
* Optional User Registration
* Password and TOTP support (via Google Authenticator or FreeOTP). Client cert auth coming soon.
* User session management from both admin and user perspective
* Customizable themes for user facing pages: login, grant pages, account management, emails, and admin console all customizable!
* OAuth Bearer token auth for REST Services
* Integrated Browser App to REST Service token propagation
* Admin REST API
* OAuth 2.0 Grant requests
* CORS Support
* CORS Web Origin management and validation
* Completely centrally managed user and role mapping metadata. Minimal configuration at the application side
* Admin Console for managing users, roles, role mappings, applications, user sessions, allowed CORS web origins, and OAuth clients.
* Deployable as a WAR, appliance, or an Openshift cloud service (SaaS).
* Supports JBoss AS7, EAP 6.x, Wildfly, Tomcat, and Jetty applications. Plans to support Node.js, RAILS, GRAILS, and other non-Java applications.
* Javascript/HTML 5 adapter for pure Javascript apps
* Session management from admin console
* Revocation policies
* Password policies
* OpenID Connect Support
* SAML Support
* Token claim and SAML assertion mappings, role name mappings, etc. Ability to configure exactly what information you want in your tokens and SAML documents
* IDP brokering or chaining. You can set up Keycloak to be a child IDP to another SAML or OIDC IDP.
* Kerberos bridging. Logged in Kerberos users can access Keycloak SAML or OIDC applications via our Kerberos bridge.
Building
--------
Please visit [http://keycloak.org](http://keycloak.org) for more information on Keycloak including how to download, documentation,
and video tutorials.
Ensure you have JDK 7 (or newer) and Maven 3.2.1 (or newer) installed
java -version
mvn -version
To build Keycloak run:
mvn install
This will build all modules and run the testsuite.
To build the distribution run:
mvn install -Pdistribution
Once completed you will find distribution archives in `distribution`.
Starting Keycloak
-----------------
To start Keycloak during development first build as specficied above, then run:
mvn -f testsuite/integration/pom.xml exec:java -Pkeycloak-server
To start Keycloak from the appliance distribution first build the distribution it as specified above, then run:
tar xfz distribution/appliance-dist/target/keycloak-appliance-dist-all-<VERSION>.tar.gz
cd keycloak-appliance-dist-all-<VERSION>/keycloak
bin/standalone.sh
To stop the server press `Ctrl + C`.
Contributing
------------
* [Hacking On Keycloak](https://github.com/keycloak/keycloak/blob/master/misc/HackingOnKeycloak.md)
License
-------
* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)

View file

@ -0,0 +1,9 @@
So you are a developer who wants to start hacking on Keycloak? Here is the short list of things you need to know:
1. You'll get a good feel for the Keycloak server and adapters if you try out the demo apps. Instructions for setting that up are at [https://github.com/keycloak/keycloak/tree/master/examples/demo-template](https://github.com/keycloak/keycloak/tree/master/examples/demo-template).
2. The build has three Maven roots. There is the obvious one at the root of the project, which builds all the core stuff. The second one is in /distribution. That assembles the appliance, the adapters, and a few other things. The third is in /docbook. That one creates the documentation.
3. We track everything in [Jira](https://issues.jboss.org/browse/KEYCLOAK). Make sure you create an issue for any changes you propose.
4. We work with GitHub in much the same way as the WildFly project. You can look at [Hacking on Wildfly](https://developer.jboss.org/wiki/HackingOnWildFly) to get some tips on that.
5. If you have other questions, ask on the [Developer Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev). We don't use IRC much, so that's the best place to ask.
6. For a more productive development, please consider using org.keycloak.testutils.KeycloakServer. This class is a Java Application that starts a KC server without requiring you to deploy a WAR file in a specific container.