This is an automated email from the ASF dual-hosted git repository. quantranhong1999 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 73bf2833830aae3061498f335f33be5753b8d75f Author: Quan Tran <[email protected]> AuthorDate: Thu Jul 2 16:29:02 2026 +0700 JAMES-4195 Document JMAP OIDC authentication Documents JMAP OIDC properties, sample configuration, cache behavior, Redis fallback, and backchannel logout. --- docs/modules/servers/partials/configure/jmap.adoc | 48 ++++++++++++++++++++++ docs/modules/servers/partials/configure/oidc.adoc | 4 +- .../sample-configuration/jmap.properties | 11 +++++ .../sample-configuration/jmap.properties | 10 +++++ .../sample-configuration/jmap.properties | 11 +++++ 5 files changed, 82 insertions(+), 2 deletions(-) diff --git a/docs/modules/servers/partials/configure/jmap.adoc b/docs/modules/servers/partials/configure/jmap.adoc index 2691fabbd3..45a0abe11a 100644 --- a/docs/modules/servers/partials/configure/jmap.adoc +++ b/docs/modules/servers/partials/configure/jmap.adoc @@ -69,6 +69,30 @@ The implicit package name is `org.apache.james.jmap.http`. If you have a custom If no authentication strategy is specified, JMAP RFC-8621 server will fallback to default strategies: `JWTAuthenticationStrategy`, `BasicAuthenticationStrategy`. +| oidc.userInfo.url +| Optional String. Configures the user info endpoint url for OIDC authentication. Example: `http://keycloak:8080/auth/realms/oidc/protocol/openid-connect/token/userinfo`. Mandatory if `OidcAuthenticationStrategy` is declared in `authentication.strategy.rfc8621`. + +| oidc.introspect.url +| Optional String. Configures the introspection url for OIDC authentication. Example: `http://keycloak:8080/auth/realms/oidc/protocol/openid-connect/introspect`. Mandatory if `OidcAuthenticationStrategy` is declared in `authentication.strategy.rfc8621`. + +| oidc.introspect.credentials +| Optional String. Configures the credentials for accessing the introspection endpoint for OIDC authentication. Example: `Bearer ewjiwelhwew`. + +| oidc.claim +| Optional String. Configures the claim to get the username from for OIDC authentication. Example: `email`. Mandatory if `OidcAuthenticationStrategy` is declared in `authentication.strategy.rfc8621`. + +| oidc.audience +| Optional List[String] with delimiter `,`. Configures a list of audiences for OIDC authentication. Example: `tmail,james`. Omitting this bypasses the audience check (not advised). + +| oidc.token.cache.expiration +| Optional duration. Configures the OIDC token cache expiration time. Example: `300s`. Defaults to 5 minutes. + +| oidc.token.cache.maxSize +| Optional positive integer. Configures the maximum number of OIDC tokens to cache in memory. Example: `10000`. Defaults to 10000 tokens. + +| oidc.token.cache.redis.command.timeout +| Optional duration. Defaults to `3s`. Timeout for Redis commands when the Redis OIDC token cache is selected. + | jmap.version.default | Optional string. Defaults to `rfc-8621`. Allowed values: rfc-8621 Which version of the JMAP protocol should be served when none supplied in the Accept header. @@ -125,6 +149,30 @@ like authentication credentials. == OIDC set up +James can authenticate JMAP RFC-8621 requests directly against an OIDC provider by enabling +`OidcAuthenticationStrategy`: + +.... +authentication.strategy.rfc8621=OidcAuthenticationStrategy +oidc.userInfo.url=https://oidc.example.com/protocol/openid-connect/userinfo +oidc.introspect.url=https://oidc.example.com/protocol/openid-connect/token/introspect +oidc.introspect.credentials=Basic base64(client_id:client_secret) +oidc.claim=email +oidc.audience=james +.... + +Clients pass the access token as a bearer token: + +.... +curl -H "Authorization: Bearer $token" -XPOST http://127.0.0.1:80/jmap -d '...' +.... + +OIDC token information is cached. The memory app uses an in-memory Caffeine cache. +Postgres and distributed apps use the Redis cache when `redis.properties` is present, otherwise they use the in-memory cache. + +Backchannel logout is exposed as a WebAdmin route at `POST /add-revoked-token` and expects an `application/x-www-form-urlencoded` +body containing the `logout_token` parameter. The token payload must contain the `sid` claim to invalidate related cached access tokens. + The use of `XUserAuthenticationStrategy` allow delegating the authentication responsibility to a third party system, which could be used to set up authentication against an OIDC provider. diff --git a/docs/modules/servers/partials/configure/oidc.adoc b/docs/modules/servers/partials/configure/oidc.adoc index 85e3d1b9db..193c15e742 100644 --- a/docs/modules/servers/partials/configure/oidc.adoc +++ b/docs/modules/servers/partials/configure/oidc.adoc @@ -1,6 +1,6 @@ -James supports OIDC via both `XOAUTH2` and `OAUTHBEARER`. -Support is only available for Managesieve, IMAP, and SMTP. +James supports OIDC via both `XOAUTH2` and `OAUTHBEARER` for Managesieve, IMAP, and SMTP. +JMAP RFC-8621 also supports OIDC bearer authentication via `OidcAuthenticationStrategy`. OIDC is not supported for POP3 and LMTP. We provide an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of an OIDC setup. It uses Keycloak as identity provider, but usage of other providers is possible. diff --git a/server/apps/distributed-app/sample-configuration/jmap.properties b/server/apps/distributed-app/sample-configuration/jmap.properties index 73fb3f9abb..881fa372d6 100644 --- a/server/apps/distributed-app/sample-configuration/jmap.properties +++ b/server/apps/distributed-app/sample-configuration/jmap.properties @@ -29,6 +29,17 @@ tls.secret=james72laBalle # If you want to specify authentication strategies for Jmap rfc-8621 version # For custom Authentication Strategy not inside package "org.apache.james.jmap.http", you have to specify its FQDN # authentication.strategy.rfc8621=JWTAuthenticationStrategy,BasicAuthenticationStrategy +# +# JMAP RFC-8621 can authenticate against an OIDC provider with: +# authentication.strategy.rfc8621=OidcAuthenticationStrategy +# oidc.userInfo.url=https://oidc.example.com/protocol/openid-connect/userinfo +# oidc.introspect.url=https://oidc.example.com/protocol/openid-connect/token/introspect +# oidc.introspect.credentials=Basic base64(client_id:client_secret) +# oidc.claim=email +# oidc.audience=james +# oidc.token.cache.expiration=5m +# oidc.token.cache.maxSize=10000 +# oidc.token.cache.redis.command.timeout=3s # Prevent server side request forgery by preventing calls to the private network ranges. Defaults to true, can be disabled for testing. # webpush.prevent.server.side.request.forgery=false \ No newline at end of file diff --git a/server/apps/memory-app/sample-configuration/jmap.properties b/server/apps/memory-app/sample-configuration/jmap.properties index 72e279e419..40e4011bd9 100644 --- a/server/apps/memory-app/sample-configuration/jmap.properties +++ b/server/apps/memory-app/sample-configuration/jmap.properties @@ -27,6 +27,16 @@ delay.sends.enabled=true # If you want to specify authentication strategies for Jmap rfc-8621 version # For custom Authentication Strategy not inside package "org.apache.james.jmap.http", you have to specify its FQDN # authentication.strategy.rfc8621=JWTAuthenticationStrategy,BasicAuthenticationStrategy +# +# JMAP RFC-8621 can authenticate against an OIDC provider with: +# authentication.strategy.rfc8621=OidcAuthenticationStrategy +# oidc.userInfo.url=https://oidc.example.com/protocol/openid-connect/userinfo +# oidc.introspect.url=https://oidc.example.com/protocol/openid-connect/token/introspect +# oidc.introspect.credentials=Basic base64(client_id:client_secret) +# oidc.claim=email +# oidc.audience=james +# oidc.token.cache.expiration=5m +# oidc.token.cache.maxSize=10000 # Prevent server side request forgery by preventing calls to the private network ranges. Defaults to true, can be disabled for testing. # webpush.prevent.server.side.request.forgery=false \ No newline at end of file diff --git a/server/apps/postgres-app/sample-configuration/jmap.properties b/server/apps/postgres-app/sample-configuration/jmap.properties index 73fb3f9abb..881fa372d6 100644 --- a/server/apps/postgres-app/sample-configuration/jmap.properties +++ b/server/apps/postgres-app/sample-configuration/jmap.properties @@ -29,6 +29,17 @@ tls.secret=james72laBalle # If you want to specify authentication strategies for Jmap rfc-8621 version # For custom Authentication Strategy not inside package "org.apache.james.jmap.http", you have to specify its FQDN # authentication.strategy.rfc8621=JWTAuthenticationStrategy,BasicAuthenticationStrategy +# +# JMAP RFC-8621 can authenticate against an OIDC provider with: +# authentication.strategy.rfc8621=OidcAuthenticationStrategy +# oidc.userInfo.url=https://oidc.example.com/protocol/openid-connect/userinfo +# oidc.introspect.url=https://oidc.example.com/protocol/openid-connect/token/introspect +# oidc.introspect.credentials=Basic base64(client_id:client_secret) +# oidc.claim=email +# oidc.audience=james +# oidc.token.cache.expiration=5m +# oidc.token.cache.maxSize=10000 +# oidc.token.cache.redis.command.timeout=3s # Prevent server side request forgery by preventing calls to the private network ranges. Defaults to true, can be disabled for testing. # webpush.prevent.server.side.request.forgery=false \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
