Getting Started

Introduction

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

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.

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.

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.

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.

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!

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 few commands as shown below.

Please check the documents at java-oauth-server for details.

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

Please check the documents at spring-oauth-server for details.

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

Please check the documents at csharp-oauth-server for details.

$ git clone https://github.com/authlete/csharp-oauth-server
$ cd csharp-oauth-server/AuthorizationServer
$ vi authlete.properties
$ dotnet run

Please check the documents at authlete-php-laravel for details.

$ laravel new authorization-server
$ cd authorization-server
$ composer require authlete/authlete-laravel
$ php artisan authlete:authorization-server
$ vi config/authlete.php

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.

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 (/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.