Skip to content

Authentication

This project implements secure and flexible authentication practices for both traditional and OpenID Connect (OIDC) Single Sign-On (SSO) workflows. The backend integrates the excellent Django-AllAuth package to handle user registration, login, password management, and third-party authentication providers.

Authentication Method

All API endpoints in Onconova require a valid, authenticated user session. Authentication is managed via a session token, which must be included in the X-SESSION-TOKEN HTTP header for every request.

A session token is issued by Django-AllAuth upon successful user authentication, whether through traditional username/email+password sign-in or supported Single Sign-On (SSO) providers. Requests that lack a valid session token, or include an expired or invalid token, will receive a 401 Unauthorized HTTP response.

Authorized users only

Onconova does not support anonymous or unauthenticated API access.

How to Authenticate

  1. Obtain a session token by logging in through the web interface or by using the API login endpoint: 

    POST /api/v1/auth/session

    Example JSON body: 

    {
    "username": "admin",
    "password": "your_password"
}

    Example response: 

    {
    "sessionToken": "eyJ0eXAiOiJKV1QiLCJh...",
    "accessToken": "...",
    "isAuthenticated": true
}

  2. Include the sessionToken value in the X-SESSION-TOKEN header in your subsequent API requests.

    Example Request with Token: 

    curl -X GET "https://onconova.example.com/api/patients/" \
    -H "X-SESSION-TOKEN: eyJ0eXAiOiJKV1QiLCJh..."

  1. Provide your credentials to your provider's OIDC authorization endpoint and follow their OIDC flow to obtain either an id_token or access_token value. Example request: 

    GET https://accounts.google.com/o/oauth2/v2/auth?...

    Example response: 

    {
    "id_token": "apJ2eXA52OivGlaKV1QiLC...",
}

  2. Obtain a session token by providing the id_token or access_token value, as well as other provider details, to the Onconova API interface: 

    POST /api/v1/auth/provider/session

    Example JSON body: 

    {
    "provider": "google",
    "token": {
        "client_id": "123.apps.googleusercontent.com",
        "id_token": "apJ2eXA52OivGlaKV1QiLC...",
        "access_token": "..."
    }
}

    Example response: 

    {
    "sessionToken": "eyJ0eXAiOiJKV1QiLCJh...",
    "accessToken": "...",
    "isAuthenticated": true
}

  3. Include the sessionToken value in the X-SESSION-TOKEN header in your subsequent API requests.

    Example Request with Token: 

    curl -X GET "https://onconova.example.com/api/patients/" \
    -H "X-SESSION-TOKEN: eyJ0eXAiOiJKV1QiLCJh..."

Token Expiration

Tokens are valid for a limited period or until manually revoked. After the expriration period, users must authenticate again to retrieve a new token.

Security Considerations

  • Always keep your session tokens secure.
  • Never expose API credentials or tokens in public code repositories.
  • Use HTTPS connections for all API calls. HTTP connections will be redirected to HTTPS by default.

SSO through Identity Providers

The project currently supports the following OIDC identity providers:

  • Google
  • Microsoft

Both are integrated using Django-AllAuth’s social account providers. To enable SSO with a specific identity provider, the Onconova application must first be registered with the provider to define access permissions, data scope, and user consent options. Upon successful registration, the provider will issue an Application (client) ID and a Client Secret. These credentials, along with any additional provider-specific configuration parameters, are required by Onconova to establish and manage the OIDC authentication workflow.

Supported OIDC Flows

The Onconova client currently supports OIDC authentication using ID tokens and Access tokens. The Authorization Code flow (involving the exchange of authorization codes) is not supported.

Client-only

OIDC authentication is enabled exclusively for client-side authentication in Onconova. API requests must be authenticated either via a traditional login or with an OIDC access token. Importantly, no provider credentials are uploaded to or stored within the Onconova server, identity verification is handled entirely through the client’s interaction with the identity provider.

Google

To enable Google SSO:

  1. Go to your organization's Google Cloud Console and navigate to the APIs and services page.

  2. Create an new OAuth 2.0 Client ID

    • Under Application type select Web application.
    • Add your Onconova domain to Authorised JavaScript origins.
    • Add the Onconova /auth/callback URL under Authorized redirect URLs: 
      https://your-onconova-domain/auth/callback
    • Create a Client Secret.

  3. Assign the Google Client ID to the ONCONOVA_GOOGLE_CLIENT_ID variable and the Client Secret to the ONCONOVA_GOOGLE_SECRET variable in the .env file. 

    ONCONOVA_GOOGLE_CLIENT_ID='694913361-005t3059...'
ONCONOVA_GOOGLE_SECRET='GOSFICPX-Iqr46NgX5...'

Microsoft

To enable Microsoft SSO through ID tokens:

  1. Go to your organization's Microsoft Entra admin center and navigate to the APIs and services page.

  2. Browse to Entra ID > App registrations > Onconova > Authentication.

  3. Under Platform configurations, select Add a platform. In the pane that opens, select Web for a web application.

  4. Under Redirect URIs, add the Onconova /auth/callback redirect URL: 

    https://your-onconova-domain/auth/callback

  5. Under Implicit grant and hybrid flows, select the ID tokens checkbox.

  6. Assign the Microsoft Client ID to the ONCONOVA_MICROSOFT_CLIENT_ID variable, the Client Secret to the ONCONOVA_MICROSOFT_SECRET variable, and the Tenant ID to the ONCONOVA_MICROSOFT_TENANT_ID variable in the .env file. 

    ONCONOVA_MICROSOFT_CLIENT_ID='694913361-005t3059...'
ONCONOVA_MICROSOFT_SECRET='GOSFICPX-Iqr46NgX5...'
ONCONOVA_MICROSOFT_TENANT_ID='16841664...'

Further reading

runner