Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions ChangeLog.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,13 @@ specific language governing permissions and limitations
under the License.
-->

**2026-11-18 Arturo Bernal (abernal AT apache DOT org)**

* _3.0.1-git-10_

* Fix for [JSPWIKI-94](https://issues.apache.org/jira/browse/JSPWIKI-94): the new module jspwiki-oidc logs users in with OpenID Connect, with the pac4j filters, and presents them to the wiki as users authenticated by the container, including their roles and the logout. It is not included in the war unless it is built with the profile oidc, and its filters are disabled in web.xml
* Fix for [JSPWIKI-1375](https://issues.apache.org/jira/browse/JSPWIKI-1375): the OpenID Connect login of the module jspwiki-oidc works with any OpenID Connect provider, with the claims for the name and the roles of the user configurable

**2026-11-14 Multiple authors**

* _3.0.1-git-09
Expand Down
2 changes: 1 addition & 1 deletion jspwiki-api/src/main/java/org/apache/wiki/api/Release.java
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ public final class Release {
* <p>
* If the build identifier is empty, it is not added.
*/
public static final String BUILD = "9";
public static final String BUILD = "10";

/**
* This is the generic version string you should use when printing out the version. It is of
Expand Down
90 changes: 90 additions & 0 deletions jspwiki-oidc/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->


# jspwiki-oidc

Logs users in with OpenID Connect, using the pac4j filters, and presents them to the wiki as users authenticated by the
container. It works with any OpenID Connect provider: it has been tried with Keycloak, see
[JSPWIKI-94](https://issues.apache.org/jira/browse/JSPWIKI-94) and
[JSPWIKI-1375](https://issues.apache.org/jira/browse/JSPWIKI-1375). The configurations for Google and Microsoft Entra ID (Azure)
below follow what these providers document, and have not been tried with them.

## Enabling it

1. Build the war with `mvn package -Poidc`, or add this module and its dependencies to `WEB-INF/lib`.
2. Create `WEB-INF/classes/jspwiki-oidc.properties`:

```
oidc.clientId=the client id
oidc.secret=the client secret
oidc.discoveryUri=https://provider.example.org/.well-known/openid-configuration
oidc.callbackUrl=/oidc/callback
```

The optional settings are:

- `oidc.scope`, `openid email profile` by default.
- `oidc.usernameClaim`, the claim with the name of the user in the wiki, `preferred_username` by default. When the claim is
missing, the wiki uses the e-mail address, and then the identifier of the user at the provider.
- `oidc.rolesClaim`, the claim with the roles of the user. It is searched in the profile and in the access token when this is a JWT,
and it may be a dotted path through nested claims. Without it, the users have no roles from the provider.
- `oidc.roleMapping`, to turn the values of the roles claim into the names of the roles of the wiki when the provider sends
identifiers instead of names, written `value=Role,value2=Role2`.

3. Add to `WEB-INF/classes/jspwiki-custom.properties`:

```
jspwiki.authorizer = org.apache.wiki.oidc.OidcAuthorizer
```

The roles the wiki takes from the provider are `Admin` and `Authenticated`. Change them with the property
`jspwiki.oidc.roles`, a comma separated list.
4. In `WEB-INF/web.xml`, remove the comment marks around the OpenID Connect filters.
5. In the provider, register the address `https://your.wiki/oidc/callback` as redirect URI, and the address of the wiki as post logout
redirect URI if the provider has that setting.

The links to log in and out of the wiki then use the provider: `Login.jsp` sends the user to it, and `Logout.jsp` ends the session of the
wiki and of the provider. The wiki is not asked for passwords, and its own user profiles are not used.

## Providers

Keycloak: the roles are in the access token, in the nested claim `realm_access.roles`.

```
oidc.discoveryUri=https://keycloak.example.org/realms/jspwiki/.well-known/openid-configuration
oidc.rolesClaim=realm_access.roles
```

Microsoft Entra ID (Azure): register the application with the redirect URI, create a client secret and define application roles
(App roles) for the administrators, which Entra sends in the claim `roles`. Use the tenant in the discovery address.

```
oidc.discoveryUri=https://login.microsoftonline.com/TENANT-ID/v2.0/.well-known/openid-configuration
oidc.usernameClaim=preferred_username
oidc.rolesClaim=roles
```

Google: create an OAuth client of type web application. Google does not send roles, so all its users are authenticated users of the wiki,
and the administrators can be defined with the groups of the wiki.

```
oidc.discoveryUri=https://accounts.google.com/.well-known/openid-configuration
oidc.usernameClaim=email
```
86 changes: 86 additions & 0 deletions jspwiki-oidc/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

<parent>
<groupId>org.apache.jspwiki</groupId>
<artifactId>jspwiki-builder</artifactId>
<version>3.0.1-SNAPSHOT</version>
</parent>

<modelVersion>4.0.0</modelVersion>
<artifactId>jspwiki-oidc</artifactId>
<name>Apache JSPWiki OpenID Connect login</name>

<properties>
<pac4j.version>6.5.5</pac4j.version>
<jakartaee-pac4j.version>8.0.3</jakartaee-pac4j.version>
</properties>

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

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

<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>jspwiki-main</artifactId>
<version>${project.version}</version>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>

<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
</project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
*/
package org.apache.wiki.oidc;

import java.text.ParseException;
import java.util.Collection;
import java.util.HashMap;
import java.util.LinkedHashSet;
import java.util.Map;
import java.util.Optional;
import java.util.Set;

import org.pac4j.core.authorization.generator.AuthorizationGenerator;
import org.pac4j.core.context.CallContext;
import org.pac4j.core.profile.UserProfile;
import org.pac4j.oidc.profile.OidcProfile;

import com.nimbusds.jwt.JWTParser;

/**
* Takes the roles of the user from a claim of the profile or of the access token, as {@code roles} in Azure or
* {@code realm_access.roles} in Keycloak.
*/
class ClaimRolesAuthorizationGenerator implements AuthorizationGenerator {

private final String claim;
private final Map< String, String > mapping;

ClaimRolesAuthorizationGenerator( final String claim, final Map< String, String > mapping ) {
this.claim = claim;
this.mapping = mapping;
}

/** {@inheritDoc} */
@Override
public Optional< UserProfile > generate( final CallContext context, final UserProfile profile ) {
final Map< String, Object > claims = new HashMap<>( profile.getAttributes() );
if( profile instanceof OidcProfile && ( ( OidcProfile )profile ).getAccessToken() != null ) {
try {
claims.putAll( JWTParser.parse( ( ( OidcProfile )profile ).getAccessToken().getValue() ).getJWTClaimsSet().getClaims() );
} catch( final ParseException e ) {
// the access token is opaque, so the roles can only be in the profile
}
}
profile.addRoles( rolesFrom( claims ) );
return Optional.of( profile );
}

/**
* Reads the roles from a set of claims.
*
* @param claims the claims of the profile and of the access token
* @return the names of the roles of the wiki
*/
Set< String > rolesFrom( final Map< String, Object > claims ) {
final Set< String > roles = new LinkedHashSet<>();
final Object value = lookup( claims, claim );
if( value instanceof Collection ) {
for( final Object item : ( Collection< ? > )value ) {
add( roles, item );
}
} else {
add( roles, value );
}
return roles;
}

private void add( final Set< String > roles, final Object value ) {
if( value != null && !value.toString().isBlank() ) {
final String text = value.toString().trim();
roles.add( mapping.getOrDefault( text, text ) );
}
}

/**
* Looks a claim up by its name or, if there is none with that name, by a path of names separated by dots through nested claims.
*/
static Object lookup( final Map< String, Object > claims, final String path ) {
if( claims.containsKey( path ) ) {
return claims.get( path );
}
Object current = claims;
for( final String part : path.split( "\\." ) ) {
if( !( current instanceof Map ) ) {
return null;
}
current = ( ( Map< ?, ? > )current ).get( part );
}
return current;
}

}
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
*/
package org.apache.wiki.oidc;

import java.util.Arrays;
import java.util.Properties;

import org.apache.wiki.api.core.Engine;
import org.apache.wiki.auth.authorize.Role;
import org.apache.wiki.auth.authorize.WebContainerAuthorizer;

/**
* Authorizer for wikis whose users log in with OpenID Connect. The login is done by filters and not by constraints of the web
* application descriptor, so this authorizer declares that the container handles the login, and takes the names of the roles
* from the property {@code jspwiki.oidc.roles}, a comma separated list that defaults to {@code Admin,Authenticated}.
*/
public class OidcAuthorizer extends WebContainerAuthorizer {

/** Property with the comma separated names of the roles the identity provider may grant. */
public static final String PROP_ROLES = "jspwiki.oidc.roles";

private static final String DEFAULT_ROLES = "Admin,Authenticated";

/** {@inheritDoc} */
@Override
public void initialize( final Engine engine, final Properties props ) {
super.initialize( engine, props );
m_containerAuthorized = true;
m_containerRoles = Arrays.stream( props.getProperty( PROP_ROLES, DEFAULT_ROLES ).split( "," ) )
.map( String::trim )
.filter( name -> !name.isEmpty() )
.map( Role::new )
.toArray( Role[]::new );
}

}
Loading
Loading