java connect with_java-spring-oidc-example

Java Spring example

This example covers how to implement and configure a Java Spring project to work with Onegini's OpenID Connect Provider (OP). The example is based on the

project spring-google-openidconnect.

Clone and configure your IDE

To get the example up and running, first you'll need to clone it:

git clone https://github.com/Onegini/java-spring-oidc-example.git

IntelliJ

Go to File->Open and open the file java-spring-oidc-example/pom.xml, open it as a project.

The class com.onegini.oidc.Application should automatically be found and set up a run configuration for you so you can run it within IntelliJ.

Onegini Configuration

You'll need to properly setup your client using the Onegini Admin panel before you can begin testing.

Refer to the OpenID Connect documentation.

The Web client must support the following scopes:

openid

profile

The Onegini Token Server only redirects to preconfigured endpoints after login or logout. You must configure the following endpoints in the Onegini Token Server:

Redirect URL: http://localhost:8080/login

Post Logout Redirect URL: http://localhost:8080/signout-callback-oidc

Configuring ID Token Encryption

The Onegini Token Server supports encryption of the ID token to provide confidentiality of the claims. It can be configured by providing a JWKS endpoint and

choosing an encryption method in OpenID Connect configuration:

Encryption method: select one of encryption method that will be used to encrypt the ID Token.

JWKS URI: An endpoint that returns a list of public keys for encryption purposes. In this example it is exposed at

http://localhost:8080/.well-known/jwks.json. These keys typically would be stored in your database and would not change frequently. This example generates

them each time the application is started.

Set up the application configuration

Modify application.properties in /src/main/resources or use one of the mechanisms Spring Boot supports to override property values.

The following properties must be set:

onegini.oidc.clientId: the client identifier of the Web client that supports OpenID Connect

onegini.oidc.clientSecret: the client secret of the Web client that supports OpenID Connect

onegini.oidc.issuer: the base URL of the Token Server instance

Optional properties:

onegini.oidc.idTokenEncryptionEnabled: boolean for enabling ID token encryption. This should match the server side configuration

Example configuration

onegini.oidc.clientId=openid-client

onegini.oidc.clientSecret=secret

onegini.oidc.issuer=http://localhost:7878/oauth

onegini.oidc.idTokenEncryptionEnabled=true

Run and test

Run the example via the Run configuration in IntelliJ or via the command line: mvn spring-boot:run. The Token Server needs to be accessible to start this

application since it connects to the discovery endpoint during start up.

You should see a page with a link to a secured resource. When you click the link you wil be redirected to authenticate. If everything goes well, you will be

returned to a page where you see user information and the claims from the ID token. The user identifier is the value of the "sub" claim in the ID token.

How it works

OAuth2Client

OAuth2Client.java configures the OAuth flow for Spring Security. It uses discovery

to find the endpoints used by the OAuth flow. By default the scopes "openid" and "profile" are requested.

OpenIdConnectAuthenticationFilter

OpenIdConnectAuthenticationFilter.java is the filter used during

authentication. It obtains the ID token and creates the principal using some of the data.

Depending on the scope and configuration used in your environment, the user data returned in the ID token will differ. Adjust the

OpenIDConnectAuthenticationFilter class accordingly to match the correct fields.

In this example we use the sub and the name value, but you can use any value configured for your environment.

OpenIdTokenValidationWrapper

OpenIdTokenValidationWrapper.java validates the ID token. It validates

its signature against the keys that are returned by the JWKS endpoint of the OP. It verifies that the claims are from the issuer, intended for the correct

audience and that they have not expired.

UserInfo

The UserInfo.java is a POJO for user information. It is used as user principal in Spring

Security.

TokenDetails

The TokenDetails.java is a POJO for additional details about the token used during

authentication. In this project it contains the claims of the JWT.

Security configuration

In SecurityConfiguration.java we configure the Spring Security filters used

to authenticate the user and authorize the controllers of our application.

SampleSecuredController

The SampleSecuredController.java has a protected endpoint /secured. It populates

the modelMap for the template that shows the user information, ID token and the claims.

LogoutController

The LogoutController.java contains the logic to end the session. The user first comes to

the /logout endpoint. If the user was logged in via an ID token, they are redirected to the end session endpoint of the OP. The OP ends the session of the

user and redirects it back to http://localhost:8080/signout-callback-oidc. Then the user is logged out in Spring Security and redirected to the home page.

Encryption/Decryption

JweWellKnownJwksController

The JweWellKnownJwksController.java is responsible for returning the JWKS list (for encryption

purposes). This is an example implementation defined by the OpenID Connect Encryption spec.

This example uses the ECDH_ES algorithm by default. You can swap to another asymmetric algorithm such as RSA_OAEP_256 using the

ASYMMETRIC_ENCRYPTION_ALGORITHM variable. The MAX_AGE variable defined in this class defines how long the Token Server will cache the response.

This should align with your key rotation strategy. It also validates that the key's encryption algorithm is supported by checking the supported algorithms

exposed by the OpenID Provider Metadata This example generates keys every time

the application is started and stores them in memory. In a production situation, keys should be persisted in some way and proper key rotation followed. See

JSON Web Key (JWK) RFC-7517 for more information. This controller is only exposed when the property

onegini.oidc.idTokenEncryptionEnabled is set to true. If your client is not configured for encryption, there is no need for this controller.

JweKeyGenerator

The JweKeyGenerator.java is responsible for key generation. It shows how to generate the RSA

and EC keys. This could be used to help you generate keys to persist elsewhere.

JwkSetProvider

The JwkSetProvider.java has a storage role for caching the encryption keys. In a production

environment it should be modified to grab the keys from where they have been stored.

JweDecrypterService

The JweDecrypterService.java does the decryption of the ID token. The decrypt

method consumes the encrypted JWT and tries to decrypt it by finding the relevant key. It then passes that key with the encrypted JWT to nimbusds-jose-jwt

library which decrypts it and returns the Signed JWT.

Troubleshooting

Connecting this Relying Party example with the Onegini Token Server requires configuration of both applications. This section describes some situations that may

go wrong.

Application fails to start

The RP can only start up when the Onegini Token Server is running. During the start up the RP tries to connect to the discovery endpoint of the

Onegini Token Server.

Check that the Onegini Token Server is running

Check that the property onegini.oidc.issuer points to the base URL of that Onegini Token Server (e.g. http://localhost:7878/oauth)

401 - Unauthorized during login

This means that the authentication has failed.

You may see this when the Relying Party has disabled ID Token encryption but the configuration in the Onegini Token Server has enabled it. When this is the

case, there are two solutions:

Enable ID Token encryption in the RP via the property onegini.oidc.idTokenEncryptionEnabled=true and restart the application

Disable ID Token encryption in the Onegini Token Server. Call the logout endpoint http://localhost:8080/logout before logging in again.

500 - Internal server error during login

An error page is shown during login with a message "Server did not return an Encrypted JWT but encryption was enabled. Check your server side configuration".

You see this when the Relying Party has enabled ID Token encryption but the configuration in the Onegini Token Server has disabled it.

There are two solutions:

Disable ID Token encryption in the RP via the property onegini.oidc.idTokenEncryptionEnabled=false and restart the application

Enable ID Token encryption in the Onegini Token Server. Call the logout endpoint http://localhost:8080/logout before logging in again.

Confirmation page is shown after logout

There can be several reasons why this page is shown by the Onegini Token Server after logging out with the RP:

The POST logout redirect URL is not properly configured. Refer to the Onegini Configuration

ID Token encryption is enabled