oidc-auth-client

oidc-auth-client is a Java and Spring Boot library for retrieving and caching access tokens from an OpenID Connect (OIDC) provider. It simplifies authentication by handling token acquisition, caching, and renewal, making secure API calls easier.

Features

• Retrieve access tokens from an OIDC provider
• Automatically cache and refresh tokens
• Simple integration with Spring Boot
• Includes AccessTokenClient for Auth0

Installation

Add the dependency to your project:

implementation("org.entur.auth.client:oidc-client-spring-boot:${oidcClientVersion}")
implementation("com.auth0:auth0:${auth0JavaVersion}")

Important

If your project don't have Spring Auto Configure enabled you need to import OidcAuthClientAutoConfiguration manually.

Alternatively if Spring Boot integration is not needed:

implementation("org.entur.auth.client:oidc-client:${oidcClientVersion}")
implementation("com.auth0:auth0:${auth0JavaVersion}")

Configuration

In Application.yaml, oidc-auth can be configured for one or more oidc clients.

Single client

Syntax for configuration of a single client of AccessTokenFactory. For single client configurations, the name will always be "auth0".

entur:
  client:
    shouldRefreshThreshold: 120 # Time (seconds) before proactive token refresh. Default=120.
    mustRefreshThreshold: 60    # Minimum time (seconds) before forced token refresh. Default=60.
    minThrottleTime: 1          # Throttle time will increase exponentially from min to max throttle time. Default=1.
    maxThrottleTime: 600        # Default 600 (10 minutes).
    auth0:
      clientId: <clientId>
      secret: <secret>
      domain: <your.domain>
      audience: <your audience>

Multiple clients

Syntax for configuration multiple clients of AccessTokenFactory. The example below will set up clients multiple with the names "myFirstClient" and "mySecondClient".

entur:
  clients:
    shouldRefreshThreshold: 120 # Time (seconds) before proactive token refresh. Default=120.
    mustRefreshThreshold: 60    # Minimum time (seconds) before forced token refresh. Default=60.
    minThrottleTime: 1          # Throttle time will increase exponentially from min to max throttle time. Default=1.
    maxThrottleTime: 600        # Default 600 (10 minutes).
    auth0:
      myFirstClient:
        clientId: <clientId>
        secret: <secret>
        domain: <your.domain>
        audience: <your audience>
      mySecondClient:
        clientId: <clientId>
        secret: <secret>
        domain: <your.domain>
        audience: <your audience>
        shouldRefreshThreshold: 60  # Override default for this client
        mustRefreshThreshold: 30    # Override default for this client
        minThrottleTime: 5          # Override default for this client
        maxThrottleTime: 300        # Override default for this client

Usage

Spring Boot

In a java Spring Boot application AccessTokenFactory can be auto wired:

@Autowired
@Qualifier("myFirstClient") // Use Qualifier if more when one client are configured. 
private AccessTokenFactory accessTokenFactory;

A valid access token can then be retrieved from accessTokenFactory by doing the following:

var accessToken = accessTokenFactory.getAccessToken();

To create a RestTemplate with a bearer token, annotations can be used:

public class AuthData {
    @AccessToken("auth0")
    private RestTemplate restTemplate;
}

Manually

An accessTokenFactory can also be configured directly outside of Spring Boot in-code:

var accessTokenFactory = new AccessTokenFactoryBuilder()
        .withDomain(oidcAuthProperties.getDomain())
        .withClientSecret(oidcAuthProperties.getSecret())
        .withClientId(oidcAuthProperties.getClientId())
        .withAudience(oidcAuthProperties.getAudience())
        .withMustRefreshThreshold(oidcAuthProperties.getMustRefreshThreshold())
        .withShouldRefreshThreshold(oidcAuthProperties.getShouldRefreshThreshold())
        .withMinThrottleTime(oidcAuthProperties.getMinThrottleTime())
        .withMaxThrottleTime(oidcAuthProperties.getMaxThrottleTime())
        .buildAuth0();

var accessToken = accessTokenFactory.getAccessToken();

Testing

The AccessTokenFactory bean can be mocked as a normal bean (for the call getAccessToken()).

@MockitoBean
private AccessTokenFactory accessTokenFactory;

and then mock using

when(accessTokenFactory.getAccessToken()).thenReturn("Bearer ABC");

The starter will detect whether an existing AccessTokenFactory exists (in the above case, the mock). See example.

Development

Clone the repository:

git clone https://github.com/entur/oidc-auth-client.git
cd oidc-auth-client

Build with Gradle:

./gradlew build

Run tests:

./gradlew test

Contributing

Contributions are welcome! See CONTRIBUTING for details.

License

This project is licensed under the EUPL-1.2 license. See LICENSE for details.