Configuration#

Transactional configuration#

The Identity Server uses transactional configuration, which means that any change to config is treated as a transaction and will be validated and executed as an atomic operation. If the prepared configuration for some reason is invalid the transaction will abort.

The Administrator can choose to configure the system in any order, as long as all changes are performed in the same transaction. I.e. deleting an object and then deleting a reference to that object is as valid as the opposite procedure.

Rollbacks and history#

Every configuration change that is deployed will generate a rollback state. It is therefore possible to go back to any previous point in time and restore that configuration. When doing so a new rollback state is stored and can be used to go forward again in time.

It is also possible to rollback to a similar state, i.e. start with a rollback time but modifying it slightly before committing the change for deployment.

Factory default#

The Identity Server comes with a small factory default configuration. This configuration can be changed but not deleted. If there is a need to restore the server to a factory default state, see the section Factory Reset .

Mandatory, optional and default parameters#

Configuration settings come in a few different flavors. In the end each setting is a single value, but these are grouped together in list objects or singleton objects. Each value is defined to be in one of three states:

  • Mandatory - the value MUST be set for a valid configuration
  • Default - the value will be given a default value if not set
  • Optional - the value is not necessary to set

Configuration data vs operational data#

The Curity Identity Server configuration is divided into two main parts:

  • Configuration data - the data that defines how the server should behave
  • Operational data - data that is generated by the server at runtime, like tokens, sessions

Some types of data can be both configuration and operational, depending on how they are used. Clients can exist both in the configuration and in the database as operational data.

Operational data is managed through the DevOps Dashboard or the GraphQL and SCIM endpoints.

Configuration interfaces#

The Curity Identity Server comes with a number of configuration interfaces.

  • restconf
  • The Web UI
  • The DevOps Dashboard
  • The Command Line Interface

Depending on which interface that is used it’s important to note that the same transactional engine is used. However due to the way different protocols are defined the transactional feature is present in different ways. For the RESTful interface, each request will be encapsulated in its own transaction, due to the fact that a REST request should be stateless, and thus spanning a transaction over many requests would break this contract.

The Web UI will keep a transaction active until commit is clicked.

Configuration Schema#

The Identity Server configuration consists of these main parts:

  • Environment with Service-Roles - Runtime entities (nodes)
  • Profiles - Functions, like Authentication services, OAuth services etc.
  • Facilities - Shared components like Data Sources, Key Stores etc.
  • Processing - Procedures and managers that affect the runtime behavior
  • Access Management - Policies and rules for access control to the configuration

Profiles and Service-Roles are tied together through the concept of endpoints. An endpoint represents an HTTP URI that is defined by a profile and then enabled on a Service-Role.

Example

The Authentication service defines 3 important endpoints:

  • The Authentication Endpoint
  • The Registration Endpoint
  • The Activation Endpoint

The Administrator defines these endpoints on the profile. But in order for them to be active, they must be mapped to service-roles. It is possible to have the authentication endpoint on one service-role (node) and the others on another. It’s entirely up to the Administrator to decide how these should be distributed in the mapping step.

Profiles and services
Profiles and services

Profiles#

The profiles define the functionality of the Identity Server. Without profiles the server cannot do any tasks. Each profile looks different depending on what they define. The Authentication Service profile defines authentication related functionality, and the OAuth Service profile defines delegation related functionality.

All profiles share some basic traits. They all define endpoints a type and they reference token-issuers the same way.

A profile is located in the configuration at profiles/profile

Example

<profile xmlns="https://curity.se/ns/conf/base">
  <id>authentication</id>
  <type xmlns:auth="https://curity.se/ns/conf/profile/authentication">auth:authentication-service</type>
  <settings xmlns="https://curity.se/ns/conf/base">
    <authentication-service xmlns="https://curity.se/ns/conf/profile/authentication">
      <redirect-url-whitelist xmlns="https://curity.se/ns/conf/profile/authentication">
        <url xmlns="https://curity.se/ns/conf/profile/authentication">*</url>
      </redirect-url-whitelist>
      <sso-expiration-time>3600</sso-expiration-time>
      <username-cookie-name>username</username-cookie-name>
      <protocol-id>simpleapi1</protocol-id>
      ...
    </authentication-service>
  </settings>
  <endpoints xmlns="https://curity.se/ns/conf/base">
    <endpoint xmlns="https://curity.se/ns/conf/base">
      <id>authenticate</id>
      <uri>/authn/authenticate</uri>
      <endpoint-kind>auth-authenticated</endpoint-kind>
    </endpoint>
    <endpoint xmlns="https://curity.se/ns/conf/base">
      <id>register</id>
      <uri>/authn/register/create</uri>
      <endpoint-kind>auth-register</endpoint-kind>
    </endpoint>
  </endpoints>
  <token-issuers xmlns="https://curity.se/ns/conf/base">
    <custom-token-issuer xmlns="https://curity.se/ns/conf/base">
      <id>StandardNonceIssuer</id>
      <issuer-type>opaque</issuer-type>
      <purpose-type>nonce</purpose-type>
      <component>se.curity.identityserver.tokens.issuers.NonceTokenIssuer</component>
      <data-sources xmlns="https://curity.se/ns/conf/base">
        <delegations-data-source-id>DefaultHSQLDB</delegations-data-source-id>
        <tokens-data-source-id>DefaultHSQLDB</tokens-data-source-id>
      </data-sources>
      <jwt xmlns="https://curity.se/ns/conf/base">
        <algorithm>RS256</algorithm>
      </jwt>
      <opaque xmlns="https://curity.se/ns/conf/base">
        <reuse-delegation>true</reuse-delegation>
      </opaque>
    </custom-token-issuer>
    <default-token-issuer xmlns="https://curity.se/ns/conf/base">
      <use-jwt-access-token xmlns="https://curity.se/ns/conf/base">
        <signing-key-id>default-signing-key</signing-key-id>
        <algorithm>RS256</algorithm>
        <issuer>Std Issuer</issuer>
      </use-jwt-access-token>
      <default-data-source>DefaultHSQLDB</default-data-source>
    </default-token-issuer>
  </token-issuers>
</profile>

Endpoints#

The endpoints are defined in each profile. The profile has a number of endpoint types that it supports. Some profiles support multiple of the same type and some don’t. In the profile the endpoint is assigned a URI.

Example

<profile>
  ...
  <endpoint xmlns="https://curity.se/ns/conf/base">
    <id>authenticate</id>
    <uri>/authn/authenticate</uri>
    <endpoint-kind>auth-authenticated</endpoint-kind>
  </endpoint>
  ...
</profile>

This example defines the Authentication endpoint in the Authentication Profile. It sets the URI to /authn/authenticate which whenever the endpoint is deployed will be its path. It also defines an ID (a name) for the endpoint, which must be globally unique. This ID is later used to reference the endpoint.

Using Endpoints in Service Roles#

For an endpoint to be available for anyone to access, it must be assigned to a service role.

An endpoint will not be active until it’s been assigned to a Service Role.

In order to make an endpoint highly available, simply start multiple nodes with the same service role command line argument.

Example: Adding endpoint to Service using RESTCONF#

To add the endpoint defined in the example below, we need to add the ID of the endpoints to the node or nodes that should run it. This is done by adding another endpoint to the endpoints list on the Service Role.

Create an XML element with the ID of the endpoint:

<endpoints>authenticate</endpoints>

Store it in a file (or use stdin directly with curl). Then POST the data to the service-role endpoint to create the new entry in the endpoints list.

Example Request

POST /base:environments/environment/services/service-role/Role1 HTTP/1.1
Host: localhost
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/yang-data+xml

Corresponding curl request:

curl -i -v -u admin:Password1 -T ./endpoint.xml -X POST https://localhost:6749/admin/api/restconf/data/base:environments/environment/services/service-role=Role1 -H "Content-Type: application/yang-data+xml"

Example Response

HTTP/1.1 204 No Content

For more information about endpoints, refer to the online tutorial on the same topic.

Commit Hooks#

The Curity Identity Server provides a way to run scripts when a configuration transaction has been committed. This can be useful to run administrative tasks, such as logging, backup or sending external events. See the commit hooks section for details.

Was this helpful?