Authentication and Authorization

The default way to Authenticate a user with in the Dossier Organizer application, is by using an OAuth 2 provider. OAuth is an open standard and there are Numerous public providers like Microsoft, Apple, Google, Amazon and many more. Alternatively you can also use closed and self Hosted solutions like KeyCloak.

Note: It is recommended to set a shorter lifetime for the OAuth tokens. Shorter token lifetimes reduce the risk of token misuse in case they are compromised. This ensures that even if a token is intercepted, it will only be valid for a limited period, minimizing potential damage.

Code Flow + PKCE

Dossier Organizer uses the Authorization Code Flow with PKCE (Proof Key for Code Exchange) as the OAuth 2.0 flow by default. This modern approach has replaced the deprecated Implicit Flow.

Setup

The First step will be to connect Dossier Organizer to the Oauth provider. For this process we need a few pieces of information form the third party system:

• A Client Id and/or client Id URI. To get This ID you need register a new client on your OAuth provider. Depending on your provider system this ID can be freely chosen, or it will be generated during the setup process. The setup varies depending on OAuth provider but will always entail an ID associated with the newly created client. The Client Id URI is only used when using Azure as an authentication provider.
• An OAuth Issuer is a named external system that provides identity and API access by issuing OAuth access tokens. The issuer should be referred to using a URL.
• A scope is a set of named "permission grants" which the user has to be able to access. These scopes are often managed by the organization and are used to Authenticate user groups on specific clients.
• A 'redirectUrl' is the URL to which the OAuth provider will redirect the user after successful authentication. Note that the redirect URL must be registered with the OAuth provider and must match it exactly to prevent attacks

After the Setup Process on the provider side this details have to be included in the deployment of Dossier Organizer using the Helm values. For an exact description on how to use the Helm Configuration please Refer to our Kubernetes deployment.

Access Control

As a basis Dossier Organizer will require a valid authentication to provide any service to a requesting user. Unauthenticated users have no access using the UI or any API endpoint. If using the provided UI the User will be prompted to log in, if the Authentication is not already present.

For a finer rights management, the fusion framework allows configuring so-called Authorization Policy files. These Authorization Policies allow restrictions based on:

• user roles
• permissions on resources
• permissions on actions

Authorization Policy Configuration

Authorization is implemented by defining AccessRules configuration file which restricts or allows access to specific functionality and resources of the product integration. These rules can be provided by adding them as additional files to the deployment. For further Information refer to the customization section.

As a default a simple Access Policy is provided that allows any authenticated user to access everything, if no other access policy is provided. This default policy is very basic and its definition can be used as an example:

{
    "_version": "1970-01-01",
    "validFrom": "1970-01-01T00:00:00.000+0000",
    "description": "Allow everything",
    "rules": [
        {
            "name": "Allow everything with claim resource_access.neverpile-fusion.roles contains 'reader'",
            "effect": "ALLOW",
            "resources": [ "*" ],
            "actions": [ "*" ],
            "subjects": [ "claim:resource_access['neverpile-fusion'].roles.contains('reader')" ]
        }
    ],
    "default_effect": "DENY"
}

If you want to implement a specific ruleset for your integration, feel free to contact our team at levigo, and we will help to create a matching configuration.

For more information about how to use Access policies please refer to the Access Policies Section

---

Azure AD (EntraID) Integration

To use Microsoft EntraID (Azure AD) as your OAuth provider, follow these steps:

1. App Registration in EntraID

1. Go to the Azure Portal.
2. Navigate to Azure Active Directory > App registrations > New registration.
3. Enter a name for your application.
4. Supported account types: Choose as required (e.g., Single tenant or Multitenant).
5. Redirect URI:
   • Set the type to Single-page application (SPA).
   • Enter your application's redirect URL (e.g., https://your-app.example.com/auth/callback).
   • You can add multiple redirect URIs if needed.

2. Expose an API & Set Application ID URI

1. In your app registration, go to Expose an API.

2. Click Set next to Application ID URI.

3. Enter a URI in the format:
   api://<Application (client) ID>

   Note: The <Application (client) ID> is the unique identifier assigned to your app registration by Azure AD. You can find it on the overview page of your app registration in the Azure Portal.

   or a custom URI, e.g.,
   api://3ac770fc-b878-4f7d-84f8-1442775f741f

4. Save your changes.

3. Configure Required Scope

1. Under Expose an API, click Add a scope.
2. For example, add the scope:
   user_impersonation

   Note: In Azure AD, a scope is a permission that an application can request from a user or another application. Scopes define what access levels are granted to the application.
   The most common scope for APIs is user_impersonation, which allows the signed-in user to access the API as themselves.
   You can also define custom scopes if your API requires more granular permissions.

3. Set the scope's display name and description as needed.
4. Save.

4. Manifest: Set accessTokenAcceptedVersion

1. Go to the Manifest tab of your app registration.
2. Find the property "accessTokenAcceptedVersion".
3. Set its value to 2:

   "accessTokenAcceptedVersion": 2,
4. Save the manifest.

5. Helm Values Configuration

In your Helm values, configure the OAuth section as follows (replace IDs and URLs as appropriate):

oauth:
  enabled: true
  clientId: "<client-id>" # Azure AD Application (client) ID
  appIdUri: "api://<client-id>" # Application ID URI set in Azure
  issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0" # Replace <tenant-id> with your Azure AD tenant ID
  scope: "api://<client-id>/user_impersonation" # Scope as defined in Azure
  redirectUri: "https://your-app.example.com/auth/callback" # Must match the SPA redirect URI registered in Azure

• Replace <client-id> with your Azure AD Application (client) ID.
• Replace <tenant-id> with your Azure AD tenant ID.
• The scope must match the one defined in your app registration.