Database Clients
Database Clients are clients whose settings are stored in a data source.
They are one of the types of clients the Curity Identity Server supports.
For deployments where the number of clients is higher than a few dozen, or where it is desirable to perform client management using an external system, OAuth clients may be stored in a compatible Data Source .
OAuth clients can be used to perform authorization flows in the Curity Identity Server in the exact same way regardless of whether they are Database Clients, Dynamic Clients or Configuration Clients.
To give the server a hint about a client being stored in a Data Source, prepend db- to the client_id.
That tells the Curity Identity Server to look for the client first in the configured Data Source, which helps avoiding conflicts with
configuration clients while potentially making it faster to find a database client.
Database Client VS DCR#
A related, but independent Curity feature is Dynamic Client Registration , which also allows storing clients in a Data Source.
Dynamic Client Registration Clients are based on the OpenID Connect Dynamic Client Registration specification, which limits the features that can be supported by both the API and by the actual clients in the Curity Identity Server.
Another difference is that Dynamic Client Registration attempts to support self-managing OAuth clients. It can be cumbersome to try and have centralized management of Dynamic Client Registration clients (which is possible through Dynamic Client Registration Management Clients). In other words, Dynamic Client Registration is not a general client management solution and does not integrate fully with Curity features.
Database Clients match more closely the Curity data model for configuring OAuth clients, allowing more Curity features to be utilized while enabling faster evolution of the API to support new use cases.
Enabling Database Clients#
To enable Database Clients:
- configure a Data Source in the Token Service
- create an endpoint of type Database Client GraphQL API in the Token Service
- configure authorization access for the GraphQL API (not required if only the Dashboard is used)
If authorization access is configured in the Token Service, the Database Clients GraphQL API will become available for external applications to manage clients. Otherwise, the only way to manage Database Clients is through the DevOps Dashboard (which must be configured to allow access to Database Clients).
Modifying clients directly in the database instead of using the GraphQL API or the DevOps Dashboard can cause the clients to become invalid, and hence inaccessible from the Curity Identity Server.
Removing Curity configuration that is used by Database Clients (e.g. encryption keys, authenticators) without updating the affected clients may also cause problems. Care must be taken to update Curity configuration and Database Clients in tandem to make sure there is always consistency between them.
Configuring a Data Source#
The first thing to do to enable Database Clients is to configure a Data Source for storing clients in each Token Service Profile.
In the Admin UI, you can find the Database Clients section under the Token Service’s General page:
Admin UI → Profiles → Oauth → Oauth Dev → Client Settings
Enable Database Clients and select a Data Source.
Only Data Sources that support Database Clients can be selected (an error occurs if the selected Data Sources doesn’t).
Create a Database Client Endpoint#
The next step is to enable the GraphQL API Endpoint, which can be done in the Admin UI:
Admin UI → Profiles → Oauth → Oauth Dev → Endpoints
Add a new endpoint of type oauth-client-graphql-api.
Authorization Access#
For the GraphQL API to be usable without the DevOps Dashboard , it is necessary to configure an appropriate Authorization Manager in the relevant Token Service which can authorize users to access the API.
Not all Authorization Managers support GraphQL APIs. As of writing, the Groups Authorization Manager and Attribute Authorization Manager have full support for Database Clients.
When only managing Database Clients via the Devops Dashboard, this step is not necessary.
Managing Database Clients in the DevOps Dashboard#
To make Database Clients accessible via the DevOps Dashboard , so that clients can be managed easily via a simple User Interface, after enabling Database Clients (as explained in the previous section), ensure that Client access is allowed in the Dashboard Settings.
The Token Service’s Authorization Manager is not used by the DevOps Dashboard! In fact, it is not necessary to configure one in order to manage Database Clients via the DevOps Dashboard - only the Dashboard authorization settings apply when authorizing the Dashboard client.
Example:
Configuring Clients#
Database clients have nearly the same configuration model as configuration clients.
See Client Configuration for details about the OAuth client’s data model. Check also the GraphQL schema which can be obtained with any GraphQL Tool by pointing it at the configured endpoint URL.
The GraphQL API is self-documented. Check the GraphQL APIs documentation for more information about using Curity’s GraphQL APIs and obtaining the full GraphQL schema.
Upon any operation on a database client, warnings can be returned. They are reporting issues that should be better to address, but that did not prevent the requested operation to succeed. They are returned in the database client’s metadata, in the warnings field.
Database Client Limitations#
Even though Database Clients are nearly identical in functionality to Configuration Clients, there are a few differences as noted below:
- when used in scripts, the
propertiesfield always returns an empty object. UsetypedPropertiesinstead. - Database Clients cannot be selected as DCR Client Templates or used for DCRM.
See also the notes on the Mutual TLS Documentation about Database Client’s certificates.