Getting started

Prerequisites

Java 11 or higher must be installed.

Start the application

The application comes as single-file-application and can be started from command-line with the following command (replace %VERSION% with the version of your downloaded artifact).

java -jar simple-oauth-server-%VERSION%.jar

After the application has been started it's accessible via http://localhost:8080. Check it with curl

curl -I -X GET http://localhost:8080

The output should be something like

HTTP/1.1 401
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
...

Initial Folder Structure

After the first start the application folder layout should look like

simple-oauth/
├── data/ (Database, Private & Public Keys for signing the JWT-token)
├── log/  (Server-Logs)
└── simple-oauth-server-VERSION.jar (App-Executable)

Initial Setup & Configuration

After the start the application has an empty database without any application or user registration. The configuration of the system is implemented by a simple REST interface that is protected by the server's OAuth mechanism itself, so the first step is to create an initial application-registration for the configuration API, so that you can use the OAuth Client-Credential-Flow to obtain an access token. With this access token you can access the REST-configuration API.

Create the initial API application

To create the initial application you have to send the OAuth server a request to get the client_id and the client_secret with the following command

curl -v -l -X POST http://localhost:8080/auth/firstStart/run -H "Content-Type: application/json" --data-raw "{"""initialAuthToken""" : """4xjKQ8537XRBeF26IH9WB1OC0CAoJsfQ"""}" 

The initialAuthToken's value is set to the default value. You can overwrite this setting with an argument.

In your response you'll see the client_id and the client_secret that can be used for obtaining an access token to access the Configuration API of the App.

{
   "client_id":"z9xFcvjA4lVmvWXzekcAzODqRhuqQ5z4",
   "client_secret":"0r7aLo7qFE1NAY4sdvGJjzlaAssDrUy8i2BSm74kDf0CLGnsHlEaYgtbykRYxiyv"
}

Save this two values. If you loose this values you won't be able to gain access to the simple-oauth-server Configuration API without access to the underlying database.

Testing the first OAuth Authentication Flow

Now you're ready to obtain your first access token via the Client-Credential Flow (for Details see Section 4.4 of the OAuth-Protocol-Spec). With the following command you can obtain an access-token

curl -v -l -X POST http://localhost:8080/auth/oauth/token -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "grant_type=client_credentials" --data-urlencode "client_id=z9xFcvjA4lVmvWXzekcAzODqRhuqQ5z4" --data-urlencode "client_secret=0r7aLo7qFE1NAY4sdvGJjzlaAssDrUy8i2BSm74kDf0CLGnsHlEaYgtbykRYxiyv" --data-urlencode "scope=data.superadmin"

Make sure to set the client_id and the client_secret to the values that were returned with the initial setup-call. The result is a response specified in Section 4.4.3.

{
    "access_token":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ6OX...",
    "token_type":"Bearer",
    "expires_in":604800
}

Congratulations. You have authenticated with OAuth. With this access-token you can now use the simple-oauth-server Configuration API to setup your Authentication & Authorization backend.

Getting a list of all registered applications.

For testing we want to list all applications that are currently registered. The call should return exact one application.

curl -v -l -X GET http://localhost:8080/auth/admin/data/applications -H "Authorization: Bearer eeyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ6OX..." -H "Content-Type: application/json"

The result should look like:

{
  "_embedded" : {
    "applications" : [ {
      "id" : 2,
      "name" : "OAuth Server CLI Configurator",
      "clientId" : "z9xFcvjA4lVmvWXzekcAzODqRhuqQ5z4",
      "loginUrls" : [ ],
      "logoutUrl" : null,
      "cssUrl" : null,
      "activated" : true,
      "applicationType" : "M2M",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/auth/admin/data/applications/2"
        },
        "application" : {
          "href" : "http://localhost:8080/auth/admin/data/applications/2"
        },
        "scopeList" : {
          "href" : "http://localhost:8080/auth/admin/data/applications/2/scopeList"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/auth/admin/data/applications"
    },
    "profile" : {
      "href" : "http://localhost:8080/auth/admin/data/profile/applications"
    },
    "search" : {
      "href" : "http://localhost:8080/auth/admin/data/applications/search"
    }
  }
}