> For the complete documentation index, see [llms.txt](https://docs.oceanenterprise.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oceanenterprise.io/operational-guidelines/federated-authentication/onboarding-data-space-participant-in-data-space-operator-authentik.md).

# Onboarding Data Space Participant in Data Space Operator Authentik

### Table of Contents

* [Overview](#overview)
* [Directory Structure](#directory-structure)
* [Sequence Flow](#sequence-flow)
* [Prerequisites](#prerequisites)
  * [Data Space Participant Side](#data-space-participant-side)
  * [Data Space Operator Side](#data-space-operator-side)
* [Prepare Participant Configuration on Data Space Operator](#prepare-participant-configuration-on-data-space-operator)
  * [Field Descriptions](#field-descriptions)
* [Participant onboarding steps](/operational-guidelines/federated-authentication/onboarding-data-space-participant-in-data-space-operator-authentik.md#onboarding-steps)
  * [Copy the Participant Configuration file on the Dataspace Operator Authentik Server](/operational-guidelines/federated-authentication/onboarding-data-space-participant-in-data-space-operator-authentik.md#copy-the-participant-configuration-file-on-the-dataspace-operator-authentik-server)
  * [Run the onboarding Script](#run-onboarding-script)
* [Verification](#verification)
  * [Federated Authentication](#federated-authentication)
  * [Token Claims Verification](#token-claims-verification)
* [Troubleshooting](#troubleshooting)
  * [Operator cannot fetch the Participant well-known URL](#operator-cannot-fetch-the-participant-well-known-url)
  * [Federation source exists, but login is not offered](#federation-source-exists-but-login-is-not-offered)
  * [OE claims are missing](#oe-claims-are-missing)
  * [User is created with unknown values](#user-is-created-with-unknown-values)
* [Operational Security Notes](#operational-security-notes)
* [Appendix](#appendix)
  * [Implementation Details for Onboarding Python Script](#implementation-details-for-onboarding-python-script)

### Overview

This section describes the operational procedure for federated authentication by connecting a Data Space Participant Authentik instance to the Data Space Operator Authentik.

The supplied federation model uses:

* **Data Space** **Participant Authentik** as the external Identity Provider;
* **Data Space** **Operator Authentik** as the central identity broker;
* OIDC discovery between Authentik instances;
* A central OAuth Source in the Operator;
* JIT enrollment based on invitations for the Operator shadow user;
* Source-property mappings for OE attributes.

### Directory Structure

 `user-management` repository additionally provides:

{% code overflow="wrap" %}

```
dataspace-operator/docker-compose/authentik/
    onboard_participant.sh
```

{% endcode %}

The above shell script calls 

```
dataspace-operator/docker-compose/authentik/scripts/
  dataspace_operator_add_participant.py
```

This script automates the creation or update of the Data Space Operator OAuth federation source and appends Participant redirect URIs to the central OIDC provider. 

For an implementation-oriented view, please consult the [Implementation Details for Onboarding Python Script](#implementation-details-for-onboarding-python-script) section.

### Sequence Flow

```mermaid
sequenceDiagram
    actor U as Data Space<br>Participant User
    participant P as Data Space<br>Participant Authentik
    participant O as Data Space<br>Operator Authentik
    participant A as OE Marketplace<br>SSI walt.id UI

    U->>A: Accesses graphical interface<br>and attempts to sign in
    A->>O: Requests OIDC discovery
    O->>U: Displays identity source
    U->>O: Selects Data Space<br>Participant source
    O->>P: Redirects to Data Space<br>Participant OIDC authorization endpoint
    U->>P: Authenticates with user credentials
    P->>O: Authorization response
    O->>O: Creates or updates shadow user claims
    O->>A: Issues central identity provider OIDC token
    A->>U: Authenticated session
```

{% hint style="info" %}
On first login, Data Space Operator creates a local shadow user and stores upstream identity metadata.
{% endhint %}

***

### Prerequisites

Before onboarding a Data Space Participant, verify the following:

#### On the Data Space Participant Side

The Data Space Participant Administrator must make sure the following&#x20;

* Data Space Participant Authentik is deployed and reachable.
* Data Space Participant Authentik uses a valid SSL certificate.
* Data Space Participant OE blueprint has been applied.
* Data Space Participant users can authenticate on the Data Space Participant Authentik instance.
* Data Space Participant provider exposes the OE JWT claims:
  * `orgId`
  * `walletId`
  * `signerServer`
  * `wellKnownUrl`
* Operational Administrator access is available by creating an initial setup account in Authentik.
* The Data Space Participant OIDC well-known configuration URL is reachable from the Data Space Operator environment.
* Checks if, within `/participant` directory, the JSON configuration file `config-for-onboarding-<participant_app_slug>.json` has been generated. \
  For detailed JSON configuration content, please consult [Prepare Participant Configuration on Data Space Operator](#prepare-participant-configuration-on-data-space-operator) section.

#### On the Data Space Operator Side

* Data Space Operator Authentik is deployed and reachable.

* The Dataspace Operator blueprint has been applied.

* The central OIDC provider exists.

* Data Space Operator Authentik Server contains the following artifacts after deploying the User Management Package:

  * `oe-central-federated-jit-enrollment`&#x20;

  <figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FDbzqZ6I15wcGVWbwtkcj%2FScreenshot%202026-09-04%20at%2019.45.51.png?alt=media&amp;token=56a93d65-ae3b-40e7-a8b1-9a2c70371f90" alt=""><figcaption></figcaption></figure>

  * `oe-central-federated-oidc-mapping` - this sets automatically `upstream_idp` claim within the JWT in federated authentication

  <figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FpDKQLDFIDJCKmFwP1fSf%2FScreenshot%202026-09-04%20at%2019.56.03.png?alt=media&amp;token=cec1e643-8d9f-4618-9429-bb685cb15a8f" alt=""><figcaption></figcaption></figure>

  &#x20;

  * `oe-authentication-flow`  - central authentication flow

    <figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FBKIe9XaCnLDmg5OoCxn0%2FScreenshot%202026-09-04%20at%2020.06.03.png?alt=media&amp;token=60c60eea-2abd-4cd2-8089-3b283f5c8a15" alt=""><figcaption></figcaption></figure>

    &#x20;

    * `oe-authentication-identification`  - central identification stage

    <figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2Fefzi30grsUoKCoT6pZwb%2FScreenshot%202026-09-04%20at%2020.08.11.png?alt=media&amp;token=67e25d4a-3ea6-4042-a20b-666ca5c4039a" alt=""><figcaption></figcaption></figure>

* Administrator- or container-level execution access is available for the onboarding script.

***

### Onboarding steps

{% hint style="warning" %}
The Data Space Participant initialization script generates a JSON file containing the configuration details of the Participant’s Authentik Server. The Data Space Operator **must receive this file from the Participant** before completing this procedure, as it provides the necessary parameters for integrating the Participant’s Identity Provider into the dataspace.
{% endhint %}

The User Management Package repository includes the participant onboarding script in the  `<user-management>/dataspace-operator/docker-compose/authentik/scripts` directory. This shell script accepts a JSON file ( `config-for-onboarding-<participant_app_slug>.json` ) with the following required keys:

```json
{
  "authentik_app_slug": "<participant-source-slug>",
  "participant_idp_consumer_key": "<participant-client-id>",
  "participant_idp_consumer_secret": "<participant-client-secret>",
  "participant_idp_well_known_url": "<participant-discovery-url>",
  "central_idp_provider_name": "<operator-central-provider-name>",
  "participant_redirect_uris": [
    "<redirect-uri-1>",
    "<redirect-uri-2>"
  ]
}
```

#### Field Description

<table><thead><tr><th width="300.36328125">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>authentik_app_slug</code></td><td><code>string</code></td><td>Application Slug used for the Operator OAuth federation source.</td></tr><tr><td><code>participant_idp_consumer_key</code></td><td><code>string</code></td><td>Client ID created on the Participant Authentik OIDC provider.</td></tr><tr><td><code>participant_idp_consumer_secret</code></td><td><code>string</code></td><td>Client secret created on the Participant Authentik OIDC provider. <strong>Treat it as sensitive information.</strong></td></tr><tr><td><code>participant_idp_well_known_url</code></td><td><code>string</code></td><td>Participant OIDC discovery endpoint.</td></tr><tr><td><code>central_idp_provider_name</code></td><td><code>string</code></td><td>Existing Data Space Operator OIDC provider whose redirect URI set is updated.</td></tr><tr><td><code>participant_redirect_uris</code></td><td><code>Array&#x3C;string></code></td><td>Redirect URIs that must be appended to the existing central provider without removing existing URIs.</td></tr></tbody></table>

***

#### Copy the Participant Configuration file on the Dataspace Operator Authentik Server

Copy the participant configuration file to the  `<user-management>/dataspace-operator/docker-compose/authentik/participant-configs` directory on the server that runs the Dataspace Operator Authentik server.

{% code overflow="wrap" %}

```bash
cp <participant-config-file.json> <user-management>/dataspace-operator/docker-compose/authentik/participant-configs/
```

{% endcode %}

#### Run the onboarding Script

From a terminal on the server that hosts the Data Space Operator Authentik server, run the onboarding script as follows:

```bash
 cd <user-management>/dataspace-operator/docker-compose/authentik/
 ./onboard-participant.sh <participant-config-file.json>
```

or

```bash
 bash onboard-participant.sh <participant-config=file.json>
```

***

### Verification

Perform the following verification steps:

#### Federated Authentication

1. Access Ocean Enterprise Marketplace in a browser as a Data Space Participant user, and click on **Login.**

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FcsHMMhO6KulS3EwUF7FP%2FScreenshot%202026-09-05%20at%2011.48.18.png?alt=media&amp;token=4631f0a7-d8b5-436d-848b-bee4ccd5e651" alt=""><figcaption></figcaption></figure>

2. Select **Login in to OE Marketplace**

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FQhebk8QKXxZg7zlqFjiH%2FScreenshot%202026-09-05%20at%2011.50.56.png?alt=media&amp;token=506e66d6-3283-4f78-855d-1c9840752d00" alt=""><figcaption></figcaption></figure>

3. Marketplace Interface forwards the login request to its Data Space Operator Authentik instance, and if the OAuth source has been added successfully, it will be displayed where it is highlighted in green in the screenshot below.

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FAevUVA9kcYHxSgxhBxwF%2FScreenshot%202026-09-05%20at%2011.55.34.png?alt=media&amp;token=899502e9-b1d2-4044-b989-d17b77e59279" alt="" width="375"><figcaption></figcaption></figure>

4. Select the correct authentication source for the dedicated Participant user and provide the credentials username or e-mail and password for the Participant user

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FjwcxSzAgTKtMR7OW9A0X%2FScreenshot%202026-09-05%20at%2012.53.17.png?alt=media&amp;token=bcbdc029-3e71-4568-b326-8eb24908d5b5" alt="" width="375"><figcaption></figcaption></figure>

#### Token Claims Verification

1. After logging in to OE Marketplace with the Participant OAuth source from the [Federated Authentication](#federated-authentication) section, the JWT token issued by the Data Space Operator can be retrieved from **Broswer's Application tab, under OE Marketplace Cookies,** if DevTools are installed on specific Browser.

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2F5YXe91OIhrHSKq3tddt5%2FScreenshot%202026-09-05%20at%2013.35.26.png?alt=media&amp;token=f32a49d3-3155-4300-adba-d8b59dee3404" alt=""><figcaption></figcaption></figure>

2. Inspect the token claims issued by the Operator to the OE application by accessing <https://www.jwt.io/> and paste encoded JWT token extracted from Cookies, from step 1.

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FpdnAB77zkBFRFrYEY3sI%2FScreenshot%202026-09-05%20at%2013.45.31.png?alt=media&amp;token=33562e54-d5c0-4cb8-a606-b6ac4a347ee0" alt=""><figcaption></figcaption></figure>

3. Verify the required OE claims according to the application's requested scopes in **the decoded payload:**

* `upstream_idp`
* `signerServer`
* `walletId`
* `wellKnownUrl`
* `orgId`
* `name`
* `email`

***

### Troubleshooting

This section targets common error resolution for Participant onboarding in the federated authentication procedure.&#x20;

It will be updated based on errors and issues encountered by organizations during deployment and operation.

#### Operator cannot fetch the Participant well-known URL

Check:

* DNS resolution;
* routing or firewall rules;
* TLS certificate;
* Participant Authentik availability;
* discovery URL correctness.

The repository script currently performs the discovery HTTP request for connectivity testing.

{% hint style="info" %}
Production operators should still deploy valid TLS certificates for the Authentik instance.
{% endhint %}

#### Federation source exists, but login is not offered

Verify that:

* the source is enabled;
* it is attached to the Operator Identification Stage;
* **source labels are enabled to be displayed in the Authentik login form;**

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2F4LN7XfeOAQFhb80tjvRj%2FScreenshot%202026-09-05%20at%2014.29.42.png?alt=media&amp;token=96993510-c059-4109-8dfb-2b615ac486d1" alt=""><figcaption></figcaption></figure>

* the authentication flow being used by the application is the expected flow.

#### OE claims are missing

Verify:

* the Participant user actually has `orgId`, `walletId`, `signerServer`, and `wellKnownUrl`;
* the Participant provider emits the corresponding scopes;
* the Operator OAuth source requests the corresponding scopes;
* the Operator source mapping copies the upstream values;
* the Operator provider exposes the claims required by the OE application.

#### User is created with unknown values

The current Operator mapping uses fallback values when upstream claims are absent. Treat `unknown*` values as a configuration error, not valid production identity data.

Correct the Participant scope within OAuth Source from **Federation and Social Login** and re-test authentication.

<figure><img src="https://1789397093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH0zpgrXbeZ7u6UuCV9Gz%2Fuploads%2FS7pLJBv1krG0XGelLfuQ%2FScreenshot%202026-09-05%20at%2014.32.52.png?alt=media&amp;token=dbd8d13b-3fa7-4853-bcac-2c5a50f1f4b3" alt=""><figcaption></figcaption></figure>

***

### Operational Security Notes

* Store Participant OAuth client secrets outside source control.
* Use unique OAuth credentials for each Participant.
* Use HTTPS and valid TLS certificates for both Authentik instances.

***

### Appendix

#### Implementation Details for Onboarding Python Script

1. Loads the Participant configuration JSON.
2. Validates that all required configuration keys are present.
3. Fetches the Participant OIDC discovery document.
4. Requires at least:
   * `authorization_endpoint`
   * `token_endpoint`
   * `jwks_uri`
5. Attempts to load the Participant JWKS.
6. Finds the configured Operator authentication flow.
7. Finds the central federated JIT enrollment flow.
8. Finds the central federated OIDC property mapping.
9. Creates or updates an Authentik `OAuthSource`.
10. Configures the source as OpenID Connect.
11. Configures the Participant client ID and secret.
12. Configures the Participant well-known URL and discovered OIDC endpoints.
13. Attaches the central OE OAuth Source property mapping.
14. Requests the OE scopes used by the federation.
15. Adds the source to the Operator authentication Identification Stage.
16. Enables source labels so users can select the Participant source.
17. Appends the supplied Participant redirect URIs to the existing central Operator OIDC provider while preserving existing redirect URIs.

{% hint style="info" %}
The script is designed to be idempotent at the source level: it gets or creates the source by slug and updates an existing source when one is already present.
{% endhint %}