General Concepts

As you may have gleaned from the getting started guide, the Curity Identity Server is comprised of three separate parts:

  1. The admin service
  2. The run-time service
  3. The configuration service

The first two are controlled through the idsvr command while the third is a separate process that is started automatically and supervised by the first. When the admin node is not also a run-time node, all it does is monitor and manage the configuration service; it does not expose any endpoints or listening ports. The configuration service that it spawns, however, exposes a number of northbound endpoints that are used to configure all nodes:

  • Management Graphical User Interface (GUI)
  • Command Line Interface (CLI)
  • SSHD (for remote administration via the CLI)

When a run-time node (or an admin node that also services request, as described in the getting started guide) starts, it immediately subscribes for configuration changes that relate to it (which is why it must identify itself in the or on the command line). Whenever one of these northbound APIs is used to change configuration related to a run-time node, the new configuration will be pushed (not pulled using a polling process) to the appropriate run-time node. Without any downtime, the node is reconfigured and all new requests will use the new configuration while old requests finish using the previous configuration. This dynamic configurability of run-time nodes allows administrators to mange the entire deployment as a whole and from a single point. From this central position, administrators can view, update, rollback, version control, and restore old configuration. All changes to configuration are done in a single transaction, allowing administrators to make several (dozens or even 100s of changes) and commit them all as a whole (at a scheduled time perhaps). In the walkthrough, you will see how this can be done with ease.

Roles of the Curity Identity Server

Based on this configuration, every run-time instance of the Curity Identity Server will assume a certain role within Identity Management System (IMS). The possible roles include:

  1. Authentication Server: The login or authentication service which is the single authority for identifying users.
  2. Security Token Server: the service that is in charge of issuing tokens according to the OAuth and OpenID Connect (OIDC) standards.
  3. Profile Server: The service that is the facade in front of an Identity Repository (e.g., a relational database or directory).

The Curity Authentication Server can be thought of web site that does login. It integrates with applications in various ways using various protocols, making it simple to retrofit into existing applications and to use it with new ones. It manages authentication and provides Single Sign-on (SSO) across disparate Web and mobile apps. The Curity Authentication Server does not store any identities itself, and it is built in a way that it can log users in regardless of where those users are stored. Before a user can login, they must have an account. To this end, the Curity Authentication Server provides users with a self-service functionality where they can sign up for access. Identities can be verified manually or automatically via email. Registration inputs can be validated using JavaScript which allows developers to ensure that all inputs are valid according to your company’s requirements; these scripts are dynamically executed server side in a performant and safe manner. As users create new accounts and multiple authentication methods are enabled, the need quickly arises for some sort of stable and consistent identifier or ID that represents the user. To this end, the Curity Authentication Server supports the notion of account linking. Based upon configuration, certain identities can be linked or associated with each other. After a user has proven possession of multiple accounts, they can be linked, providing the application with that stable user ID.

A Security Token Server is essential for providing both Web application and Web service security. To meet the need for mobile experiences and to facilitate microservices architectures, Web services or Web Application Programming Interfaces (APIs) are essential. To provide access via these networked endpoints, the service must reliably know who is at the other end of the wire. To this end, the Curity Security Token Server issues tokens that represent an end user after he or she has authenticated themselves. The Curity Security Token Server does not actually perform the authentication – a task left to an Authentication Server; instead, it exchanges this initial identity for a new one encoded in the form of a signed token. This token is delivered to apps via the OAuth and OIDC standards. Once the app obtains such a token, it can make secure API calls with them. By so doing, the API will verify the authenticity and trustworthiness of the token and grant access to the data if the user is authorized.

The Curity Security Token Server provides a number of features that you would expect from any Security Token Server which supports OAuth and OIDC. For example, the Curity Security Token Server support all of the standard OAuth flows (e.g., the implicit, resource owner credentials, and authorization code flows); it also supports lesser-known flows like the assisted token flow and the device flow. The former is a simplification of the implicit flow and greatly simplifies integration while simultaneously making the app integration more secure. These various flows or message exchange patterns can be implemented using various open and closed source frameworks, making it easy to retrieve tokens from the Curity Security Token Server.

To meet the needs of complex deployments, the Curity Security Token Server also supports a very flexible and rich JavaScript-based token issuance language. This allows developers to write logic that runs server-side in the product. When a token is retrieved, validated, refreshed or exchanged, the appropriate script is executed. Because the language is imperative, developers can use normal programming techniques to stipulate what data should be in the tokens issues by the Curity Security Token Server, including loops, conditions, etc. This token data can be arbitrarily deep, allowing tokens to contain other tokens to any level necessary. All of these JavaScript procedures are validated at configuration time and pushed out to the appropriate run-time nodes which pre-compile them before executing them during token issuance. This technique ensures that scripts are syntactically correct, providing developers with quick feedback about programming mistakes.

While the Curity Authentication Server allows users to register for new accounts during authentication, organizations often need to provide users with a means to manage their profile outside of the login process. To this end, the Curity Profile Server provides profile management as a Web service API (which is protected by tokens issued by the Curity Security Token Server). The API itself conforms to the SCIM protocol, a standard specified by the IETF which is the same international standards body that also authored the OAuth, TLS, and HTTP standards. This API provides the ability to modify users, facilitating basic Create, Read, Update, and Delete (CRUD) operations. As with the other roles of the Curity Identity Server, the Curity Profile Server does not house or store any identities. Instead, the Curity Profile Server can be configured to use various identity repositories. These can include Relational Database Systems (RDBMS), other SCIM services (e.g., Windows Azure Active Directory), and LDAP (e.g., Active Directory). A growing list of RDBMS are supported, including HSQL (for testing and development), MariaDB (e.g., as provided by Amazon RDS), MySQL, SQL Server, Postgres, Oracle and CockroachDB. The API also makes it easy to integrate user management capabilities into existing web sites, Customer Relationship Management (CRM) systems, and customer care portals where Customer Service Representatives (CSRs) need to make changes on a user’s behalf.


Based on configuration, a run-time node will assume one or more of the above roles. Each of these roles and the related configuration is stipulated in what is referred to as a profile. A profile is a central concept to the Curity Identity Server. It is essentially an instance of an Authentication Server, a Security Token Server or a Profile Server. Multiple profile instances can be configured of the same type. For example, you can create an Security Token Server profile for employees that has different client applications than a profile that should only be used with customers. You could also create an Authentication Server profile that only allows for login to one particular app using one particular authentication method; you could then make this restricted profile available to a certain partner that uses this single app. Each profile not only contains the apps (or clients or service providers) that should use it, but also the server on which the profile is executed. Each profile contains a set of endpoints; these endpoints can be completely arbitrary, allowing an OAuth Security Token Server profile to serve tokens from /zort and an Authentication Server profile to authenticate users from /foo. This and the ability to designate profiles to certain servers makes it very easy to limit and obfuscate the endpoints as needed to meet certain situations. For example, in the previously mentioned example with a partner that should only be able to login to a certain app with a particular authentication method. If this app was integrated using OpenID Connect, then two profiles would be created – an authentication profile and an token service profile. Both of these profiles could be assigned to a server called The endpoints might all be prefixed with the partner name, resulting in endpoints like, and For more background information on this topic, refer to the tutorial about endpoints on the developer portal.

In this way, profiles are used in the Curity Identity Server to wrap configuration together into a unit. This unit is also what is used at runtime to decide which components should be used to handle the request.

A Smorgasbord of Plug-ins

Architecturally speaking, the Curity Identity Server is made up of a number of pluggable components. The engine itself is relatively small, and, based on a node’s centrally-defined configuration, certain plug-ins are loaded and used to handle requests made to each particular node. It is important to understand what kind of plug-ins exists and how they fit together, as this will provide an good overview of the product’s capabilities. The supported types of plug-ins include the following:

Authorization Managers
A component that determines if access to certain resources should be allowed or not. This component is responsible for deciding if a request should be approved or not. All Authorization Managers make these decisions using information about the authenticated user (i.e., the subject), the resource being requested, the action being performed on that resource (e.g., delete, update, etc.), and the context or environmental situation (e.g., time of day, whether or not it is snowing outside, etc.). This allows Authorization Managers to perform Attribute-based Access Control (ABAC) to determine if access should be allowed or not. Authorization Managers are usable from OAuth and OpenID Connect token issuance procedures as well as in user management actions in the Curity Profile Server. The Curity Identity Server ships with a scope-based Authorization Manager that considers only the scopes of an OAuth Access Token (AT) presented to an API (e.g., the SCIM 2.0 Users endpoint).
The Curity Authentication Server, which handles login and related tasks in the Curity Identity Server, all components that perform authentication are doing using various plug-ins known as Authenticators. An Authenticator may be as simple as redirecting the user to a social network like Facebook and handling the response; or, it may be more complicated, collecting various inputs from a user and showing numerous screens and calling various back-end services. Authenticators can be grouped into arbitrary groups, and authentication can be performed by any of those in the group. Any Authenticator can be configured to have a previous one run first, allowing Authenticators to be chained in any way. This allows the Curity Identity Server to provide not only 2-factor authentication but true multi-factor authentication. For a complete list of the supported Authenticators and more about how they work, refer to the Authentication Service Admin Guide.
Authenticator Filters
The Curity Identity Server as supports another kind of plug-in called Authenticator Filters. An Authenticator Filter is a component that can remove or filter out an Authenticator from the view of the user. Authenticators are configured to be shown per Curity Identity Server instance, or more accurately, per-profile. This list can be pered down based on the application that makes the request. For example, an OAuth Security Token Server profile might enable 3 Authenticators: Facebook, BankID, SMS 2-factor authentication, and smart cards. For a certain OAuth client that requires higher levels of assurance that the user really is who they say they are, however, the Facebook Authenticator should not be shown, only the MFA Authenticators. This subset will be shown to all users when no other inputs are given to the Curity Identity Server stipulating otherwise. For users of mobile devices, however, it does not make sense to present them with an option to login with a smart card, as no mainstream mobile devices has a smart card reader. So, even if the smart card Authenticator is allowed for the OAuth client application, it should not be presented to the user. An Authenticator Filter can be configured for this app, so that it will not be shown. The Curity Identity Server supports various Authenticator Filters including one that can filter Authenticators based on the client IP address (using CIDR rules), the user agent string of the browser being used, and a JavaScript-based filter than can query back-end Data Sources and other repositories to determine if a user should be shown a certain Authenticator or not. Authenticator Filters are always run even when Authenticators are chained together, making it easy to support scenarios where certain authentication methods should not be possible depending on the previous authentication factors.
Integration Protocols
The Curity Identity Server is designed to easily integrate with other computer systems, both within an existing IMS and beyond it. This is done using the various protocols it supports, including SCIM, OAuth, OpenID Connect, and others. The Curity Authentication Server, which is the only profile of the product that does any user authenticate, is designed to be used not only by the other roles of the Curity Identity Server but non-Curity products. To this end, it can integrate with various standard and non-standard protocols. For instance, the Curity Authentication Server supports PingFederate’s agentless integration protocol and SAML. It also supports a simple browser-based integration protocol (which is used by the Curity Security Token Server) which allows applications to integrate very easily. SAML support allows the Curity Authentication Server to be used as an Authentication Server for various federation servers like Active Directory Federation Services (AD FS) from Microsoft, IBM Tivoli, CA Single Sign-On (PKA SiteMinder), and other applications that support SAML (e.g., Office 365). Which protocol is used is, like all plug-ins, just a bit of configuration that can be changed at any time.
Data Sources
Many aspects of the Curity Identity Server require access to identity data. Data is needed to check credentials input by a user, values are needed for inclusion in tokens, values are needed for an Authorization Manager to authorize a request, and data must be stored when a user registers for a new account. The use cases that require data within an IMS are numerous. To address all of these use cases, the Curity Identity Server included a type of plug-in called a Data Source. These plug-ins get, update, modify and delete user-related data. The Curity Identity Server includes Data Sources that can communicate with a simple JSON Web service; more complex Web services that implement SCIM 1.1 or 2.0; LDAP directories like ApacheDS, OpenLDAP, and Active Directory; and RDBMS like MariaDB, MySQL, SQL Server, Postgres, Oracle or CockroachDB. In some deployments, only one of these Data Sources will be used while in others numerous ones will be employed to solve the use cases at hand. Through flexible configuration, new Data Sources can be created used by any profile of the Curity Identity Server that needs them.
Attribute Transformers
Often, back-end identity repositories do not store the data in the format that applications needs; sometimes a query to an LDAP server returns missing or incomplete information; and other times more data is needed before issuing a token after a user logs in under certain conditions. To transform, augment, and remove data, the Curity Identity Server provides a class of plug-ins calls Attribute Transformers. These can be used with any Authenticator and are executed after that Authenticator identifies a user. Attribute Transformers plug-ins include the regex transformer, a tabular database table transformer, and a JavaScript transformer that allows for complete flexibility in what and how attributes looks after a certain Authenticator is executed. By coupling an Attribute Transformer to an Authenticator via configuration, multiple transformations can be performed when Authenticators are chained together. When tokens are issued, Attribute Transformers can be used to enrich the token data; this can be useful as tokens are often issued long after authentication has taken place.
Account Managers
When users are allowed to register during the login process, a pluggable Account Manager governs the account-related data. This Account Manager uses a Data Source for CRUD purposes, but there is often more to account management then simple CRUD. For example, the credential may be stored in some other identity repository than the account. This is often the case when the account-related data is in a CRM while the password is in an LDAP directory. Also, if account linking is used, the linking between accounts might be offloaded to a different RDBMS than where the account data is kept. For new use cases like mobile authentication, which devices are associated with a user might not be able to be stored in the same repository as the account because modifying the legacy storage system with this novel device-related data might be too onerous. Therefore, an Account Manager brings together the representation of a user account from various back-end identity repositories. This greatly simplifies the integration of the Curity Identity Server into existing operations and allows it to solve very complex user-account-related use cases.
Credential Managers
A credential or proof of identity can be stored in various types of identity repositories. They can also be hashed in those back-ends to avoid exposure if that entire data store is stolen. In some cases, it is possible to send the un-hashed form to the back-end and it will compare the results, but other identity repositories require the credential to be hashed before transmission. When the client must hash the credential, some require SHA-1, others SHA-256, or some other hashing algorithm. Sometimes, despite an overwhelming amount of advice against it, the credential might be stored in plain text within the identity repository. All of this disparity is obscured from all aspects of the Curity Identity Server by a class of plug-ins called Credential Managers. A Credential Manager is in charge of checking a password by pre-hashing it with a certain algorithm as needed or to leave it unchanged, so the back-end repository can do that work. In addition, Credential Managers perform other CRUD on credentials only. When a new user account is created by an Account Manager, it is actually a Credential Manager that stores it. This allows the account-related data and the password to be housed in separate data sources if necessary. The Curity Identity Server includes Credential Managers that perform hashing using the SHA-256, SHA-512, BCrypt and PHPass algorithms as well as a Credential Manager that does not perform any hashing. Credential Managers are used not only with account management but also in OAuth flows that accept a credential directly (e.g., the Client Credentials flow and the Resource Owner Password Credentials flow).
SMS Providers
The Curity Identity Server needs to send SMS text messages on occasion. This need usually arises after a user selects an Authenticator that sends a text message to perform MFA. This need can also arise when a user registers a new account, and their identity needs to be confirmed by sending a text message to a pre-set phone number. In any case, the Curity Identity Server does not use only one SMS gateway, but the configured SMS Provider plug-in. This class of plug-in is responsible for sending text messages to a given phone number. How it does this is completely transparent to the engine itself. Currently, the only supported SMS Provider is the Twilio SMS Provider. Using this Twilio plug-in, you can deliver SMS text messages to thousands of carriers in dozens of countries around the world.

Using these plug-ins together, many scenarios can be implemented. Almost all of these involve authentication in some way, so it good to acquaint yourself with the authentication capabilities of the Curity Identity Server.


Authentication is a really big part of any IMS, perhaps the biggest. Authentication is the process of confirming the identity of some entity. In other words, it is the task of answer the question “Who are you?” How this determination is done varies widely. In the Curity Identity Server, there are two general authentication use cases:

  1. Cases where a user is directly involved, clicking buttons, making selections, enter input, etc. In these situations, the interaction can be quite dynamic. These cases are generally performed in a web browser or a browser view embedded in a mobile application. Concrete examples of this type of use case are when a user logins in via Facebook, register for a new account, signs in using a mobile authentication app, or is automatically logged in using an SSO session.
  2. Situations where the user is not directly involved. These are typically cases where an automated client is communicating with the Curity Identity Server on behalf of an end user. Specific examples of this case are when the OAuth resource owner credentials flow is used to get a token directly from the Curity Security Token Server’s token endpoint or when a SCIM 2.0 request is sent to the Curity Profile Server to update a user’s profile.

As the worth of the data that a user is trying to access increases, so does the risk associated with misidentifying that user or authenticating them incorrectly. If the value of the requested resource is very low, getting a right answer to the question “who are you?” is not as important as when the resource is very valuable. Therefore, the accuracy of the authentication method or the strength of the credential that is used to authenticate a user will be proportional to the value of the resource. It may be OK for a low-value resource to be accessed after authenticating a user with a very strong credential, but the converse is almost never the case; granting access to high-worth data after a user logs in with a very weak credential exposes your organization to risk. It is important, therefore, that users authenticate themselves using the right methods under the right circumstances.

To this end, the Curity Identity Server provides a number of options for login, and a number of ways to select and control these choices. Most of them relate to the first case mentioned above when the user is directly involved; this is due to the dynamism of such interactions. For example, the Curity Authentication Server provides numerous Authenticators; all of these can be configured and used or, more typically, a subset of them can be setup. Just because some are configured, however, doesn’t mean that they should all be available in every situation. As described above, it is very common to restrict certain Authenticators based on the application that is requesting authentication. Take, for example, an intranet Web site. For such an app, the only authentication method that should be allowed is Integrated Windows Authentication (IWA) when the user is on the local network. In such cases, the user is known to have logged in to their workstation with a corporate account because only domain-joined PCs can connect to the local network. Under such circumstances, it is not necessary and quite annoying for the user to have to authenticate them self again. By configuring an instance of the IWA Authenticator and allowing this intranet app to use it (via configuration), employees on the network will receive a better user experience.

When such personnel take their laptops home, however, they may not be on the same network, preventing IWA from working. In such cases, it is usual for the employee to be prompted to enter their AD credentials into a Web-based form as well as a second factor of authentication using a hardware token, software token, or by entering a one-time code sent to them via SMS. The Curity Authentication Server can easily implement this use case. To do this, you should configure an Authenticator for the second factor, like SMS 2-FA Authenticator. As with all Authenticators, this one can require a previous Authenticator to run first. This could be an instance of HTML form Authenticator, for instance. The HTML form Authenticator needs an Account Manager to be configured. This Account Manager in turn needs a Data Source. If that Data Source is an LDAP one that is configured to communicate with AD, home workers will firstly be prompted to enter their AD credentials in a Web form, and then receive an SMS with a one-time usage code. The phone number to which this code is sent can be looked up in AD, but it can also be found in a different Data Source, like a RDBMS, because the Data Source of the two Authenticators are configured independently, enabling both simple and advanced implementations of this use case.

In this example, the intranet app uses three Authenticators: IWA, SMS 2FA, and an HTML form Authenticator. Because the SMS 2FA Authenticator instance requires the HTML form Authenticator instance to run first, they will manifest themselves as two choices to the user:


Fig. 2 Authenticator selection page using default styling

This type of Authenticator selector page is always shown to the user when multiple Authenticators are configured and there is not enough inputs in the request to narrow down the selection to just one. If only one Authenticator is configured or the inputs are given to reduce the number of selections to just one, the user will not see this screen. While the above screenshot shows how this page would normally look, it is possible to change the appearance for all apps or even just this intranet app. Rather than customizing it, however, it would be better in this use case if it were not shown at all. The easiest way to do this in this case would be to use an Authenticator Filter. The Curity Authentication Server includes an Authenticator Filter that can filter out Authenticators based on the IP address of the client. If the client’s IP address is not one from the local intranet, the Classless Inter-Domain Routing (CIDR) Authenticator Filter can be used to remove the IWA Authenticator. After which, the user will not see the authenticator selector page because the number of allowed Authenticators has been slimmed down to just one. Instead, the user will be prompted with an HTML form where they can enter their AD credentials:


Fig. 3 HTML Authenticator that is automatically show

Likewise, another instance of the CIDR Authenticator Filter can be used to determine if the user is within the corporate network. If they are, the HTML form Authenticator can be filtered out, thus reducing the number of allowed Authenticators to just one – the IWA Authenticator instance. Then, the Authenticator selector screen will not be shown, and IWA will log the user in directly without any prompt.

Usually, the Curity Identity Server will be used with a number of different applications. While this fictitious intranet application requires these types of authentication, they probably aren’t applicable for an application used by end customers. Imagine an organization’s web site. Imagine it requires users to login under certain circumstances. When a prospective customer visits the Web site, they can probably visit a lot of the site anonymously. Under certain circumstances, some form of identification might be needed. For example, if the prospective customer signs up for a newsletter, or coupons, or other low-value resources, a simple username/password might be acceptable. Because users often reuse these credentials across sites, it might be more secure and easier for the user to let them login with their Google or Facebook account. For such an application, the allowed Authenticators would be instances of the Facebook, Google Authenticator, and the HTML form Authenticator (but a different instance then the one used with the intranet app). In this case, the user would be presented with three login options when they visit this app without a session[1]:


Fig. 4 Alternative Authenticator selection page

Because this is a different app requesting login, the authentication methods that are available to the user are not the same ones from that of the fictitious intranet application. (They of course could be if so configured, but this isn’t a plausible setup.)

Authentication Method Usage

In the examples above, you may be wondering how the Curity Authentication Server determined which authentication methods to present to the user. It is done by an application identifier that is provided in the request, typically on the query string. What is stopping the user from changing that, you may now wonder? Nothing! How then will the app know that its authentication requirements were met? In those cases where the actual authentication method that was used must be made known to the application, the Curity Identity Server provides this information is what is know as an Authentication Class context Reference (ACR). An ACR is provided in the login token issued by the Curity Authentication Server and can also be included in tokens issued by the Curity Security Token Server. Sometimes tokens will be issued by the Curity Security Token Server hours, days or even weeks after the user logged in. Even in such cases, the original authentication method that was used can be determined by the application using the ARC in the token. (The authentication time can also be determined from information in the token.) This allows the application to decide if a newer, fresher authentication of the end user is needed.

Application often need a way to inform the Curity Identity Server about their requirements that a user authenticates using a certain methods, a particular Authenticator. This is also done using ACRs. In the request that an application sends to the Curity Identity Server is may include this information. This set of ACRs must correspond to a subset of the configured Authenticators that are allowed for the application. An ACR that corresponds to any unknown or disallowed Authenticator will be ignored. In any event, the Authenticator that is used will be communicated back to the application in the ACR of the token. This will allow the app to check that its authentication requirements were satisfied. Using the ACR like this is how things like step-up authentication can be implemented in the Curity Identity Server.

By default, an ACR has a standard format:


This value can be changed per Authenticator to whatever string value is desired.


Another important concept that is used throughout the Curity Identity Server is scripting. The Curity Identity Server provides a unique and powerful JavaScript-based scripting engine that is used in the product to perform various tasks. Most of these can be done without resorting to scripting, but the possibility and power exists when needed. The types of things that can be done with scripting include:

  • Validation of registration form inputs
  • Issuing tokens
  • Introspecting tokens
  • Refreshing tokens
  • Filtering out certain Authenticators
  • Transforming attribute values
  • Authorize certain actions like token issuance
  • React to Server Events with custom logic

Every script is given a run-time context. This context contains information about the calling client, the request parameters, the configured data sources and Authorization Managers, the configured token issuers, and other things. Each script can also use globally defined scripts that allow you create reusable libraries of functions. All scripts have access to a console object that can log information at run time which is logged in the regular server log; logging can be enabled or disabled for certain scripts or for all. To enable logging for a certain script only, a logger named se.curity.identityserver.scripting.token_procedure.<procedure-name> (where <procedure-name> is the ID of the script) should be configured in the log4j2.xml file located in $IDSVR_HOME/etc. To enable logging for all scripts, including global ones, a logger named se.curity.identityserver.scripting.token_procedure should be enabled at the DEBUG level.

Scripts are configuration like any other setting. When an administrator enters a script using any of the northbound APIs described above, they are validated. Only if the script parses will it be accepted as valid configuration data. If it does, it will be replicated to the appropriate run-time which will pre-compile it into byte code before making use of it. This ensures that the script is correct and optimized before it is used to service any requests.

For more information on scripting, refer to the scripting guide.

What’s Next?

There are many more concepts that you will need to learn about, like SSO, the types of tokens, various flows, etc. These will be covered in the various guides included with this overview guide. Refer to them for more details or walkthrough some common scenarios to gain some first hand experience with these concepts.

[1]Again, every pixel of this view can be customized as desired