title: Building a Java OAuth2.0 authorization server with Keycloak
body: <blockquote>
    <h1>TL;DR</h1>
    
    <ul>
    <li>Objective: Java authorization server:
    
    <ul>
    <li>OAuth2.0 authorization code grant flow with fine-grained permissions (not a mere SSO server)</li>
    <li>User management and authentication: custom database</li>
    <li>Client management and authentication: Keycloak</li>
    </ul></li>
    <li>Questions: <strong>What are the best practices for implementing a Java authorization server with applicative permissions handling backed on Keycloak?</strong>
    
    <ul>
    <li>What Keycloak adapter/API should I use in my development?</li>
    <li>How should the users be managed/appear in Keycloak if they are to appear at all?</li>
    </ul></li>
    </ul>
  </blockquote>
  
  <h1>Forewarning</h1>
  
  <p>I am quite the beginner with Keycloak and, though I think I understand the main principles, it seems to be a rich tool and I fear I may still be mistaken about some aspects of the best ways to use it. Please do not hesitate to correct me.</p>
  
  <h1>Context</h1>
  
  <p>We are looking at implementing an API requiring our users (henceforth "users") to grant permissions to third party applications (henceforth "clients").</p>
  
  <p>Our users are stored in a custom existing database-based user management system. As for our clients, we are thinking of using <a href="https://www.keycloak.org" rel="noreferrer">Keycloak</a>.</p>
  
  <p>The users consent will be given using an OAuth2.0 Authorization code grant flow. They will log in, specify which permissions they grant and which they deny, and the client then retrieves the access token it will use to access the API.</p>
  
  <p>It is my understanding that Keycloak can handle the authorization token but it should not know anything applicative, which our permissions are. As a consequence, I thought of building a custom authorization server which will use Keycloak for all identity/authentication problems but will handle the applicative permissions by itself.</p>
  
  <p>Then, we will use Keycloak for client authentication and authorization code/access token management, and an applicative part will check the permissions.</p>
  
  <h1>Problem</h1>
  
  <p>Besides my first experimenting, I've been roaming the Internet for a week now and I'm surprised as I thought this would be quite a standard case. Yet I found next-to-nothing, so maybe I'm not searching correctly.</p>
  
  <p>I've found many Spring/Spring Boot tutorials<sup>1</sup> on how to make a "simple authorization server". Those are mainly SSO servers though, and few do manage permissions, with the exception of those mentioned in <a href="https://stackoverflow.com/a/17004631/1734119">this SO answer</a><sup>2</sup>. That I think we can deal with.</p>
  
  <p>The real problem I have, and that none of the tutorials I have found are treating, is the following:</p>
  
  <h2>How do I integrate Keycloak in this authorization server?</h2>
  
  <p>I've been having a look at the <a href="http://www.keycloak.org/docs/3.4/securing_apps/index.html#java-adapters" rel="noreferrer">available Java Adapters</a>. They look OK when it comes to authenticate but I did not see hints about how to manage clients from a custom authorization server (ie administer the realm).</p>
  
  <p>I therefore <strong>suppose I should use the admin API</strong>. Am I correct and is it good practice? I saw no adapter for that, so I suppose I should then use the REST API.</p>
  
  <p>I also wonder <strong>how we should integrate our users in design?</strong> Should they be duplicated inside Keycloak? In this case, should we use Keycloak's admin API to push the data from the authorization server or is there a better way?</p>
  
  <p>Finally, am I missing some other obvious point?</p>
  
  <p>Sorry for the long message and the many questions, but it all boils down to one question in the end:</p>
  
  <h2>What are the best practices when building an authorization server using Keycloak as a backbone?</h2>
  
  <hr>
  
  <p><sub>1. Some examples: 
  <a href="https://spring.io/guides/tutorials/spring-boot-oauth2/" rel="noreferrer">Spring Boot OAuth2 tutorial</a> -
  <a href="https://techeye7.wordpress.com/2017/11/24/oauth-2-authorization-code-grant-type-example/" rel="noreferrer">A blog post</a> -
  <a href="http://www.hascode.com/2016/03/setting-up-an-oauth2-authorization-server-and-resource-provider-with-spring-boot/" rel="noreferrer">Another blog post</a></sub></p>
  
  <p><sub>2. I've mainly focused on <a href="https://github.com/spring-projects/spring-security-oauth" rel="noreferrer">the sample app provided by Spring Security OAuth</a></sub></p>