pac4j allows you to login using the OpenID Connect protocol v1.0.

It has been tested with various OpenID Connect providers: Google, AzureAD, Okta, IdentityServer3 (and 4), MitreID, Keycloak 4.6…

1) Dependency

You need to use the following module:pac4j-oidc.

Example (Maven dependency):

<dependency><groupId>org.pac4j</groupId><artifactId>pac4j-oidc</artifactId><version>${pac4j.version}</version></dependency>

2) Clients

a) Indirect clients

For any OpenID Connect identity provider, you should use the genericOidcClient (or one of its subclasses).It is an indirect client for web browser based authentication.The configuration is defined via theOidcConfiguration component.

Example:

OidcConfigurationconfig=newOidcConfiguration();config.setClientId(clientId);config.setSecret(secret);config.setDiscoveryURI(discoveryUri);OidcClientoidcClient=newOidcClient(config);

In some cases (when the discovery url is already known for example), you can use a specific client like forGoogle,Azure Active Directory,KeycloakorApple.

Example:

OidcConfigurationconfiguration=newOidcConfiguration();configuration.setClientId("788339d7-1c44-4732-97c9-134cb201f01f");configuration.setSecret("we/31zi+JYa7zOugO4TbSw0hzn+hv2wmENO9AS3T84s=");configuration.setDiscoveryURI("https://login.microsoftonline.com/38c46e5a-21f0-46e5-940d-3ca06fd1a330/.well-known/openid-configuration");AzureAd2Clientclient=newAzureAd2Client(configuration);

TheclientId andsecret will be provided by the OpenID Connect provider, as well as thediscoveryUri (to read the metadata of the identity provider). If you do not define thediscoveryUri, you’ll need to provide the provider metadata by using theStaticOidcOpMetadataResolver component.

AnOidcProfile is returned after a successful authentication (or one of its subclasses:AzureAdProfile,GoogleOidcProfileorKeycloakOidcProfile). All the attributes returned in the ID Token will be available in theOidcProfile even if you can get the ID token directly via thegetIdToken() method.

You can define the flow you want to use via thesetResponseType andsetResponseMode methods:

// implicit flowconfig.setResponseType("id_token");config.setResponseMode("form_post");

By default, theresponse_type is set tocode (the authorization code flow) and theresponse_mode is empty.

You can define the scope to use with thesetScope method:

config.setScope("openid email profile phone");

You can request to use thenonce parameter to reinforce security via:

config.setUseNonce(true);

b) Direct clients

For direct clients (web services), you can get theaccess token from any OpenID Connect identity provider and use that in your request to get the user profile.

For that, theHeaderClient would be appropriate, along with theoidcClient.getProfileCreator().

OidcConfigurationconfig=newOidcConfiguration();config.setClientId(clientId);config.setSecret(secret);config.setDiscoveryURI(discoveryUri);OidcClientoidcClient=newOidcClient(config);oidcClient.setCallbackUrl("notused");oidcClient.init();HeaderClientclient=newHeaderClient("Authorization","Bearer ",oidcClient.getProfileCreator());

The request to the server should have anAuthorization header with the value asBearer {access token}.

3) Advanced configuration

You can define how the client credentials (clientId andsecret) are passed to the token endpoint with thesetClientAuthenticationMethod method:

config.setClientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC);

You can also use thePRIVATE_KEY_JWT authentication method by providing thePrivateKeyJWTClientAuthnMethodConfig component:

oidcConfiguration.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);varprivateKey=org.jasig.cas.client.util.PrivateKeyUtils.createKey("private-key.pem","RSA");varprivateKeyJwtConfig=newPrivateKeyJWTClientAuthnMethodConfig(JWSAlgorithm.RS256,privateKey,"12345");oidcConfiguration.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);

When validating the IDToken in the login process, you can set a clock skew:

// 1 minuteconfig.setMaxClockSkew(60);

You can also choose your preferred algorithm to sign the JSON web tokens:

config.setPreferredJwsAlgorithm(JWSAlgorithm.RS256);

You can finally set additional parameters by using theaddCustomParam(String key, String value) method:

// select display mode: page, popup, touch, and wapconfig.addCustomParam("display","popup");// select prompt mode: none, consent, select_accountconfig.addCustomParam("prompt","none");

Customstate values may be defined in the configuration using the below method:

config.setWithState(true);config.setStateData("custom-state-value");

By default, the local session expires when the access token does, but this can be disabled using:

config.setExpireSessionWithToken(false);

The additional paramTokenExpirationAdvance allows to set the time in seconds, previous to the token expiration, in which the expiration is advanced. By default it is0 seconds.

config.setTokenExpirationAdvance(10);

You can disable the call to the user info endpoint using:

config.setCallUserInfoEndpoint(false);

Since version 5.2 and to reinforce security, thenone alogithm for ID tokens (meaning no signature validation) must be explicitly accepted by using:

config.setAllowUnsignedIdTokens(true);

Since version 6.0.5 and to reinforce security, the logout requests are validated. This can be disabled using:

config.setLogoutValidation(false);