Writing Java library to build OAuth 2.0 Authorization Server / OpenID Connect Identity Provider

inaba jun — Thu, 22 Dec 2022 14:31:54 +0000

AzIdP4J

I'm writing AzIdP4J that the library to build Authorization Server and Identity Provider in Java.
The article talk about what I think while developing.

inabajunmr/azidp4j: Library for Java OAuth 2.0 Authorization Server & OpenID Connect Identity Provider

The library works as the following example.

// Convert HTTP Request query parameters to Map
var authorizationRequestQueryParameterMap =
        Map.of(
                "scope", "openid item:read",
                "response_type", "code",
                "client_id", "xyz-client",
                "redirect_uri", "https://client.example.com/callback",
                "state", "abc",
                "nonce", "xyz");
var authorizationRequest =
        new AuthorizationRequest(
                "inabajun", // authenticated user subject. Application needs to implements user authentication. If no user is authenticated, specify null.
                Instant.now().getEpochSecond(),
                Set.of("openid", "item:read"), // User consented scopes. Application needs to implements user consent.
                authorizationRequestQueryParameterMap);

// Authorization Request
var response = azIdP.authorize(authzReq);

// Library returns what should do next so implements application's behavior.
switch (response.next) {
    case redirect -> {
        // Redirect to response.redirect.redirectTo
    }
    case additionalPage -> {
        // Implements additional process like login or consent or...
    }
    case errorPage -> {
        // Error happend but can't redirect to redirct_uri
    }
}

When you want Authorization server / Identity provider

When we want Authorization server / Identity provider, we can select the following patterns.

Develop them by yourself
Develop them with libraries
Use a service that works as an Authorization server / Identity provider in conjunction with your application
Using standalone Authorization server / Identity provider

In the case of scratch development, we need to write many sources. We need to understand the specifications. We need to continue learning about new specifications and trends...

I often feel to develop user experiences myself but delegating processes about protocols like OAuth 2.0 / OIDC to a library. So I'm developing the library to build OAuth 2.0 Authorization Server / OIDC Identity Provider in Java. (Because Spring Security OAuth was EOL already.)

Policies

I think the most important thing about libraries is the interface.
I decided on the following policies to consider interfaces.

Don't depend on a specific framework
Easy to issue Access token / ID token
Applications can implement user experiences by themselves
No datastore implementations

Don't depend on a specific framework

OAuth 2.0 / OpenID Connect depends on HTTP as a specification. So if a library can be used without any additional implementations, the library needs to accept HTTP requests directly.

But there are many Java web application frameworks and I want to implement a library that can be used for any framework.

So AzIdP4J has more abstract interfaces than accepting HTTP requests directly.

For example, token request / token response is expressed as following examples.

Spring based example implementation is like this.

@PostMapping(value = "token", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public ResponseEntity<Map> tokenEndpoint(@RequestParam MultiValueMap<String, Object> body) {

    // client authentication by the application...
    // convert HTTP request query parameters to Map
    var request = new TokenRequest(authenticatedClientId, body.toSingleValueMap();
    // Token Request
    var response =
            azIdP.issueToken(request);

    // convert AzIdP4J resposne to HTTP response
    return ResponseEntity.status(response.status).body(response.body);
}

On the other hand, AzIdP4J doesn't support functions within the protocol that be highly dependent on the framework. For example, I think many frameworks have functions to authenticate a client and authorize by bearer token so AzIdP4J doesn't support them.

Easy to issue Access token / ID token

I decided to make it easy to implement issuing each token by Authorization Code Flow. If supporting many functions makes interfaces complicated, AzIdP4J doesn't support them.

For example, if AzIdP4J supports the UserInfo endpoint, AzIdP4J needs to know Users but it makes interfaces complicated so I don't support it yet.

Applications can implement user experiences by themselves

Behavior after authorization request doesn't close in protocols. When the authorization request has prompt=login, the application needs to show a login page but how to provide authentication user experiences are out of the scope of these specifications. The application needs to provide the application-specific authentication flow. AzIdP4J wants not to affect user experiences like user authentication, consent, etc...

So AzIdP4J provides the following interface.

// authzReq has authenticated user subject but can expresses not authenticated.
var response = azIdP.authorize(authzReq);
// Library returns what should do next so implements application's behavior.
switch (response.next) {
    case redirect -> {
        // Redirect to response.redirect.redirectTo
    }
    case additionalPage -> {
        // Implements additional process like login or consent or...
    }
    case errorPage -> {
        // Error happend but can't redirect to redirct_uri
    }

Authorization Request Document

No datastore implementations

I like ory/fosite interfaces so AzIdP4J imitates them. AzIdP4J needs to manage tokens so it provides only interfaces and an Application needs to implement them.

Token Stores Configuration

Things not to support

When I implement protocols, I become to wish to implement any specifications but I decided on things that don't support to control my motivation.

I decided first milestones.

Make AzIdP4J work at least
Writing documents with concrete examples

For the milestone, I removed the following things at the first milestone.

Doesn't support all of the core specification
- For example, Request Object
- Doesn't support specifications that I don't understand concrete demands.

It's difficult what specifications should be supported.

Make AzIdP4J work at least

First of all, I implemented accepting authorization requests and issuing access tokens and ID tokens via the token endpoint. I often test OICD Conformance Test against my implementation while implementing. This made progress visible so It was good to continue my motivation. The conformance test revealed some specifications that I can't understand correctly also.

Writing documents with concrete examples

I understood some of the specifications through conformance tests, writing sources and so one. But I can't understand whether the library's interfaces are good or bad. I want feedback about the library so I wrote documents with concrete examples. I'll be glad if you provide feedback.

AzIdP4J Documentation

Development process

For continuous checking of the policy "Don't depend on a specific framework", I implemented 2 types of sample identity frameworks.

The approach helped my decision on interfaces. For example, when I considered whether the application with the library can implement client authentication or not, multiple implementations help my consideration.

The library development with client implementations is better than just with test cases. Cases that I can't discover from the latter sometimes appeared.

Conclusion

I'm writing AzIdP4J that the library to build Authorization Server and Identity Provider in Java.
The article talked about what I thought while developing.

inabajunmr/azidp4j: Library for Java OAuth 2.0 Authorization Server & OpenID Connect Identity Provider

The library works as the following example.

// convert HTTP Request query parameters to Map
var authorizationRequestQueryParameterMap =
        Map.of(
                "scope", "openid item:read",
                "response_type", "code",
                "client_id", "xyz-client",
                "redirect_uri", "https://client.example.com/callback",
                "state", "abc",
                "nonce", "xyz");
var authorizationRequest =
        new AuthorizationRequest(
                "inabajun", // authenticated user subject. Application needs to implements user authentication. If no user is authenticated, specify null.
                Instant.now().getEpochSecond(),
                Set.of("openid", "item:read"), // User consented scopes. Application needs to implements user consent.
                authorizationRequestQueryParameterMap);
var response = azIdP.authorize(authzReq);
// Library returns what should do next so implements application's behavior.
switch (response.next) {
    case redirect -> {
        // Redirect to response.redirect.redirectTo
    }
    case additionalPage -> {
        // Implements additional process like login or consent or...
    }
    case errorPage -> {
        // Error happend but can't redirect to redirct_uri
    }
}

I hope your feedbacks. Thank you.

The tool to find and edit any tool's config file

inaba jun — Fri, 19 Mar 2021 14:12:34 +0000

When I want to edit fish configuration file, I always google like "fish config" or "fish fishrc".

But I made tool to solve it.

anyconf

https://github.com/inabajunmr/anyconf

Behavior

Recommended system requirements

$ go version
go version go1.13.8 darwin/amd64
$ vim --version
VIM - Vi IMproved 8.1 (2018 May 18, compiled Jun  5 2020 21:30:37)
macOS version
$ sw_vers
ProductName:    Mac OS X
ProductVersion: 10.15.7
BuildVersion:   19H114

Install

go get github.com/inabajunmr/anyconf

Usage

anyconf command shows supported tools like the following example.

$ anyconf
? What's next key?  [Use arrows to move, enter to select, type to filter]
> fish
  screen
  git
  aws
  bash
  curl
  npm

And you can type and filter tools.

$ anyconf
? What's next key? g  [Use arrows to move, enter to select, type to filter]
> git
  wget

After selection, the configuration file open by vim. (vim is the default, you can change it via anyconf configuration.)

Support new tools via Pull Request

The mapping tools and configuration files are managed by the following file.

https://github.com/inabajunmr/anyconf/blob/main/static/configs.txt

anyconf ~/.anyconf/configs.txt
aws/config ~/.aws/config
aws/credentials ~/.aws/credentials
bash/bash_profile ~/.bash_profile
bash/bashrc ~/.bashrc
+NEWTOOL ~/.newtool.conf

You can send pull request if you want to apply NEWTOOL like this.
After merging it, anyconf support NEWTOOL.

Support new tools via Local Configuration

anyconf manages .anyconf/configs.txt and you can support your tool via the configuration.

If you put the following example to configuration, you can use NEWTOOL by anyconf.

NEWTOOL ~/.newtool.conf

The configuration file can be opened via anyconf.

Conclusion

I made anyconf to find and edit any tools configuration.

But it supports only a few tools that I use yet so If I receive Pull Request for other tools, I'll be glad. Thank you.

DEV Community: inaba jun

Writing Java library to build OAuth 2.0 Authorization Server / OpenID Connect Identity Provider

AzIdP4J

When you want Authorization server / Identity provider

Policies

Don't depend on a specific framework

Easy to issue Access token / ID token

Applications can implement user experiences by themselves

No datastore implementations

Things not to support

Make AzIdP4J work at least

Writing documents with concrete examples

Development process

Conclusion

The tool to find and edit any tool's config file

anyconf

Behavior

Recommended system requirements

Install

Usage

Support new tools via Pull Request

Support new tools via Local Configuration

Conclusion