Experimental

Database Scopes

Database Scopes are scopes stored in a data source and managed via a GraphQL API.

Database Scopes are experimental and their behavior, data schema, and configuration model may change in non-backwards-compatible ways in future versions of the Curity Identity Server.

For deployments with more than a few dozen scopes, or where it is desirable to perform scope management using an external system, OAuth Scopes may be stored in a compatible Data Source . These scopes are called Database Scopes and their management is done via the Database Clients GraphQL API API. Namely, creating, updating, or deleting Database Scopes does not require any configuration change.

Currently, Database Scopes can only be used with Database Clients or with Ephemeral Clients . Allowing or disallowing a Database Scope to be used by a specific Database Client or by any Ephemeral Client also doesn’t require a configuration change.

Database Scopes have the same properties as Configuration-based Scopes :

  • The name by which they are referred to in OAuth requests and responses.
  • Their textual description.
  • Whether the scope is required or not.
  • Whether the scope is exposed in the OAuth 2.0 and OIDC metadata or not.
  • Whether it is a prefix scope or not.
  • The scope’s time to live.
  • The optional Token Issuance Authorizer to control their usage.
  • The set of associated claims .

Database Scopes also have an extra property defining whether a Database Scope can be used by Ephemeral Clients.

Using with Database Clients#

To allow a Database Client to use a Database Scope, the scope’s name must be added to the Database Client’s scopes GraphQL field, via a Database Client GraphQL mutation. Note that Database Clients do not have a separate field for Database Scopes. They are managed via the same scopes field that already existed for Configuration-based Scopes. If a Configuration-based Scope exists with the same name as a Database Scope, then the properties of the Configuration-based Scope will be used instead. That is, Configuration-based Scopes override Database Scopes when they have the same name.

Using with Ephemeral Clients#

To allow Ephemeral Clients to use a given Database Scope, the following requirements need to be satisfied:

  • The configuration settings for Ephemeral Clients need to explicitly allow the usage of Database Scopes.
  • The given Database Scope must have the allowed_in_ephemeral_client field set to true.

By design, there isn’t a way to allow Ephemeral Clients to use any Database Scope via a configuration setting. Instead, the allowed Database Scopes need to have allowed_in_ephemeral_client set to true individually.

Enabling Database Scopes#

Database Scopes are stored in a compatible Data Source via Entity Managers that have Database Scope support.

To enable Database Scopes in a profile:

  1. Select or create an Entity Schema with Database Scope support. A new Entity Schema with this support can be created by running the Config Spec named “Creates or updates an entity schema to support database scopes”.

  2. Select or create a Data Source with entity storage support. Currently only the SQL-based Data Sources support entity storage.

  3. Select or create an Entity Manager configured with

    • an Entity Schema with Database Scope support,
    • and a Data Source with entity storage support.

  4. In the profile’s general settings, enable Database Scopes and provide the previous Entity Manager.

Managing Database Scopes#

Creating, reading, updating, and deleting Database Scopes is done via queries and mutations in the database-clients-graphql API.

The createDatabaseScope mutation creates a new Database Scope, given a set of fields.

input DatabaseScopeCreateFields {
    "The unique name of the scope."
    name: String!
    "An optional human readable description of the scope."
    description: String
    "The list of claims given when this scope is requested. It should be a subset of the claims configured in the profile."
    claims: [String!]
    "Optional ID of a configuration-defined authorizer that will be called when this scope is requested."
    token_issuance_authorizer: String
    "Prefix scopes enable clients to request scopes that are unknown at design time"
    is_prefix: Boolean
    "Lifetime of the scope in seconds."
    time_to_live: Long
    """
    Marking a scope as required means that it is required to be included in all tokens.
    If a client does not include a required scope in its request for a new token, the request will be rejected.
    """
    required: Boolean
    "Whether to include the scope in the OAuth/OIDC metadata."
    expose_in_metadata: Boolean
    "Whether ephemeral clients on the owning profile may request this scope. Requires `database-scopes` to be enabled on the ephemeral-client feature for the scope to be usable at request time."
    allowed_in_ephemeral_client: Boolean
}

Note that allowing a Database Scope to be used by a Database Client is done by mutating the Database Client and not the Database Scope.

The updateDatabaseScopeById and deleteDatabaseScopeById mutations update and delete a Database Scope, respectively.

The databaseScopeByName and databaseScopeById queries return a Database Scope given its name or ID, respectively, providing the following fields.

type DatabaseScope {
    "The unique identifier of the scope."
    id: ID!
    "The unique name of the scope."
    name: String!
    "An optional human readable description of the scope."
    description: String
    "The list of claims given when this scope is requested. It should be a subset of the claims configured in the profile."
    claims: [String!]!
    "Optional ID of a configuration-defined authorizer that will be called when this scope is requested."
    token_issuance_authorizer: String
    "Prefix scopes enable clients to request scopes that are unknown at design time"
    is_prefix: Boolean!
    "Lifetime of the scope in seconds."
    time_to_live: Long
    """
    Marking a scope as required means that it is required to be included in all tokens.
    If a client does not include a required scope in its request for a new token, the request will be rejected.
    """
    required: Boolean
    "Whether to include the scope in the OAuth/OIDC metadata."
    expose_in_metadata: Boolean
    "Whether ephemeral clients on the owning profile may request this scope."
    allowed_in_ephemeral_client: Boolean
    "Metadata related to this scope."
    meta: Meta
}

The databaseClientsByScopeId query provides paginated retrieval of all Database Clients that have a given scope assigned.

The databaseScopes query provides paginated retrieval of all Database Scopes, optionally filtered by a name prefix.

Current limitations#

Was this helpful?