Overview

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. This means that 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 interfaces

The Identity Server comes with a number of configuration interfaces.

  • RESTCONF API
  • The Web UI (from version 1.0)
  • The Identity Server CLI (from version 1.0)

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 it’s 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 save is pressed.

The Identity Server configuration consists of 2 main parts

  • Service-Roles - Runtime entities (nodes)
  • Profiles - Functions, like Authentication services, OAuth services etc.

These are tied together through a 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.

../_images/ProfilesAndServices.png

Service Roles

A Service Role is defined as a mode a runtime node runs in. It is possible to configure a service-role without the corresponding runtime node actually being running, a concept called pre-provisioning. When the actual node (the jvm) wakes up, it connects to the admin node, and receives the configuration that is defined for that particular instance. The service-role a runtime node should execute as is provided via the -s command line argument (or in the startup.properties) when starting the idsvr process on the machine.

A typical service configuration has the following form

<service-role>
        <id>Runtime</id>
        <location>Lab</location>
        <enabled>true</enabled>
        <listening-host>0.0.0.0</listening-host>
        <listening-port>8443</listening-port>
        <protocol>https</protocol>
        <ssl-server-keystore>server-key-1</ssl-server-keystore>
        <endpoints>authenticate</endpoints>
        <endpoints>register</endpoints>
</service-role>

Important

The service-role is located in the configuration at: /environments/environment/services/service-role{id}

The available parameters for a service are

class service
id(string, mandatory)

The given name of the service-role

location(string, optional)

An optional location, describing where the node can be found. For the administrator’s use.

enabled(boolean, default true)

If the node should be enabled or disabled.

listening-host(host, default 0.0.0.0)

The host on which the node should be accepting HTTP requests

listening-port(uint16, default 8443)

The port on which the node should be accepting HTTP requests

protocol(enumeration, default https)

Either http or https. WARNING: http is only available for development use!

ssl-server-keystore(ref, mandatory if https is used)

A pointer to an ssl-server-keystore that should be used as the SSL Server key

endpoints(ref, multiple)

The endpoints that should be available on this service. This attribute can be repeated.

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.

Important

A profile is located in the configuration at /profiles/profile{id type}

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>
class 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 it’s 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.

Note

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.

POST /environments/environment/services/service-role=(string: id)

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.