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 the Administration UI or by 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 an Entity Manager with Database Scope support. Therefore, enabling Database Scopes in a profile requires selecting or creating an Entity Manager for this purpose.

The Administration UI contains a setup wizard that will guide the user through this process, including the creation of an Entity Schema if needed.

An alternative process is:

  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”; or by creating an Entity Schema via the Administration UI and then enabling Database Scopes on it.

  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#

Management of Database Scopes, including their relationships with Database Clients and Ephemeral Clients, can be done via the Administration UI:

  • The Token Profile Scopes page allows the creation, editing, and deletion of both Configuration-based Scopes and Database Scopes.
  • The Token Profile Ephemeral Clients page allows defining which Database Scopes can be used by an Ephemeral Client.
  • The edit page for any Database Client also allows the management of Configuration-based Scopes and Database Scopes allowed for that client.

Alternatively, creating, reading, updating, and deleting Database Scopes can be done via queries and mutations to 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 and/or a claim name. When both filters are provided, only scopes whose name starts with the given prefix and that contain the given claim are returned.

Current limitations#

Was this helpful?