# Epic SI-2 - Seamless integration of user sessions of Nextcloud and OpenProject using OIDC & JWTs

Project: Stream Integration Basics
Status: closed
URL: https://community.openproject.org/work_packages/SI-2

## Detailed specification

### Motivation and background information

### Acceptance criteria

### Out of scope

User provisioning via SCIM. This is tracked seperately <mention class="mention" data-id="55941" data-type="work_package" data-text="###55941">\#\#\#55941</mention>

| Attribute | Value |
| --- | --- |
| Mockups |  |

## Planning

| Attribute | Value |
| --- | --- |
| Roadmap |  |
| Date | 2025-02-03 – 2025-05-07 |
| Votes |  |
| List |  |
| Target versions | 16.0.0 |
| Relevance |  |

## Subitems

| ID | Type | Subject | Status | Assignee | Target versions | Project | Priority | Spent time |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SI-12 | Feature | Extend API authentication to accept JWT issued by OpenID provider to other client.  | closed |  | 14.4.0 | Stream Integration Basics | Medium |  |
| SI-3 | Feature | Add and document Keycloak to the Docker based development setup | closed |  | 15.4.0 | Stream Integration Basics | Medium |  |
| SI-68 | Feature | Store token expiration information for OIDC user tokens | closed |  | 15.4.0 | Stream Integration Basics | Medium |  |
| SI-71 | Feature | OIDC provider creation: Prefill scopes instead of showing a placeholder | closed |  | 15.4.0 | Stream Integration Basics | Medium |  |
| SI-76 | Feature | Show proper error message when refresh token is unusable | closed |  | 15.4.0 | Stream Integration Basics | Medium |  |
| SI-10 | Feature | File storages settings for type Nextcloud: Allow OIDC based connection instead of OAuth2 | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-14 | Feature | Extend Nextcloud files storage to use SSO access tokens  | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-39 | Feature | Store token exchange capability on OIDC providers | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-47 | Feature | Support OIDC in storage health status | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-53 | Feature | Enterprise banner (Corporate Plan) for Nextcloud SSO authentication | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-73 | Feature | Allow to configure SSO authentication + two-way OAuth 2 | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-77 | Feature | Audience selection for Nextcloud Hub scenario | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-83 | Feature | Link to new OIDC docs from storages setup | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-105 | Feature | Allow to set authentication method and storage audience via API | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-106 | Feature | Hide authentication method for "SSO with Fallback" | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-119 | Feature | Validate scope of JWTs | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| SI-134 | Feature | Storage sidebar button in projects should behave correctly in all scenarios | closed |  | 16.0.0 | Stream Integration Basics | Medium |  |
| NEX-462 | Feature | Allow to use first SSO token for authentication at OpenProject | closed | Sajan Gurung | Nextcloud Integration 2.9.0 | Stream Nextcloud app "OpenProject Integration" | Medium |  |
| SI-15 | Open Point | Is the setup for token exchange from one OIDC client to another scriptable in Keycloak? | decided | Sagar Gurung |  | Stream Integration Basics | Medium |  |

## Bugs and other work packages

| ID | Type | Subject | Status | Assignee | Target versions | Module |
| --- | --- | --- | --- | --- | --- | --- |
| SI-11 | Bug | Do not save access token in cookies | closed |  | 14.2.0 |  |
| SI-61 | Bug | Refreshing exchanged token does not work with Keycloak | closed |  | 15.3.0 |  |
| SI-60 | Task | Document Keycloak development setup | closed | Jan Sandbrink | 15.3.0 |  |
| SI-91 | Bug | Trying to create OIDC user tokens, even for non-OIDC providers | closed |  | 15.4.0 |  |
| SI-89 | Bug | Authentication errors during fetch of origin_user_id are not shown properly | closed |  | 15.4.0 |  |
| SI-88 | Bug | Can't replace OAuth application if none is present | closed |  | 15.4.0 |  |
| SI-56 | Code maintenance | Refactor to support different steps during setup | closed |  | 15.4.0 |  |
| SI-155 | Bug | Can't list project storage members when one member is incompatible with SSO storage | closed |  | 16.0.0 | Modules and project features / File storages |
| SI-152 | Task | Note to release notes that Storage SSO is experimental | closed | Jan Sandbrink | 16.0.0 |  |
| SI-143 | Task | Add breaking change info to release notes | closed | Jan Sandbrink | 16.0.0 |  |
| SI-107 | Bug | Storage shows as healthy even if audience is misconfigured | closed |  | 16.0.0 |  |
| SI-102 | Bug | Linking to project storage via SSO fails when user can't authenticate | closed |  | 16.0.0 |  |
| SI-87 | Bug | Can't associate storage to project via storage admin view | closed |  | 16.0.0 |  |
| SI-86 | Bug | SSO users storage connection does not work on project storage members page  | closed |  | 16.0.0 |  |
| SI-84 | Bug | Empty audience translation is missing | closed |  | 16.0.0 |  |
| SI-80 | Bug | Token Refresh and Exchange does not work when Client ID contains special characters | closed |  | 16.0.0 |  |
| SI-78 | Documentation | Update documentation to include SSO-based storage authentication | closed | Jan Sandbrink | 16.0.0 |  |
| SI-54 | Documentation | Allow migration from a "two-way OAuth 2" setup to "OAuth 2 SSO" | closed |  | 16.0.0 |  |
| NEX-466 | Bug | Can't configure integration when oidc app is not installied | closed | Sajan Gurung | Nextcloud Integration 2.9.0 |  |
| SI-8 | Task | Investigate token exchange in Keycloak | closed | Sagar Gurung |  |  |
| SI-7 | Task | Investigate if Nextcloud respects the "aud" (Audience) of a JWT access tokens when used as Bearer token | closed | Sagar Gurung |  |  |
| SI-6 | Task | Investigate if OpenProject accepts JWT token when used as Bearer token. | closed |  |  |  |
| NEX-429 | Task | check what NextCloud is doing with "auto provisionion on API calls " | closed |  |  |  |
| NEX-425 | Task | Follow up token exchange mechanism implemented in user_oidc app | closed |  |  |  |
| NEX-435 | Documentation | Add documentation for OIDC OP-NC connection method | rejected | Jan Sandbrink |  |  |
| SI-15 | Open Point | Is the setup for token exchange from one OIDC client to another scriptable in Keycloak? | decided | Sagar Gurung |  |  |

## Details

| Attribute | Value |
| --- | --- |
| Module |  |
| Enterprise plan | Enterprise / Corporate (COR) |
| Labels |  |

## People

| Attribute | Value |
| --- | --- |
| Assignee | Robin Wagner |
| Accountable | Pavel Balashou |
| Product manager |  |
| Feature Lead |  |
| Designer | Marc Alcobé |
| Developers | OP Dev Titan Team |
| Requested by |  |
| Interest by |  |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| Work |  |

## Description

Our goal of this EPIC is to allow setting up the integration between OpenProject (OP) and Nextcloud (NC) in a way, that does not require users to visit consent screens from both applications. Instead of mutually being OAuth Client and server for one another, OP and NC can be set-up to agree on a common OpenID Connect identity provider (IDP) from which they obtain user-bound tokens to call each other's API.

From the user's perspective this improves the UX, while we are hopefully able to lay the technical foundation for similar authentication patterns for future/other integrations.

This Epic covers two similar, but slightly different use cases:

  - The IDP issues "wide use" access tokens
    
    1.  OP obtains access and refresh token during single-sign-on of the user
    
    2.  OP recognizes that the token already grants access for API calls to NC
    
    3.  OP uses the token directly to make API requests in the user's name

  - The IDP issues "narrow use" access tokens
    
    1.  OP obtains access and refresh token during single-sign-on of the user
    
    2.  OP recognizes that the token does not grant access to NC, but that the IDP is capable of token exchange
    
    3.  OP exchanges the token for a token capable of making requests to NC
    
    4.  OP uses the obtained token to make requests in the user's name

We want to successfully integrate this feature with the following IDPs:

  - Keycloak (supports both use cases)

  - Nextcloud as OIDC provider (may only support the use case with "wide use" access tokens in the beginning)

In order to make it as easy as possible for new users we need to come up with a good, detailed plan. It involves at least:

  - A compatible OIDC/OAuth 2.0 Identity Provider
    
      - e.g. Keycloak or Nextcloud with the OIDC app

  - Nextcloud
    
      - Nextcloud core accept/verify and store those sessions on incoming API requests
    
      - Nextcloud app
        
          - to accept/verify (ideally handled by core) incoming API requests for API endpoints that are provided by the app
        
          - uses such sessions for outgoing requests to OpenProject

  - OpenProject
    
      - Allowing OpenProject to be configured to use that special type of setup
        
          - Provide railguards and helpers to avoid/detect configuration errors
    
      - Accept/verify these tokens on incoming API requests
    
      - Store tokens associated to a user
    
      - Make the the file storage connection use those tokens when emitting requests to Nextcloud
    
      - Take special care of the background jobs (they currently use a Nextcloud app password as there is no user session)

> This plan is still pretty rough. This is an integration topic with high complexity but definitely worth the effort. I recommend to work with proofs of concept in the beginning. It also requires that all three involved parties are working closely together.

This is an Enterprise Edition feature as SSO already is an Enterprise Feature and this one depends on SSO.
