Getting Started

Getting Started

This document is a quick guide for those who want to run an OAuth 2.0 authorization server using Authlete.

  1. Sign Up
  2. Try OAuth 2.0 Flow
  3. Authorization Server Implementation
  4. Next Steps

1. Sign Up

To begin with, please sign up. After account registration, you will receive an email that contains an instruction in how to try OAuth 2.0 flow.

2. Try OAuth 2.0 Flow

You can try OAuth 2.0 flow right after account registration. This is because your first OAuth 2.0 authorization server and the first client application of the server have already been created and running.


Technical Note

You can find the API key of your first service and the client ID of your first client application in the email. Also, you can see them in Service Owner Console and Developer Console, respectively. The URLs of the consoles are as follows.


Service Owner Console https://so.authlete.com/
Developer Console https://cd.authlete.com/service-api-key/

You can login Developer Console using the API credentials of the service. Also, you can let other (third-party) developers use Developer Console of your service by implementing a developer authentication callback endpoint to authenticate the developers. Read "Developer Authentication Callback" for details.


2.1. Make An Authorization Request

Click "Authorization Endpoint" button in the email you received after account registration. It will open an authorization page in your web browser.


Technical Note

Clicking "Authorization Endpoint" button in the email will make an authorization request to the default authorization endpoint implementation provided by Authlete using Implicit Flow. It is equivalent to the URL shown below.


https://api.authlete.com/api/auth/authorization/direct/service-api-key?response_type=token&client_id=client-id

2.2. Input Credentials

Input the API key and the API secret of your first service into the login form in the authorization page. You can see the API credentials by clicking "Service Owner Console" button in the email.


Technical Note

"Service Owner Console" button in the email is a link to https://so.authlete.com/services/service-api-key, which opens Service Details page of the service.


As a special behavior, the login form in the authorization page displayed by the default authorization endpoint implementation provided by Authlete accepts the pair of API key & API secret of the corresponding service as if it were a valid pair of ID & password of an end-user. If you want to let your end-users use the default authorization endpoint implementation, you need to implement an authentication callback endpoint to authenticate the end-users. Read "Authentication Callback". for details.


2.3. Authorize The Request

Click "Authorize" button in the authorization page, and your browser will be redirected to the redirection endpoint. You can find an access token in the fragment part of the destination URL like below. (The line breaks are just for display purpose.)

https://api.authlete.com/api/mock/redirection/service-api-key
  #access_token=wAwuQSkePLk2D6rgGnuXQAtJHmFitVKoXIIPAY-3rzw
  &token_type=Bearer&expires_in=86400&scope=

Congratulations! You confirmed your OAuth 2.0 authorization server is working!


3. Authorization Server Implementation

In the previous chapter, you used the default implementation of authorization endpoint, but you have another option. You can implement your own authorization server using Authlete Web APIs.

java-oauth-server is an open-source authorization server written using Authlete Web APIs. It is the reference implementation in Java and a good starting point for your own authorization server implementation.

Because, of course, the reference implementation uses Authlete as its backend, you don't have to set up a database server that stores authorization data (e.g. as access tokens), settings of the authorization server itself, and settings of client applications. Therefore, all you have to type to download and start the authorization server are only 4 commands as shown below.


$ git clone https://github.com/authlete/java-oauth-server.git
$ cd java-oauth-server
$ vi authlete.properties
$ mvn jetty:run

If you implement your own authorization server using Authlete Web APIs, you don't have to implement an authentication callback endpoint, but instead you are required to customize some source files related to end-user authentication. Please read the documents at https://github.com/authlete/java-oauth-server for details.


Next Steps

Service Owner Console

Service Owner Console is a Web console for you to manage services. Read "Service Owner Console" for details.

Developer Console

Developer Console is a Web console for developer to manage client applications. Read "Developer Console" for details.

Protected Resource

The main purpose to implement OAuth 2.0 is to protect Web APIs by access tokens. Read "Protected Resource" about how to do it.

Authentication Callback

If you use the default implementation of authorization endpoint (/api/auth/authorization/direct/service-api-key) provided by Authlete, and if you want to authenticate your end-users at the authorization page by their ID and password, you need to implement an authentication callback endpoint to authenticate the end-users. Read "Authentication Callback" for details.

Note that you don't have to implement an authentication callback endpoint if you implement your own authorization server using Authlete Web APIs. java-oauth-server is an open-source authorization server written using Authlete Web APIs and it is a good starting point for your own authorization server implementation.

Developer Authentication Callback

If you want to let other (third-party) developers use Developer Console, you need to implement a developer authentication callback endpoint to authenticate the developers. Read "Developer Authentication Callback" for details.