Zayd Anderson
Oct 14, 2023

Managing Users and Access In Sonador

User identity management and access control are essential to ensuring data security. Sonador uses OpenID connect and oAuth2 to provide access to imaging resources. This article describes how those systems are implemented and walks through the process of enabling security and configuring Single Sign On.

User identity management and access control (sometimes called IAM), are two of the most complex aspects of creating secure software. Even so, they are essential to ensuring that sensitive data remains protected.

There are two main challenges that IAM systems attempt to solve:

  • Authentication: ensuring that a user is who they claim to be. There are many ways for a user to prove their identity: authentication using usernames/passwords, entering the values of one-time PINs (perhaps sent to a mobile phone), providing biometric information, verifying the answers to security questions, and many others. The job of authentication software is to ensure that authentication is secure and hackers are unable to compromise the system. Once authenticated, IAM software then ensures that every request and interaction is associated with a trusted identity.
  • Authorization: determine what resources a user may access. Through the use of access controls, policies, and roles; authorization systems ensure that users are only able to see and modify data for which they have the correct permissions.

In any IAM system, there are many moving pieces and it is easy to make a mistake. Because of the challenges, the security community has published guidelines and best practices that can help application developers secure their data. One emerging pattern is to split authentication and authorization into separate concerns and then use centralized systems (sometimes called an Identity Providers or IdPs) to handle authentication, and a protocol (such as OpenID Connect or SAML) to allow for a "client application" to verify the identity of users. Robust authorization can then be built on top of this external "security service." There are several benefits to this approach:

  • it allows better integration into large organizations via Single Sign On (SSO), allowing users to use the same credentials for every system in the business rather than requiring them to memorize multiple usernames and passwords
  • improved breach mitigation in the case of an account being compromised, as there is only a single place required to disable access across the whole organization
  • the security service can help with regulatory compliance by providing an audit trail which tracks when users access specific applications

The Sonador Medical Imaging platform follows this pattern and uses an external IdP to verify user identity. Authorization is managed using an internal group based permission system (with the option to sync those groups with the IdP). In this blog post, we'll look at how security is implemented in Sonador and discuss the fundamental components for the authentication of users and authorization of API requests.

  • First, we'll review the specifics of how the Sonador web application coordinates authentication workflows and the interacting components needed to issue an "access token" via the OpenID Connect (OIDC) "access code" workflow.
  • Next, we'll discuss the steps needed to configure an "OpenID Provider" and "Authentication Server" to take advantage of Single Sign On (SSO) capabilities.
  • Finally, we'll demonstrate how to configure and test AWS Cognito as an IdP.

Overview of Security in Sonador

Sonador's data storage system (called Sonador IO) is composed of a set of microservices which interact to securely store medical images so that they can be queried, retrieved, and transferred. There are three primary components:

  • Sonador Web Application: provides user and group management, role based access control, authentication/authorization workflows, service discovery, centralized configuration of imaging servers, and integration APIs.
  • Orthanc: medical imaging database used for indexing and storing medical imaging resources.
  • OHIF: web-based viewer with support for a wide range of modalities (MRI, CT, ultrasound, X-ray, and more), 2D/3D visualization, segmentation (DICOM-SEG) and structured reporting (DICOM-SR), and whole slide imaging.

The Sonador web application is the central security hub and provides authentication (via an external IdP and OIDC) and authorization services. OHIF, Orthanc, and third party applications use the web app to retrieve access tokens and authorize requests. Examples of how these systems work include:

  • Authentication: OHIF uses a Sonador mediated OIDC access code workflow (additional details below) for obtaining oAuth2 access tokens to retrieve imaging resources. These "bearer" tokens are attached to requests sent to Orthanc and other systems as proof of identity.
  • Authorization: Orthanc (via the advanced authorization plugin) communicates with Sonador's "introspection" API to validate API tokens. The token is forwarded to Sonador, which determines which user the token is associated with, verifies that the token is valid, and authorizes (or denies) the request.

Core Concepts

To make all of this work, the Sonador web app uses a number of interacting components:

  • User: a person or service account that needs access to application resources.
  • Group: a collection of users that share common properties and are used to attach permissions to collections of resources.
  • Applications: things that users log into. In OpenID Connect, applications are registered with an IdP, and verified using a "client ID" and "client secret." A Sonador deployment is an application.
  • Scope: set of information (such as a username and email) that the application needs to create an account for the user. The requested scopes are part of the application registration on the IdP..
  • OpenID Provider: profile that describes an IdP service used by Sonador. It includes the endpoints needed to execute security workflows and custom logic to parse responses. Example providers include Google Connect, Azure AD, AWS Cognito, and Oak-Tree Acorn. OpenID Providers are managed from within Sonador.
  • Authentication Server: stores the application identifiers (client ID and client secret) which link the Sonador instance and the IdP that will be used for authentication. Authentication servers are always associated with an OpenID Provider.
  • Imaging Server: Orthanc instance containing resources which a user may attempt to retrieve. Resource permissions in Sonador are associated with a group and attached to imaging servers.
  • Access Tokens: credential obtained from Sonador after successful authentication which are used to make requests on behalf of a user. Access tokens in Sonador are JSON Web Tokens (JWT) tied to a "user session" that are cryptographically signed to ensure their validity.

Seen from a high level: Sonador uses an external IdP (such as Keycloak, AWS Cognito, Google Identity Platform, Azure Active Directory, FusionAuth, Okta, or Acorn) to verify a user's identity and issue an access token. The IdP is aware of Sonador and will authorize users on its behalf because Sonador was registered at some point in the past as an application and is able to provide a known client ID and matching secret. The workflow required to orchestrate the entire process is defined by an OpenID Provider and authentication server. As part of the authentication workflow, Sonador will create internal users matching the details provided by the IdP which can then be added to groups which determine what resources the user can access.

Sonador uses the OpenID Connect "access code flow" to authenticate users and allow access to imaging resources. Integrated applications, such as the OHIF Viewer, can initiate authentication workflows which enable them to authenticate via external identity providers and obtain access tokens. Once the viewer has obtained an access token, it is able to make secure requests on a user's behalf.

OpenID Connect (OIDC)

The workflow reponsible for authenticating users in Sonador and issuing access tokens is called the "authorization code flow" and is shown in the figure above. It is redirect based and keeps client credentials private.

  1. The workflow is initaited when the user navigates to the OHIF viewer (or another integrated application) that does not have an access token. The viewer will detect the lack of credentials and redirects to the Sonador web app (step in the 1 figure above).
  2. The Sonador web app initates the login process by creating a URL for the IdP which includes the application client ID, requested scopes, "local state," and a Sonador URL to which the IdP should redirect after successful auth; and forwards the user to the IdP for authentication (step 3).
  3. When the user arrives on the IdP, it will check the application client ID to ensure that Sonador is registered and will then prompt the user for credentials (step 4). If the user provides valid credentials, the IdP will redirect the user back to the viewer with an "ID" or "authorization" code (step 5).
  4. Next, the viewer submits a request to Sonador using the ID code and requests an access token (step 6). When it receives the ID code, Sonador will make a direct request to the IdP in order to verify the ID code (step 7). If the code is valid, Sonador will return an access token that can be used by the viewer to request imaging resources from Orthanc and other systems within Sonador (step 8).

Resource Access Control

Access tokens in Sonador are associated with a specific user account, tied to a session, limited in duration, and cryptographically signed to ensure that they have not been tampered with. Sonador's "introspection" API is used by Orthanc (and other external applications) to submit validation requests, which are then authorized or denied based on what resources are requested and the permissions associated with the user account.

The primary way that permissions are assigned to users is through the use of an access control list (ACL) associated with a group and imaging server. Sonador has limited support for "roles," but these are normally only used for administrative or system accounts (additional detail below). The ACL indicates what resources on the imaging server members of the group are able to access or modify. If users are not members of a group with the needed permissions to access or modify a resource, the authorization request will be denied and Orthanc will block the operation. Users can be added or removed from a group using the Sonador administration console, and changes take effect immediately.

Sonador Auth: Configure Medical Imaging Server Permissions
Access to medical image resources are managed on a per server basis by associating a group with resource permissions using the "Medical Images" panel of the Sonador admin console. Users will only see imaging servers associated with groups of which they are members.
Sonador Auth: Assigning User to Groups
In Sonador, group membership is assiged in the "Users" panel. A user may be a member of as many groups as needed for their role.
Role Based Access

Within Sonador there are two special roles that can be assigned to users: "staff" and "superuser."

  • The "staff" permission gives access to backend APIs and the administrative console, but not to medical imaging resources. Even though staff users have access to the Sonador admin console, they are limited to viewing/modifying configuration options for which they have been explicitly authorized.
  • The "superuser" permission grants access to all resources managed by Sonador including configuration, medical imaging resources, and data services. In practice, it should only be granted to administrative and system accounts.

Configure Cognito as an Identity Provider for SSO

When first deployed, Sonador provides access for "database" users (usually configured using the createsuperuser command), which are local accounts intended for backend administration. Database users are only able to authenticate via the Sonador admin console.

To enable outside users to authenticate to Sonador, you must configure an IdP, OpenID Provider, and Auth Server. In this section, we'll walk step-by-step through the process to configure AWS Cognito as an IdP. The general steps we need to follow are:

  • Create a user pool in Cognito which manages the users who will authenticate to Sonador. Cognito supports social and enterprise federation, which allows for users to sign in through social media accounts like Apple, Google, or Facebook; or through enterprise systems such as LDAP. How to configure federated login using Cognito is beyond the scope of this article.
  • Configure the Sonador application details in Cognito.
  • Configure the Cognito instance as an Identity Provider in Sonador.
  • Link the two together with an Auth Server and determine correct redirect URIs to register with Cognito.
  • Create a user in Cognito and test.

Step 1: Create Cognito User Pool

Cognito instances are managed using the AWS Console. To load the Cognito panel, log into your AWS account and search for "Cognito."

Sonador Auth: AWS Console Cognito
The tools for manging Cognito instances and user pools are available through the AWS Console.

To create a user pool click on "Manage User Pools" and then click on "Create a User Pool." Follow the instructions to provide a name and other base settings for the pool and to configure the login/security options as needed for your application. Ignore the "App Client" and "Triggers" sections for now, we'll return to these in a later step.

Once the pool has been created, take note of the Pool ID, Pool ARN, and region the pool was created in. These identifiers are needed for configuring Sonador.

Step 2: Configure Sonador as an App Client in Cognito

Now that you have a user pool, the next step is to configure Sonador as an OpenID application in Cognito. To access the application settings, click on the "App clients" link in the sidebar.

Sonador Auth: AWS Cognito Navigation for "App Clients"

When the "App clients" pane loads, click on the “Add an app client” button. You will be prompted to create a name for your app client and to enter a "refresh token" time. Make sure the "generate client secret" option is selected and that the Username and Password sections in the "Auth Flows Configuration" section are selected (in addition to any other options you would like to have enabled).

To create the application, click on the "Create app client" button.

After the client application is generated, make note of the "App client id" and "app client secret." The ID and secret will be needed to configure Sonador.

Sonador Auth: AWS Cognito App Details
Example configuration for Cognito OpenID application. The "App client id" and "App client secret" are used to configure the authentication server in Sonador.

Step 3: Create Cognito DNS

To use the newly created Cognito instance, you need a DNS domain for your app. This allows for Sonador to route authentication API calls and for users to authenticate.

To create the domain, click on the "Domain name" link under the "App Integration" section of the sidebar which will load the Domain management panel. The panel will prompt you to create a domain name, check it's availability, and confirm it.

When finished, click on the "Save Settings" button.

Sonador Auth/Cognito: Configure Domain
Example Cognito domain configuration. The Cognito domain will be used by Sonador to initiate the OIDC authentication workflow, so it is important the domain be routable by both the Sonador web app and users' browsers.

Important: At this point, the Cognito configuration is incomplete and requires details from Sonador (such as the callback URLs) before it will work. These will be added in a later step.

Step 4: Configure Sonador OpenID Provider

Log into to your Sonador instance admin and navigate to the "Social Media Application OpenID Providers" section and click "Add a Social Media Application OpenID Provider".

Sonador Auth: Create new OpenID Provider
OpenID Providers are comprised of a set of endpoints and logic needed to interact with OIDC compatible IdPs. They are created from the "Social Media Application OpenID Providers" section of the Sonador admin console.

In the "Add Social Media Application Authorization Provider" panel, populate the settings with the following options:

  • Name: Cognito
  • Scheme: https
  • Hostname: hostname that you created earlier. Example:
  • Port: 443
  • Description: description of the provider. Example: "Cognito Sonador test provider"
  • Authorization Endpoint: /oauth2/authorize
  • Token Endpoint: /oauth2/token
  • Revoke Token Endpoint: /oauth2/revoke
  • User Endpoint: /oauth2/userInfo
  • Login Control Class List: cognito aws login
Sonador Auth: Configure OpenID Provider Connection Components
Sample OpenID Provider connection settings.
Sonador Auth: Configure OpenID Provider Endpoints
Sample OpenID Provider endpoint settings.

Then, add the following code snippets to provide the parsing logic for the Cognito provider.

Retrieve Authorization Token
def get_authorization_token(instance, url_redirect, code):
    """ Retrieve authorization token from Cognito using the provided access code
    # Prepare request data
    rdata = instance._authorization_token_request_data(url_redirect, code)
        'client_id': instance.client_id,
        'grant_type': "authorization_code",

        rauth = server_request_post(server_controlurl(instance, instance.endpoint_token), 
            rdata, headers={
                'Content-Type': 'application/x-www-form-urlencoded'
            auth=(instance.client_id, instance.client_secret), json_data=False)
        authtoken_data = server_controloperation_json_response(rauth)
    except Exception as err:
        raise Exception('%s\n%s' % (getattr(err, "details", None), rdata))

    # Ensure that the token includes a token type
    if not authtoken_data.get(instance.authtoken_class.access_token_type_attr):
        authtoken_data[instance.authtoken_class.access_token_type_attr] = 'bearer'

    return instance.authtoken_class(instance, authtoken_data)
Revoke Authorization Token
def revoke_authorization_token(instance, access_token, token_type):
     """ Revoke the provided access token
Retrieve Service User
def get_user(instance, access_token):
    """ Retrieve the user associated with the provided access token
    # Retrieve user data from the graph API
    userdata = server_controloperation_get(
        server_controlurl(instance, instance.endpoint_user), headers={
            "Authorization": "Bearer %s" % access_token.access_token

    # The social user classes require a username as the unique identifier
    # so annotate username from the response if not present
    if not userdata.get('username'):
        userdata['username'] = userdata.get('preffered_username')

    # Retrieve first and last name
    if not userdata.get("first_name"):
        userdata['first_name'] = userdata.get('given_name')
    if not userdata.get('last_name'):
        userdata['last_name'] = userdata.get('last_name')

    return instance.user_class(instance, userdata)

Click on the "Save" button to create the OpenID Provider.

Step 5: Link Sonador and Cognito via an Authentication Server

Once the OpenID Provider is created, the next step is to create an "Authentication Server" that will link Cognito and the Sonador instance. To create an Authentication Server, click on the "Authentication Servers" link under the "Authentication and Authorization" section in the admin console. Then click on the "Add Auth Server" button.

Sonador Auth : Create a new Auth Server
Auth Servers store application settings and link Sonador to an IdP. They are created from the "Authentication Servers" section of the Sonador admin console.

Add the following settings:

  • Provider: select the Cognito provider that you created in the previous step.
  • Description: description of the authentication server. Example: "Cognito test server".
  • Provider Client ID: Cognito application client ID created earlier.
  • Secret Key: Cognito application secret key created earlier.

Check the box that says "Default," and click "Save." Note: If you will be configuring other applications, such as a standalone build of OHIF, to utilize the Auth Server; populate the Redirect URL input with the desired callback URLs (one per each line). Refer to "Configuring Sonador to Allow for Remote OHIF Development" for additional information.

Sonador Auth: Configure Authentication Server
Sample Sonador auth server settings.

After the auth server is saved, it will return you to the Auth Server management panel. Locate the server instance you just created and take note of the auth server token which appears in the first column of the server list (next to provider column). This value uniquely identifies the server and is used in Sonador OIDC URLs such as the login and callback URL.

Sonador Auth: Auth Server Callback URLs
To complete the OpenID application registration in Cognito, it's necessary to provide a "callback URL." This value can be retrieved from the "Authentication Management" panel in the Sonador admin console.

Copy the "OpenID Callback URL" from the second to the last column. It will follow the general pattern of /auth/openid/{{ authserver-id }}/callback, example: /auth/openid/g9NtlrXqwhJyxH0b/callback. This value is needed to finish the application registration in Cognito.

Step 6: Add Sonador OIDC Callback URL to Cognito Configuration

Because OIDC uses redirects to pass sensitive information, it requires a white list of URLs to which it is authorized to send traffic. This prevents a hacker from hijacking one of the redirects and intercepting sensitive information such as the client ID or an access code.

To register the callback URL for the Auth Server created in the previous step, navigate to Cognito and click on the "App Client Settings" link under the "App Integration" section. Then in the "Callback URL(s)" box, add the fully qualified URL for the callback endpoint. It will have the general form: {{ scheme }}://{{ sonador-url}}:{{ port }}/auth/openid/{{ authserver-id }}/callback. Example: https://imaging.local:8870/auth/openid/g9NtlrXqwhJyxH0b/callback.

Important: the callback URL registered in Cognito must match that generated by Sonador exactly. If the Sonador instance is using the standard https port of 443, it is not necessary to include the port in the URL. Cognito only supports https URLs.

Place the callback URL in the "Sign out URL(s)" box in addition to the "Callback URL(s)" box and click "Save Settings" to apply the changes.

Sonador Auth: Configure Cognito Auth URLs
Sample Cognito app client settings including callback and signout URLs.

Important: Sonador dynamically generates its callback URL using the domain entered under "Sites" and the settings from the Site-Connection section of the site config. If you encounter errors while testing in the next step, review the domain entered in the Sites panel of the Sonador admin and the SITE_CONNECT_PORT / SITE_CONNECT_SCHEME settings of the config file. For https domains (which is required by Cognito) the SITE_CONNECT_MATCH_SITE_SCHEME and SITE_CONNECT_MATCH_SITE_NETLOC options must also be enabled.

The listing below shows the Site-Connect section of the site config for the Sonador instance in this article.


SITE_CONNECT_SCHEME = 'https' # Site connection scheme (production)
SITE_CONNECT_PORT = '8870' # If different from http/https defaults (80/443)
SITE_CONNECT_SCHEME_DEVEL = 'https' # Connection connection scheme (development)
SITE_CONNECT_PORT_DEVEL = '8870' # Connection port (development)
BASE_URL = 'https://imaging.local:8870'


Step 6: Create Cognito User and Test Integration

Once Cognito has been configured as an IdP, an OpenID Provider has been created, and Sonador/Cognito are linked using an Auth Server; it is possible to test the configuration.

In Cognito, navigate to the "Users and Groups" tab and create a test user.

Then, open a new tab and navigate to the frontend (viewer) URL of Sonador. If everything is configured correctly, you will be redirected to a Cognito login page to provide your credentials. Upon successful authentication you be redirected a second time back to the Sonador OHIF viewer.

Sonador Auth/Cognito: Test Step 1. Navigate to Sonador URL.
Step 1: Navigate to the Sonador frontend (viewer) URL
Sonador Auth/Cognito: Test Step 2. Provide test credentials.
Step 2: Authenticate with Cognito credentials
Hello Sonador AI (Chest X-Ray): Patient List
Step 3: Redirect to OHIF viewer
Zayd Anderson Oct 14, 2023
More Articles by Zayd Anderson


Unable to find related content


Unable to retrieve data due to an error
No results found
Back to All Comments