pac4j

https://www.pac4j.org/docs
Admin
pac4j is a security engine for Java applications that provides authentication and authorization...
Tokens:25,621
Snippets:386
Trust Score:8.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configure HTTP Authentication Clients

Source: https://www.pac4j.org/docs/clients/http.html

Examples of configuring ParameterClient for URL tokens and HeaderClient for custom Authorization header validation.

```java
// REST authentication with JWT token passed in the url as the "token" parameter
ParameterClient parameterClient = new ParameterClient("token", new JwtAuthenticator(salt));
parameterClient.setSupportGetRequest(true);
parameterClient.setSupportPostRequest(false);

// if the 'Authorization' header is passed with the 'Basic token' value
HeaderClient client = new HeaderClient("Authorization", "Basic ", (credentials, ctx) -> {
    String token = ((TokenCredentials) credentials).getToken();
    // check the token and create a profile
    if ("goodToken".equals(token)) {
        CommonProfile profile = new CommonProfile();
        profile.setId("myId");
        // save in the credentials to be passed to the default AuthenticatorProfileCreator
        credentials.setUserProfile(profile);
    }
});
```

--------------------------------

### Configure BitbucketClient (OAuth v1.0)

Source: https://www.pac4j.org/docs/clients/oauth.html

Example configuration for simulating the BitbucketClient using OAuth 1.0. Requires setting API, profile definition, key, secret, and callback URL.

```java
OAuth10Configuration config = new OAuth10Configuration();
config.setKey("bjEt8BMpLwFDqZUvp6");
config.setSecret("NN6fVXRTcV2qYVejVLZqxBRqHgn3ygD4");
config.setApi(new BitBucketApi());
config.setProfileDefinition(new BitbucketProfileDefinition());
OAuth10Client client = new OAuth10Client();
client.setCallbackUrl(PAC4J_BASE_URL);
client.setConfiguration(config);
```

--------------------------------

### Initialize Specific OAuth Clients

Source: https://www.pac4j.org/docs/clients/oauth.html

Examples of initializing specific OAuth clients for Facebook and Twitter with their respective API keys and secrets.

```java
FacebookClient facebookClient = new FacebookClient("145278422258960", "be21409ba8f39b5dae2a7de525484da8");
TwitterClient twitterClient = new TwitterClient("CoxUiYwQOSFDReZYdjigBA", "2kAzunH5Btc4gRSaMr7D7MkyoJ5u1VzbOOzE8rBofs");
```

--------------------------------

### Configure GithubClient (OAuth v2.0)

Source: https://www.pac4j.org/docs/clients/oauth.html

Example configuration for simulating the GithubClient using OAuth 2.0. Requires setting API, profile definition, scope, key, secret, and callback URL.

```java
OAuth20Configuration config = new OAuth20Configuration();
config.setApi(GitHubApi.instance());
config.setProfileDefinition(new GitHubProfileDefinition());
config.setScope("user");
config.setKey("62374f5573a89a8f9900");
config.setSecret("01dd26d60447677ceb7399fb4c744f545bb86359");
OAuth20Client client = new OAuth20Client();
client.setConfiguration(config);
client.setCallbackUrl(PAC4J_BASE_URL);
```

--------------------------------

### Configure IndirectKerberosClient

Source: https://www.pac4j.org/docs/clients/kerberos.html

Example of setting up an IndirectKerberosClient for web browser-based authentication. Requires a KerberosAuthenticator with a SunJaasKerberosTicketValidator. The callback URL is mandatory for indirect clients.

```java
import org.pac4j.kerberos.client.direct.DirectKerberosClient;
import org.pac4j.kerberos.client.indirect.IndirectKerberosClient;
import org.pac4j.kerberos.credentials.KerberosCredentials;
import org.pac4j.kerberos.credentials.authenticator.KerberosAuthenticator;
import org.pac4j.kerberos.credentials.authenticator.SunJaasKerberosTicketValidator;
import org.pac4j.kerberos.profile.KerberosProfile;
import org.springframework.core.io.FileSystemResource;

SunJaasKerberosTicketValidator validator = new SunJaasKerberosTicketValidator();
// HTTP/fully-qualified-domain-name@DOMAIN
validator.setServicePrincipal("HTTP/www.mydomain.myrealm.lt@MYREALM.LT");
// the keytab file must contain the keys for the service principal, and should be protected
validator.setKeyTabLocation(new FileSystemResource("/private/security/http-keytab"));
// validator.setDebug(true);

IndirectKerberosClient client = new IndirectKerberosClient(new KerberosAuthenticator(validator));
client.setCallbackUrl("/force-kerberos-login"); // required only for indirect client
```

--------------------------------

### Configure GenericOAuth20Client with Profile Attributes

Source: https://www.pac4j.org/docs/clients/oauth.html

Example for configuring a GenericOAuth20Client to define custom profile attributes. You can specify attribute names or name-converter pairs.

```java
GenericOAuth20Client client = new GenericOAuth20Client();
Map map = new HashMap();
map.put(AGE, "Integer|age");
map.put(IS_ADMIN, "Boolean|is_admin");
map.put(BG_COLOR, "Color|bg_color");
map.put(GENDER, "Gender|gender");
map.put(BIRTHDAY, "Locale|birthday");
map.put(ID, "Long|id");
map.put(BLOG, "URI|blog");
map.put("name", "name");  //default String
client.setProfileAttrs(map);
```

--------------------------------

### Custom OpenSAML Configuration Manager

Source: https://www.pac4j.org/docs/clients/saml.html

Implement this class to provide a custom configuration for OpenSAML. Ensure it has a @Priority annotation with the lowest value to be selected. This example shows how to initialize the XMLObjectProviderRegistry and ParserPool.

```java
@Priority(100)
  public static class DefaultConfigurationManager implements ConfigurationManager {
      @Override
      public void configure() {
          XMLObjectProviderRegistry registry;
          synchronized (ConfigurationService.class) {
              registry = ConfigurationService.get(XMLObjectProviderRegistry.class);
              if (registry == null) {
                  registry = new XMLObjectProviderRegistry();
                  ConfigurationService.register(XMLObjectProviderRegistry.class, registry);
              }
          }

          try {
              InitializationService.initialize();
          } catch (final InitializationException e) {
              throw new RuntimeException("Exception initializing OpenSAML", e);
          }

          ParserPool parserPool = initParserPool();
          registry.setParserPool(parserPool);
      }

      private static ParserPool initParserPool() {

          try {
              BasicParserPool parserPool = new BasicParserPool();
              parserPool.setMaxPoolSize(100);
              parserPool.setCoalescing(true);
              parserPool.setIgnoreComments(true);
              parserPool.setNamespaceAware(true);
              parserPool.setExpandEntityReferences(false);
              parserPool.setXincludeAware(false);
              parserPool.setIgnoreElementContentWhitespace(true);

              final Map<String, Object> builderAttributes = new HashMap<String, Object>();
              parserPool.setBuilderAttributes(builderAttributes);

              final Map<String, Boolean> features = new HashMap<>();
              features.put("http://apache.org/xml/features/disallow-doctype-decl", Boolean.TRUE);
              features.put("http://apache.org/xml/features/validation/schema/normalized-value", Boolean.FALSE);
              features.put("http://javax.xml.XMLConstants/feature/secure-processing", Boolean.TRUE);
              features.put("http://xml.org/sax/features/external-general-entities", Boolean.FALSE);
              features.put("http://xml.org/sax/features/external-parameter-entities", Boolean.FALSE);

              parserPool.setBuilderFeatures(features);
              parserPool.initialize();
              return parserPool;
          } catch (final ComponentInitializationException e) {
              throw new RuntimeException("Exception initializing parserPool", e);
          }
      }
  }

```

--------------------------------

### Identify JCE Illegal Key Size Errors

Source: https://www.pac4j.org/docs/clients/saml.html

Example of error logs encountered when the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files are missing.

```text
ERROR [org.opensaml.xml.encryption.Decrypter] - <Error decrypting the encrypted data element>
org.apache.xml.security.encryption.XMLEncryptionException: Illegal key size
ERROR [org.opensaml.xml.encryption.Decrypter] - <Failed to decrypt EncryptedData using either EncryptedData KeyInfoCredentialResolver or EncryptedKeyResolver + EncryptedKey KeyInfoCredentialResolver>
ERROR [org.opensaml.saml2.encryption.Decrypter] - <SAML Decrypter encountered an error decrypting element content>
```

--------------------------------

### Initialize DbProfileService

Source: https://www.pac4j.org/docs/authenticators/sql.html

Create a DbProfileService instance using a javax.sql.DataSource.

```java
DataSource dataSource = JdbcConnectionPool.create("jdbc:h2:mem:test", dbuser, dbpwd);
DbProfileService dbProfileService = new DbProfileService(dataSource);
```

--------------------------------

### Get Proxy Ticket from CasProxyProfile

Source: https://www.pac4j.org/docs/clients/cas.html

After successful authentication with proxy support, retrieve a proxy ticket for another CAS service URL using the CasProxyProfile.

```java
CasProxyProfile casProxyProfile = (CasProxyProfile) casProfile;
String proxyTicket = casProxyProfile.getProxyTicketFor(anotherCasServiceUrl);
```

--------------------------------

### Configure SAML2Client in Java

Source: https://www.pac4j.org/docs/clients/saml.html

Initializes the SAML2Configuration and SAML2Client for a service provider. Ensure the idp-metadata.xml file is correctly referenced.

```java
final SAML2Configuration cfg = new SAML2Configuration("resource:samlKeystore.jks",
 "pac4j-demo-passwd",
 "pac4j-demo-passwd",
 "resource:idp-metadata.xml"); //the id-metadata.xml contains IdP metadata, you will have to create this
 cfg.setMaximumAuthenticationLifetime(3600);
 cfg.setServiceProviderEntityId("test.pac4j"); //the entityId of you client (the SP), you will usualy change this
 cfg.setServiceProviderMetadataPath(new File("sp-metadata.xml").getAbsolutePath()); //the metadata of the SP, no changes required usually
 final SAML2Client saml2Client = new SAML2Client(cfg);
```

--------------------------------

### Set Assertion Consumer Service Index

Source: https://www.pac4j.org/docs/clients/saml.html

Configure the index for the assertion consumer service. This guides pac4j in selecting the correct ACS URL from the metadata.

```java
cfg.setAssertionConsumerServiceIndex(1);
```

--------------------------------

### Configure Service Provider Metadata from File

Source: https://www.pac4j.org/docs/clients/saml.html

Set the Service Provider metadata by providing a resource path to an XML metadata file.

```java
cfg.setServiceProviderMetadata(new FileSystemResource("/tmp/sp-metadata.xml"));
```

--------------------------------

### Initialize MongoProfileService

Source: https://www.pac4j.org/docs/authenticators/mongodb.html

Create an instance of MongoProfileService using a configured MongoClient.

```java
MongoClient mongoClient = new MongoClient(server, port);
MongoProfileService mongoProfileService = new MongoProfileService(mongoClient);
```

--------------------------------

### Get User Profile Identifier

Source: https://www.pac4j.org/docs/user-profile.html

Retrieves the unique identifier for a user profile. Use getTypedId() to include the profile class name for uniqueness across different identity providers.

```java
profile.getId()
profile.getTypedId()
```

--------------------------------

### Configure Keystore for Federation

Source: https://www.pac4j.org/docs/clients/openid-connect-federation.html

Set the keystore path and passwords for signing entity statements when using a keystore.

```java
oidcConfig.getFederation().getKeystore().setKeystorePath("file:./metadata/oidcfede.keystore");
oidcConfig.getFederation().getKeystore().setKeystorePassword("changeit");
oidcConfig.getFederation().getKeystore().setPrivateKeyPassword("changeit");
```

--------------------------------

### Generate Keystore

Source: https://www.pac4j.org/docs/clients/saml.html

Use keytool to create a JKS keystore for SAML signature and encryption operations.

```bash
keytool -genkeypair -alias pac4j-demo -keypass pac4j-demo-passwd -keystore samlKeystore.jks -storepass pac4j-demo-passwd -keyalg RSA -keysize 2048 -validity 3650
```

--------------------------------

### Configure a generic OidcClient

Source: https://www.pac4j.org/docs/clients/openid-connect-clients.html

Use OidcConfiguration to set up a generic OpenID Connect client for web browser authentication.

```java
OidcConfiguration config = new OidcConfiguration();
config.setClientId("788339d7-1c44-4732-97c9-134cb201f01f");
config.setSecret("we/31zi+JYa7zOugO4TbSw0hzn+hv2wmENO9AS3T84s=");
config.setDiscoveryURI("https://login.microsoftonline.com/38c4650d-3ca06fd1a330/.well-known/openid-configuration");
OidcClient oidcClient = new OidcClient(c);
```

--------------------------------

### Define Basic Security Configuration

Source: https://www.pac4j.org/docs/config.html

Initializes a Config object with authentication clients, authorizers, and matchers.

```java
FacebookClient facebookClient = new FacebookClient("145278422258960", "be21409ba8f39b5dae2a7de525484da8");
TwitterClient twitterClient = new TwitterClient("CoxUiYwQOSFDReZYdjigBA", "2kAzunH5Btc4gRSaMr7D7MkyoJ5u1VzbOOzE8rBofs");

Config config = new Config("http://localhost:8080/callback", facebookClient, twitterClient);

config.addAuthorizer("admin", new RequireAnyRoleAuthorizer("ROLE_ADMIN"));
config.addAuthorizer("custom", new CustomAuthorizer());

config.addMatcher("excludedPath", new ExcludedPathMatcher("^/facebook/notprotected\\.jsp$"));
```

```java
ParameterClient parameterClient = new ParameterClient("token", new JwtAuthenticator(salt));

Config config = new Config(parameterClient);
```

--------------------------------

### Compose Authorizers with OR and AND

Source: https://www.pac4j.org/docs/authorizers.html

Demonstrates how to create a composition of authorizers using logical OR and AND operations. This is useful for defining complex authorization rules.

```java
final Authorizer authorizer = or(
    and(
        requireAnyRole("profile_role1"),
        requireAnyRole("profile_role2")
    ),
    and(
        requireAnyRole("profile_role3"),
        requireAnyRole("profile_role4"),
    )
);

```

--------------------------------

### Configure LdapProfileService with Ldaptive

Source: https://www.pac4j.org/docs/authenticators/ldap.html

Initialize the LdapProfileService by configuring the Ldaptive connection factory and authenticator.

```java
// ldaptive:
FormatDnResolver dnResolver = new FormatDnResolver();
dnResolver.setFormat(LdapServer.CN + "=%s," + LdapServer.BASE_PEOPLE_DN);
ConnectionConfig connectionConfig = new ConnectionConfig();
connectionConfig.setConnectTimeout(500);
connectionConfig.setResponseTimeout(1000);
connectionConfig.setLdapUrl("ldap://localhost:" + LdapServer.PORT);
DefaultConnectionFactory connectionFactory = new DefaultConnectionFactory();
connectionFactory.setConnectionConfig(connectionConfig);
PoolConfig poolConfig = new PoolConfig();
poolConfig.setMinPoolSize(1);
poolConfig.setMaxPoolSize(2);
poolConfig.setValidateOnCheckOut(true);
poolConfig.setValidateOnCheckIn(true);
poolConfig.setValidatePeriodically(false);
SearchValidator searchValidator = new SearchValidator();
IdlePruneStrategy pruneStrategy = new IdlePruneStrategy();
BlockingConnectionPool connectionPool = new BlockingConnectionPool();
connectionPool.setPoolConfig(poolConfig);
connectionPool.setBlockWaitTime(1000);
connectionPool.setValidator(searchValidator);
connectionPool.setPruneStrategy(pruneStrategy);
connectionPool.setConnectionFactory(connectionFactory);
connectionPool.initialize();
PooledConnectionFactory pooledConnectionFactory = new PooledConnectionFactory();
pooledConnectionFactory.setConnectionPool(connectionPool);
PooledBindAuthenticationHandler handler = new PooledBindAuthenticationHandler();
handler.setConnectionFactory(pooledConnectionFactory);
Authenticator ldaptiveAuthenticator = new Authenticator();
ldaptiveAuthenticator.setDnResolver(dnResolver);
ldaptiveAuthenticator.setAuthenticationHandler(handler);
// pac4j:
LdapProfileService ldapProfileService  = new LdapProfileService(connectionFactory, ldaptiveAuthenticator);
```

--------------------------------

### Initialize SAML2Client

Source: https://www.pac4j.org/docs/clients/saml.html

Declare the SAML2Client using the previously defined configuration.

```java
SAML2Client client = new SAML2Client(cfg);
```

--------------------------------

### Configure SAML HTTP Client and Metadata URLs

Source: https://www.pac4j.org/docs/clients/saml.html

This snippet shows how to configure a SAML2Configuration with a custom HTTP client and URLs for keystore and metadata resources. Ensure the URLs point to valid endpoints that serve the required resources.

```java
SAML2HttpClientBuilder httpClient = new SAML2HttpClientBuilder();
httpClient.setConnectionTimeout(Duration.ofSeconds(1));
httpClient.setSocketTimeout(Duration.ofSeconds(1));

final SAML2Configuration config = new SAML2Configuration();
config.setHttpClient(httpClient.build());
config.setKeystoreResourceUrl("http://localhost:8081/keystore");
config.setServiceProviderMetadataResource(
    new FileUrlResource(new URL("http://localhost:8081/saml")));

// Other Stuff...

config.init();
return config;
```

--------------------------------

### Initialize RestAuthenticator Client

Source: https://www.pac4j.org/docs/authenticators/rest.html

Configure the RestAuthenticator with the target API URL and wrap it in a DirectBasicAuthClient.

```java
RestAuthenticator authenticator = new RestAuthenticator("http://rest-api-url");
DirectBasicAuthClient directBasicAuthClient = new DirectBasicAuthClient(authenticator);
```

--------------------------------

### Configure DirectCasProxyClient

Source: https://www.pac4j.org/docs/clients/cas.html

Initializes a DirectCasProxyClient with a CasConfiguration set to CAS30_PROXY protocol.

```java
CasConfiguration config = new CasConfiguration();
config.setLoginUrl("https://casserverpac4j.herokuapp.com/login");
config.setProtocol(CasProtocol.CAS30_PROXY);
DirectCasProxyClient directCasProxyClient = new DirectCasProxyClient(config, "http://localhost:8080/webservices");
```

--------------------------------

### Initialize CasClient with CasConfiguration

Source: https://www.pac4j.org/docs/clients/cas.html

Instantiate a CasClient with the CAS server's login URL. This is used for web applications to participate in Single Sign-On (SSO).

```java
CasClient casClient = new CasClient(new CasConfiguration("https://mycasserver/login"));
```

--------------------------------

### Configure CasRestFormClient

Source: https://www.pac4j.org/docs/clients/cas.html

Initializes a CasRestFormClient using a CasConfiguration pointing to the CAS server login URL.

```java
CasConfiguration casConfig = new CasConfiguration("https://mycasserver/login");
CasRestFormClient casRestClient = new CasRestFormClient(casConfig);
```

--------------------------------

### Configure CasProxyReceptor for Proxy Support

Source: https://www.pac4j.org/docs/clients/cas.html

Set up the CasProxyReceptor in the CasConfiguration to handle proxy authentication. This is necessary for proxy support in CAS.

```java
CasProxyReceptor casProxy = new CasProxyReceptor();
config.setProxyReceptor(casProxy);
```

--------------------------------

### Create Database Schema for Users

Source: https://www.pac4j.org/docs/authenticators/sql.html

SQL script to define the required users table structure for DbProfileService.

```sql
CREATE TABLE users
(
  id varchar(255),
  username varchar(255),
  password varchar(255),
  linkedid varchar(255),
  serializedprofile varchar(10000)
);

ALTER TABLE users
	ADD PRIMARY KEY (id),
	ADD KEY username (username),
	ADD KEY linkedid (linkedid);
```

--------------------------------

### Configure a direct HeaderClient

Source: https://www.pac4j.org/docs/clients/openid-connect-clients.html

Use HeaderClient with an OidcClient profile creator to authenticate web service requests via access tokens.

```java
OidcConfiguration config = new OidcConfiguration();
config.setClientId(clientId);
config.setSecret(secret);
config.setDiscoveryURI(discoveryUri);
OidcClient oidcClient = new OidcClient(config);
oidcClient.setCallbackUrl("notused");
oidcClient.init();
HeaderClient client = new HeaderClient("Authorization", "Bearer ", oidcClient.getProfileCreator());
```

--------------------------------

### Configure OIDC Client with Azure AD

Source: https://www.pac4j.org/docs/clients.html

Sets up an Azure AD v2 client using OIDC configuration and integrates it into pac4j clients with a common callback URL. The callback URL will include the client name as a path parameter.

```java
OidcConfiguration configuration = new OidcConfiguration();
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");
AzureAd2Client client = new AzureAd2Client(configuration);
Clients clients = new Clients("http://localhost:8080/callback", client);
Config config = new Config(clients);
```

--------------------------------

### Configure State and Nonce

Source: https://www.pac4j.org/docs/clients/openid-connect-config.html

Manages custom state values and nonce behavior during refresh.

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

```java
config.setUseNonceOnRefresh(false);
```

--------------------------------

### Initialize IpClient with IpRegexpAuthenticator

Source: https://www.pac4j.org/docs/authenticators/ip.html

Instantiate an IpClient with an IpRegexpAuthenticator to validate incoming IP addresses against a regular expression pattern. The IP address is typically retrieved using context.getRemoteAddr().

```java
IpClient ipClient = new IpClient(new IpRegexpAuthenticator("10\\..*\\"));
```

--------------------------------

### Configure Callback URL with Query Parameters

Source: https://www.pac4j.org/docs/clients.html

Sets up Facebook and Twitter clients with a common callback URL. The callback URL resolver automatically appends the client name as a query parameter.

```java
FacebookClient facebookClient = new FacebookClient(fbKey, fbSecret);
TwitterClient twitterClient = new TwitterClient(twKey, twSecret);
Config config = new Config("http://localhost:8080/callback", facebookClient, twitterClient);
```

--------------------------------

### Configure Signing Algorithms

Source: https://www.pac4j.org/docs/clients/openid-connect-config.html

Sets the algorithms for ID token verification and request object signing.

```java
config.setIdTokenSigningAlgorithm(JWSAlgorithm.RS256);
```

```java
config.setRequestObjectSigningAlgorithm(JWSAlgorithm.RS256);
```

--------------------------------

### Client Interface Methods

Source: https://www.pac4j.org/docs/clients.html

Overview of the primary methods used in the Client interface for authentication workflows.

```APIDOC
## Client Interface Methods

### Description
The Client interface provides the core methods for managing the authentication lifecycle, including redirection, credential extraction, validation, and profile creation.

### Methods
- **getRedirectionAction(CallContext ctx)**: Returns the redirection action to the identity provider for indirect clients.
- **getCredentials(CallContext ctx)**: Extracts credentials from the HTTP request.
- **validateCredentials(CallContext ctx, AuthenticationCredentials credentials)**: Validates the provided credentials.
- **getUserProfile(CallContext ctx, Credentials credentials)**: Builds the authenticated user profile.
- **renewUserProfile(CallContext ctx, UserProfile profile)**: Returns the renewed user profile.
- **processLogout(CallContext ctx, LogoutCredentials credentials)**: Processes logout credentials.
- **getLogoutAction(CallContext ctx, UserProfile currentProfile, String targetUrl)**: Returns the redirection action for identity provider logout.
```

--------------------------------

### Configure pac4j Clients and Authorizers

Source: https://www.pac4j.org/docs/how-to-implement-pac4j-for-a-new-framework.html

Define authentication mechanisms (clients) and authorization rules (authorizers) for pac4j security. Ensure the callback URL is correctly specified when creating the Clients instance.

```java
FacebookClient facebookClient = new FacebookClient(FB_KEY, FB_SECRET);
TwitterClient twitterClient = new TwitterClient(TW_KEY, TW_SECRET);
FormClient formClient = new FormClient("http://localhost:8080/theForm.jsp", new SimpleTestUsernamePasswordAuthenticator(), new UsernameProfileCreator());
CasClient casClient = new CasClient();
casClient.setCasLoginUrl("http://mycasserver/login");
Clients clients = new Clients("http://localhost:8080/callback", facebookClient, twitterClient, formClient, casClient);
Config config = new Config(clients);
config.addAuthorizer("admin", new RequireAnyRoleAuthorizer("ROLE_ADMIN"));
config.addAuthorizer("custom", new CustomAuthorizer());

```

--------------------------------

### Configure Clients via Clients Object

Source: https://www.pac4j.org/docs/config.html

Uses an intermediate Clients object to group authentication mechanisms and apply shared settings.

```java
Clients clients = new Clients("http://localhost:8080/callback", facebookClient, twitterClient, parameterClient);

Config config = new Config(clients);
```

--------------------------------

### Silent Login Configuration

Source: https://www.pac4j.org/docs/clients.html

Configuring a custom profile factory for when authentication fails or is cancelled.

```APIDOC
## Silent Login Configuration

### Description
Allows returning a custom profile (e.g., AnonymousProfile) when the login process fails or is cancelled, preventing a 401 error.

### Method
- **setProfileFactoryWhenNotAuthenticated(Function<CallContext, UserProfile> factory)**

### Request Example
myClient.setProfileFactoryWhenNotAuthenticated(p -> AnonymousProfile.INSTANCE);
```

--------------------------------

### Configure Client Authentication Method

Source: https://www.pac4j.org/docs/clients/openid-connect-config.html

Sets the client authentication method for the token endpoint.

```java
config.setClientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC); // or CLIENT_SECRET_POST
```

--------------------------------

### Configure SAML2Configuration

Source: https://www.pac4j.org/docs/clients/saml.html

Define the SAML2Configuration using Spring resources or string prefixes for resource loading.

```java
SAML2Configuration cfg = new SAML2Configuration(new ClassPathResource("samlKeystore.jks"),
        "pac4j-demo-passwd",
        "pac4j-demo-passwd",
        new ClassPathResource("testshib-providers.xml"));
```

```java
SAML2Configuration cfg = new SAML2Configuration("resource:samlKeystore.jks",
    "pac4j-demo-passwd",
    "pac4j-demo-passwd",
    "resource:testshib-providers.xml");
```

--------------------------------

### Store Interface Methods

Source: https://www.pac4j.org/docs/store.html

Overview of the methods available in the pac4j Store interface for cache management.

```APIDOC
## Store Interface Methods

### Description
The Store interface defines the contract for cache mechanisms in pac4j. It allows for storing, retrieving, and removing values based on keys.

### Methods
- **get(key)**: Retrieves a value from the store associated with the provided key.
- **set(key, value)**: Stores a value in the cache associated with the provided key.
- **remove(key)**: Removes a value from the store identified by the key.

### Implementations
- **GuavaStore**: The default implementation provided by pac4j using the Guava library.
```

--------------------------------

### Configure CasConfiguration with URLs

Source: https://www.pac4j.org/docs/clients/cas.html

Set the CAS login URL and optionally the CAS prefix URL if they differ. This allows for flexible CAS server endpoint configuration.

```java
CasConfiguration config = new CasConfiguration();
config.setLoginUrl("https://casserverpac4j.herokuapp.com/login");
config.setPrefixUrl("http://internal-cas-url");
```

--------------------------------

### Localhost Domain Mapping for Kerberos Testing

Source: https://www.pac4j.org/docs/clients/kerberos.html

This entry in the hosts file maps a fake domain name to localhost, useful for local development and testing of Kerberos authentication where the browser URL must match the fully-qualified domain name specified in the service principal.

```text
127.0.0.1 www.mydomain.myrealm.lt
```

--------------------------------

### Configure Signature Algorithms and Digest Methods

Source: https://www.pac4j.org/docs/clients/saml.html

Specify supported signature algorithms, digest methods, and canonicalization algorithms for SAML authentication requests.

```java
cfg.setBlackListedSignatureSigningAlgorithms(...);
cfg.setSignatureAlgorithms(...);
cfg.setSignatureReferenceDigestMethods(...);
cfg.setSignatureCanonicalizationAlgorithm(...);
```

--------------------------------

### Configure Silent Login

Source: https://www.pac4j.org/docs/clients.html

Sets a custom profile factory to be used when authentication fails or is cancelled, allowing access to resources as an anonymous user.

```java
myClient.setProfileFactoryWhenNotAuthenticated(p -> AnonymousProfile.INSTANCE);
```

--------------------------------

### Add Maven Dependency

Source: https://www.pac4j.org/docs/clients/saml.html

Include the pac4j-saml module in your project's dependencies.

```xml
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-saml</artifactId>
    <version>${pac4j.version}</version>
</dependency>
```

--------------------------------

### Enable OIDC nonce parameter

Source: https://www.pac4j.org/docs/clients/openid-connect-clients.html

Enable the nonce parameter to enhance security during the authentication process.

```java
config.setUseNonce(true);
```

--------------------------------

### Enable Signing of Authentication Requests

Source: https://www.pac4j.org/docs/clients/saml.html

Enable signing of SAML authentication requests by setting 'authnRequestSigned' to true.

```java
cfg.setAuthnRequestSigned(true);
```

--------------------------------

### Configure a provider-specific OidcClient

Source: https://www.pac4j.org/docs/clients/openid-connect-clients.html

Use specialized configuration classes like AzureAd2OidcConfiguration for specific identity providers.

```java
String tenant = "38c46e5a-21f0-46e5-940d-3ca06fd1a330";
AzureAd2OidcConfiguration configuration = new AzureAd2OidcConfiguration(tenant);
configuration.setClientId("788339d7-1c44-4732-97c9-134cb201f01f");
configuration.setSecret("we/31zi+JYa7zOugO4TbSw0hzn+hv2wmENO9AS3T84s=");
AzureAd2Client client = new AzureAd2Client(configuration);
```

--------------------------------

### Configure JWKS for Federation

Source: https://www.pac4j.org/docs/clients/openid-connect-federation.html

Set the JWKS path and key ID for signing entity statements when using JWKS.

```java
oidcConfig.getFederation().getJwks().setJwksPath("file:./metadata/oidcfede.jwks");
oidcConfig.getFederation().getJwks().setKid("mykeyoidcfede26");
```

--------------------------------

### Update SimpleSAMLphp Service Bindings

Source: https://www.pac4j.org/docs/clients/saml.html

Adds HTTP-POST bindings to the SimpleSAMLphp configuration, which are required by PAC4J for SSO and SLO.

```php
'SingleSignOnServiceBinding' => array('urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'),
'SingleLogoutServiceBinding' => array('urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'),
```

--------------------------------

### Configure Federation Target OP and Trust Anchors

Source: https://www.pac4j.org/docs/clients/openid-connect-federation.html

Set the target OP entity ID and add trust anchors for OpenID Connect Federation. Trust anchors include the issuer and JWKS URL.

```java
val federation = oidcConfig.getFederation();

federation.setTargetOp("http://localhost:8080/op");

val trust = new OidcTrustAnchorProperties();
trust.setTaIssuer("http://localhost:8081/ta");
trust.setTaJwksUrl("http://localhost:8081/ta/jwks.json");
federation.getTrustAnchors().add(trust);
```

--------------------------------

### Configure SAML Metadata Generator with JDBC

Source: https://www.pac4j.org/docs/clients/saml.html

This snippet demonstrates how to configure SAML2Configuration to use a JDBC-based metadata generator. It requires an instance of JdbcTemplate and an entity ID. The table name and columns can be customized.

```java
var configuration = new SAML2Configuration();
...
var generator = new SAML2JdbcMetadataGenerator(jdbcTemplate, entityId);
generator.setTableName(...);
...
configuration.setMetadataGenerator(generator);
...
configuration.init();

```

--------------------------------

### Custom Authorizer with HttpAction

Source: https://www.pac4j.org/docs/customizations.html

Implement a custom authorizer that throws a FoundAction to redirect the user under specific conditions. This is useful for breaking the standard flow.

```java
public class ExampleAuthorizer implements Authorizer {

    @Override
    public boolean isAuthorized(WebContext context, SessionStore sessionStore, List<UserProfile> profiles) {
        if ("specificValue".equals(context.getRequestHeader("specificHeader"))) {
            throw new FoundAction("/message.html");
        }
        return true;
    }
}

```

--------------------------------

### GET/POST /callback

Source: https://www.pac4j.org/docs/callback-endpoint.html

The callback endpoint receives requests from identity providers to complete the authentication process or handle central logout requests.

```APIDOC
## GET/POST /callback

### Description
Handles the callback from an identity provider to finish the login process or process a Single-Log-Out (SLO) request.

### Method
GET or POST

### Parameters
#### Query/Form Parameters
- **defaultUrl** (string) - Optional - The URL to redirect to after login if no original URL was requested. Defaults to '/'.
- **renewSession** (boolean) - Optional - Whether to renew the web session after login to prevent session hijacking. Defaults to 'true'.
- **defaultClient** (string) - Optional - The default client to use for finishing the login process if none is provided.

### Behavior
1. Extracts credentials from the request.
2. Fetches the user profile from the identity provider.
3. Saves the profile in the web session.
4. Redirects the user to the originally requested URL or the defaultUrl.
```

--------------------------------

### Configure Unsigned ID Token Acceptance

Source: https://www.pac4j.org/docs/clients/openid-connect-config.html

Enables or disables the acceptance of ID tokens using the 'none' algorithm.

```java
config.setAllowUnsignedIdTokens(true);
```

--------------------------------

### Add pac4j-oidc Maven Dependency

Source: https://www.pac4j.org/docs/clients/openid-connect.html

Include this dependency in your project's pom.xml to enable OpenID Connect support.

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

--------------------------------

### User Profile Structure and Attributes

Source: https://www.pac4j.org/docs/user-profile.html

Explains the components of a pac4j user profile, including its identifier, attributes, authentication-related attributes, roles, client name, and remember-me status.

```APIDOC
## User Profile Overview

When a user is authenticated by pac4j, their data is retrieved from the identity provider and a user profile is constructed. This profile contains:

*   **Identifier**: A unique ID for the user.
*   **Attributes**: Data retrieved from the identity provider.
*   **Authentication-related Attributes**: Information about the authentication process itself.
*   **Roles**: Permissions assigned to the user.
*   **Client Name**: The name of the client used for authentication.
*   **Remember-me Nature**: Indicates if the user is remembered.
*   **Linked Identifier**: An identifier linked to the user profile.

The `BasicUserProfile` is the root class, implementing the `UserProfile` interface. The `CommonProfile` is the most frequently used profile, offering common methods.

### Identifier Management

Each user profile requires a unique identifier. Pac4j clients typically use a value enforced by the identity provider. To avoid collisions when using multiple identity providers, a "typed identifier" is used, which prepends the profile class name to the identifier.

**Example:**
```
profile.getId() // "00001"
profile.getTypedId() // "org.pac4j.oauth.profile.facebook.FacebookProfile#00001"
```

The `ProfileHelper.sanitizeIdentifier` method can be used to convert other Java types and remove the "typed" part of the identifier, as identifiers must be strings.

### Attributes

User profiles contain attributes populated from identity provider data. Attributes with the same name and a collection value can be optionally merged into a single attribute, which is useful for identity providers returning roles in separate single-element collections.

### Authentication-related Attributes

These attributes, such as authentication method or validity period, are stored separately from user attributes and provide details about the authentication process.

### Roles

Roles can be added to a user profile using `addRole(role)` and `addRoles(roles)` methods. They are typically computed by an `AuthorizationGenerator`.

### Client Name

The name of the client used during the login process is saved via `setClientName(name)` and can be retrieved using `getClientName()`.

### Remember-me

The `setRemembered(boolean)` method sets whether a user profile is remembered. `isRemembered()` returns this status. This distinguishes remembered users from fully authenticated ones.

```

--------------------------------

### Configure PRIVATE_KEY_JWT Authentication

Source: https://www.pac4j.org/docs/clients/openid-connect-config.html

Uses a private key for JWT-based client authentication.

```java
oidcConfiguration.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);

val jwksProperties = new JwksProperties();
jwksProperties.setJwksPath("classpath:/static/op/keystore.jwks");
jwksProperties.setKid("cas-qGcosGMN");
val signingKey = JwkHelper.loadJwkFromOrCreateJwks(jwksProperties);

val privateKeyJwtConfig = new PrivateKeyJWTClientAuthnMethodConfig(JWSAlgorithm.RS256, ((RSAKey) signingKey).toKeyPair().getPrivate(), "12345");
oidcConfiguration.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);
```

```java
config.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);
val privateKeyJwtConfig = new PrivateKeyJwtClientAuthnMethodConfig(new JwksProperties());
privateKeyJwtConfig.getJwks().setJwksPath("file:./metadata/clientauthprivatekeyjwt.jwks");
privateKeyJwtConfig.getJwks().setKid("myprivatekeyjwt");
config.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);
```

```java
val rpJwks = config.getRpJwks();
rpJwks.setJwksPath("file:./metadata/rpjwks.jwks");
rpJwks.setKid("defaultjwks0326");
config.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);
val privateKeyJwtConfig = new PrivateKeyJwtClientAuthnMethodConfig(rpJwks);
config.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);
```

--------------------------------

### Profile Definition and Conversion

Source: https://www.pac4j.org/docs/user-profile.html

Details how profile classes and attributes are defined using ProfileDefinition, including attribute converters and profile restoration.

```APIDOC
## Profile Definition

Profile classes and their attributes are defined through implementations of `ProfileDefinition`.

*   **`setProfileFactory`**: This method allows you to specify the instance class to be returned for the user profile.
*   **`primary` and `secondary` methods**: These are used to define attributes along with their specific converters.

Pac4j provides various built-in attribute converters, such as `BooleanConverter` and `ColorConverter`. You can find these in the `org.pac4j.core.profile.converter` package.

The `newProfile` method creates a new instance of the defined profile class. The `convertAndAdd` methods handle the conversion of attributes using associated converters before adding them to the profile.

Additionally, the `newProfile` method can return a related profile of a `typedId` if the `typedId` is provided as the first parameter and `setRestoreProfileFromTypedId(true)` has been invoked.
```

--------------------------------

### Generate JWT with Signature and Encryption

Source: https://www.pac4j.org/docs/authenticators/jwt.html

Instantiate JwtGenerator with signature and encryption configurations to generate a JWT from a profile. Ensure SECRET is defined appropriately.

```java
JwtGenerator generator = new JwtGenerator(new SecretSignatureConfiguration(SECRET), new SecretEncryptionConfiguration(SECRET));
String token = generator.generate(facebookProfile);
```

--------------------------------

### Generate Service Provider Metadata Programmatically

Source: https://www.pac4j.org/docs/clients/saml.html

Obtain the Service Provider metadata as a string using the SAML2Client's metadata resolver.

```java
String spMetadata = client.getServiceProviderMetadataResolver().getMetadata();
```

--------------------------------

### Generate Federation Entity Configuration (Spring Boot)

Source: https://www.pac4j.org/docs/clients/openid-connect-federation.html

Endpoint to generate the entity configuration for OpenID Connect Federation in a Spring Boot application. Requires the OidcClient to be configured.

```java
@RequestMapping(value = "/.well-known/openid-federation", produces = DefaultEntityConfigurationGenerator.CONTENT_TYPE)
    @ResponseBody
    public String oidcFederation() throws HttpAction {
        val oidcClient = (OidcClient) config.getClients().findClient("OidcClient").get();
        return oidcClient.getConfiguration().getFederation().getEntityConfigurationGenerator().generate();
    }
```

--------------------------------

### Configure JwtAuthenticator with Signature and Encryption

Source: https://www.pac4j.org/docs/authenticators/jwt.html

Set up JwtAuthenticator to handle signed and encrypted JWTs using various configurations like secrets and key pairs. Ensure signature configurations are defined for signed JWTs; otherwise, plain text JWTs might be accepted with a warning. Encryption is optional by default but can be enforced.

```java
JwtAuthenticator jwtAuthenticator = new JwtAuthenticator();

# define two signature configurations (one based on the KEY2 secret and the other one based on a generated RSA key pair)
jwtAuthenticator.addSignatureConfiguration(new SecretSignatureConfiguration(KEY2));
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
KeyPair rsaKeyPair = keyGen.generateKeyPair();
jwtAuthenticator.addSignatureConfiguration(new RSASignatureConfiguration(rsaKeyPair));

# define two encryption configurations (one based on the SECRET secret and the other one based on a generated elliptic curve key pair)
jwtAuthenticator.addEncryptionConfiguration(new SecretEncryptionConfiguration(SECRET));
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("EC");
KeyPair ecKeyPair = keyGen.generateKeyPair();
ECEncryptionConfiguration encConfig = new ECEncryptionConfiguration(ecKeyPair);
encConfig.setAlgorithm(JWEAlgorithm.ECDH_ES_A128KW);
encConfig.setMethod(EncryptionMethod.A192CBC_HS384);
jwtAuthenticator.addEncryptionConfiguration(encConfig);

jwtAuthenticator.validate(new TokenCredentials(token, "myclient"));
```

--------------------------------

### Register SP EntityID in SimpleSAMLphp

Source: https://www.pac4j.org/docs/clients/saml.html

Registers the Service Provider entity ID and Assertion Consumer Service URL in the remote SP metadata file.

```php
$metadata['test.pac4j'] = array(
 'AssertionConsumerService' => 'http://localhost:8080/callback?client_name=SAML2Client',
...
```

--------------------------------

### Set Default Client for NoParameterCallbackUrlResolver

Source: https://www.pac4j.org/docs/clients.html

Configures a default client to be used when the NoParameterCallbackUrlResolver is employed, as no client name is appended to the callback URL.

```java
defaultCallbackLogic.setClient("FacebookClient");
```

--------------------------------

### Add Custom OIDC Parameters

Source: https://www.pac4j.org/docs/clients/openid-connect-config.html

Adds custom parameters to the OIDC configuration, such as display or prompt modes.

```java
// select display mode: page, popup, touch, and wap
config.addCustomParam("display", "popup");
// select prompt mode: none, consent, select_account
config.addCustomParam("prompt", "none");
```
Tokens:
Raw