Common Scenarios

If you read through the getting started and the general concepts guides, you should hopefully have the big picture of how the Curity Identity Server can be used within an Identity Management System (IMS), you should also have it running, and be acquainted with the general concepts. To help solidify those concepts, it would be good to walkthrough some common scenarios that the Curity Identity Server can solve. There is a lot more that it can do then what is covered in this guide, but this will give you a good start.

Important

In order to perform this walk through, you will need a license key for the Curity Identity Server. If you do not have one, contact sales by sending an email to info@curity.io.

Login

Let’s start simple and just login. We won’t login to an app or anything to start with; we’ll just see if we can create an account and enter a username/password.

Authentication Profile

As mentioned in the general concepts guide, one of the most central ideas in the Curity Identity Server is that of a profile. A profile groups together a set of configuration as it relates to one of the roles that the Curity Identity Server can assume. You can have multiple profiles of any type running in the same instance of the product. If it helps, you can think of a profile like a virtual host in a web server. In such a web server, each virtual host or web site has configuration for things like the SSL key, the root directory, default document type, etc. Each of these sites can have different settings, but the same web server hosts them all. This is similar to how the Curity Identity Server hosts various profiles. Each profile has different settings and the same server can host them all.

To solve this very basic and common case of login, we need to create a new authentication profile. This can be done using any of the management interfaces, but this guide will show only the Web UI. Assuming this was enabled during installation, it should be accessible at https://localhost:6749/admin. Login using the username admin and the password that was also set during installation.

../_images/login.png

Fig. 5 The admin GUI login prompt

To add a new authentication profile after logging in, do the following:

  1. From the Authentication tab click New Profile

    ../_images/create-authn-profile.png

    Fig. 6 Starting the new authentication profile wizard in the admin GUI

This opens a wizard that will guide you through the process of creating a new authentication profile.

  1. On the first screen, enter a name, for instance authentication or test1-authn and a URL prefix, like authn or test1. The URL prefix will be prepended to the URL endpoints in this profile.

    ../_images/create-authn-profile-wizard-page1.png

    Fig. 7 Setting the name and URL prefix of the new authentication profile

    Click Next.

  2. For now, leave the SMS Service option blank, and click the Create button beside the Data Store dropdown.

    ../_images/create-auth-profile-wizard-create-service-page.png

    Fig. 8 Selecting to add a new data source in the service page of the wizard

    This will start a subflow where you can define a connection to a data store which houses user accounts.

  3. In the Create Data Source modal dialogue box, enter a name for the new data source, e.g., DefaultDataSource or NewDataSource.

    ../_images/new-data-source-name.png

    Fig. 9 Naming the new data source in the authentication wizard

    Then, click Create.

  4. The modal will expand and you can enter more information about the data source. With jdbc selected from the Type dropdown list, enter the following information:

    Field Name Configuration Value
    Connection String jdbc:hsqldb:file:${se.curity:identity-server:db};ifexists=true;hsqldb.lock_file=false
    Driver org.hsqldb.jdbc.JDBCDriver
    Username SA

    Click Close at the bottom of the modal to return to the wizard. The new data source should be slected from the dropdown list. Click Next to proceed to the subsequent step in the wizard.

  5. On the Signing Keys page, select Generate New Key. Enter a Common Name, for example, test1, and click Next:

    ../_images/new-signing-key.png

    Fig. 10 Generating a new signing key for the authentication profile

  6. Skip over the deployment page by clicking Next since there are no run-time nodes configured yet.

  7. On the Integration Protocol page, select Curity Token Service and select Next.

    ../_images/integration-protocol.png

    Fig. 11 Selecting an integration protocol that will connect the Curity Authentication Server to the Curity Security Token Server

  8. On the final screen of the wizard, select Commit to persist the configuration changes and make them live.

    ../_images/commit-page.png

    Fig. 12 Committing the changes created by the new authentication profile wizard

At this point, a new data source has been created. That will store the user accounts, and, for this tutorial at least, can also be used for other needs – like token storage. A new authentication profile has also been added. Next, we’ll host that profile somewhere by adding a run-time service configuration.

Configuring a Service

All requests are handled by a service. A service is a node that hosts configuration stored in the configuration database that is specific for it. To do this, a run-time node needs to identify itself when subscribing with the configuration service for configuration changes. A run-time node identifies itself and makes this subscription when it starts. You can see this in the logs of the node that you have been starting:

Trying to connect to node-local configuration service at 127.0.0.1:6789 using the service …role=admin

The service ID of admin is stored in the $IDSVR_HOME/etc/startup.properties file, but it can also be specified on the command line as the Curity Identity Server is started using this -s or --server-id options.

At this point, the service admin is not hosting any profiles; it is only an admin node, not a run-time node. We can assign it a profile though, and then it will start responding to request. To do this, follow these steps in the admin UI:

  1. Go to System -> Deployments.

    ../_images/services.png

    Fig. 13 The deployment page with no services define

  2. Click New Server button.

  3. In the Create New Server modal dialogue that pops up, enter admin as the name of the new node.

    ../_images/new-service-name.png

    Fig. 14 Setting a name for a new service

    Then, click Next.

  4. In the Create New Server dialogue, select the SSL certificate that was created by the installer.

    ../_images/create-new-service.png

    Fig. 15 Configuring the setting of a new service

  5. Click the Change button to add endpoints to the new service node. The Update Endpoints dialogue will come up:

    ../_images/change-endpoints-on-new-service.png

    Fig. 16 Adding the endpoints of the previously created authentication profile to the new node

    Other settings can also be configured in this dialogue if desired by clicking the Show Advanced Settings.

  6. Finally, hit Select All to add all endpoints to the node. Then, close the dialogue by clicking the X in the toolbar at the top.

  7. To activate the configuration changes, click Changes -> Commit. Optionally, enter a commit comment and click OK.

  8. To confirm that the endpoint was added to the admin service, run this command that uses the REST API:

    Listing 5 Getting the settings of the newly created service named admin
    $ curl -k -u admin:Password1 \
        "https://localhost:6749/admin/api/rest/running/environments/environment/services/service/admin?with-defaults"
    

    The output should be as follows:

    Listing 6 The service configuration, including default values encoded as XML
    <service xmlns="https://curity.se/ns/conf/base" xmlns:y="http://tail-f.com/ns/rest"
            xmlns:base="https://curity.se/ns/conf/base">
        <id>admin</id>
        <enabled>true</enabled>
        <listening-host>0.0.0.0</listening-host>
        <listening-port>8443</listening-port>
        <protocol>http</protocol>
        <endpoints>test1-anonymous</endpoints>
        <endpoints>test1-authenticate</endpoints>
        <endpoints>test1-registration</endpoints>
    </service>
    
  9. Surf to the authenticate endpoint which should now be available at http://localhost:8443/test1/authentication. When you view this page, you will receive an HTTP server 500 error like this:

    ../_images/after-adding-service.png

    Fig. 17 An error shown after adding a service because no Authenticators are configured

    If you check the server log, you’ll find this message:

    Can not respond to authentication request without authenticators. The profile configuration must be finalized by adding authenticators.

So at this point, we need to configure an Authenticator.

See also

For more information about how to configure endpoints and how to use them with services, refer to the Using Endpoints in Service Roles section of the Configuration Guide.

Defining an Authenticator

As described in the general concepts section of this guide, an Authenticator is the component or plug-in that authenticates a user. There are various kinds that can be used to authenticate users in various ways such as:

  • With a social identity (e.g., Facebook)
  • Via a one-time code that is emailed or sent via SMS
  • By checking a credential in a back-end web service, directory, or database

The steps to setup an Authenticator in that last way using a database is described next.

Important

The Curity Identity Server does not store any user accounts. It is always integrated with some sort of identity repository. It supports integration with these using SQL, LDAP, SCIM 1.1 and SCIM 2.0.

HSQL Data Source

For testing purposes, the Curity Identity Server ships with HSQLDB, an embedded, relational database (AKA HyperSQL or just HSQL for short). This isn’t meant to be used in production, but allows you to quickly setup a test repository for user accounts. Once you have this working, you will be able to use it an HTML form Authenticator to login. The data source created when running the authentication profile wizard can be used for this. To confirm that it was configured correctly, check the Facilities view or by executing this REST API command:

Listing 7 Retrieving the currently configured Data Sources
$ curl -k -u admin:Password1 -H "Accept: application/vnd.yang.data+json" \
    "https://localhost:6749/admin/api/rest/running/facilities/data-sources?deep"

Create a Credential Manager

With the Data Source in hand, identities can be verified against the stored values using a Credential Manager. As explained in the general concepts section of this guide, a Credential Manager is the entity that verifies credentials. The difference between a Credential Manager and a Data Source is that a Credential Manager is in charge of Create, Read, Update and Delete (CRUD) for credentials whereas a Data Source is a more general component that can get identity data of all sorts and for various purposes. A Credential Manager may also perform algorithmic operations on the inputs that are received from the back-end Data Source. This allows a Credential Manager, for example, to get an hashed value from a back-end Data Source, hash the un-hashed input provided by a user, and compare the results. Credential Managers can use any Data Source, making this sort of application-level logic more broadly available.

To configure a new Credential Manager that uses the HSQL Data Source, do the following in the admin UI:

  1. Click Facilities in the top-right corner of the screen.

  2. Next to the Credentials Managers heading, click New.

  3. In the Create Credential Manager modal dialogue box, enter a name, e.g., DefaultCredentialManager or Tenant1CredentialManager. Then, click Close.

  4. In the expanded view of the modal, pick the previously created data source. Other values can, like the algorithm used for hashing, can also be changed.

    ../_images/credential-manager.png

    Fig. 18 Defining a new credential manager in the admin UI

  5. Commit the changes by selecting Changes -> Commit, entering an optional message, and clicking OK.

Note

A Credential Manager is in the processing subtree of the configuration schema. This allows the same Credential Manager to be used across profiles. This can be especially useful when you have an authentication and an OAuth or OpenID Connect profile. In such a case, you can use the same Credential Manager with an HTML form Authenticator in the authentication profile as you do to verify credentials presented to the OAuth server’s token endpoint when using the resource owner password credentials grant type, for instance.

Create an Account Manager

An Authenticator – whether that is an HTML form Authenticator like the one we will create next, or an SMS Authenticator or some other sort – operates on accounts using a component called an Account Manager. This is because an Authenticator often needs more than a credential to create accounts or find the devices or phone numbers associated with a user ID. The CRUD of user accounts is provided by an Account Manager. An Account Manager references a Credential Manager and delegates all CRUD of credential to it. Other CRUD for other user attributes, however, are handled directly by the Account Manager. For storing and retrieving the attributes, an Account Manager also needs a Data Source. This Data Source need not be the same one that a Credential Manager uses. This allows passwords to exist in an LDAP directory, for example, and other user attributes to exist in a SCIM service or RDBMS.

To see how this can work, create a new Account Manager that uses the new HSQL-backed Credential Manager. This will result in an Account Manager that checks passwords and gets account details from the same database; we could use different ones for these two purposes, but we’ll start simple. To add such an Account Manager, do the following in the admin UI:

  1. Click Facilities in the top-right corner of the screen.

  2. Next to the Account Managers heading, click New.

  3. In the Create Account Manager modal dialogue box, enter a name, e.g., DefaultAccountManager.

  4. In the same modal, toggle on Enable Registration and select no-verification from Account Verification Method dropdown list.

    ../_images/new-account-manager.png

    Fig. 19 Adding a new account manager in the admin UI

    Finally, click Close.

Create the New Authenticator

With these facilities in place, we can now create a new HTML form Authenticator that uses this Account Manager by performing the following steps in the admin UI:

  1. Select the authentication profile that was previously created by selecting it from the Authentication Menu.

  2. In that profile, click Authenticators from the left-hand sidebar.

  3. Click the New Authenticator button.

  4. Enter a name, like html1, and choose the type HTML Form. Then, click Next.

  5. Select the previously created Credential and Account Managers from the respective dropdown lists.

    ../_images/new-html-form-authenticator.png

    Fig. 20 Adding a new HTML form authenticator, choosing the previously created managers

  6. Commit the changes as in previous steps.

If you surf back to http://localhost:8443/dev/authn/authenticate at this point, you will get a bad request error like the following:

../_images/400-bad-request.png

Fig. 21 An error shown because the request lacks an application identifier

This is because we didn’t indicate which app we are authenticator for. In order to do this, we need an app of some sort. We will use OAuth to integrate with the app in the end, but we can temporarily set up a test app to ensure that things are configured correctly at this point.

Adding a Temporary Test App

To test what is configured so far, we will create a Service Provider app directly in this new authentication profile. The Curity Identity Server is designed to integrate with apps. These can be installed desktop applications, Web applications, and mobile applications. They can also be server-based applications and Commercial Off-The-Shelf commercial (COTS) products. When you are building the apps and integrating them with the Curity Security Token Server using OAuth or OpenID Connect, the integration will be defined in an OAuth profile. When integrations are defined in an OAuth or OpenID Connect profile, the app is called a “Client.” When integrating with a COTS product like ADFS from Microsoft or PingFederate from Ping Identity or other apps and only using the Curity Authentication Server, you will define application integrations in an authentication profile itself. When you do this, the app is referred to as a “Service Provider.”

Since you have not yet setup an OAuth profile, do the following to create a Service Provider in the admin UI:

  1. Select the authentication profile that was previously created by selecting it from the Authentication Menu.

  2. In that profile, click Service Providers from the left-hand sidebar.

  3. Click the New Service Provider button.

  4. Give it a name, e.g., walk-through-test-sp and click Create.

  5. Enter some callback URL, like http://localhost/callback. This is where the login information will be sent. The way this is communicated is using one of the integration protocols. When using the wizard to define the profile, the Curity Token Service was the only integration setup. This is sufficient for the level of testing that we’ll do shortly.

    ../_images/new-sp.png

    Fig. 22 Adding a new account manager in the admin UI

  6. So that the Curity Authentication Server will redirect to the service provider, add the callback URL to the redirect whitelist on the General page of the profile:

    ../_images/redirect-whitelist.png

    Fig. 23 Adding the service provider’s target URL to the authentication profile’s allowed redirect whitelist

  7. Commit the changes as in previous steps.

  8. Access the authenticate endpoint of the profile by surfing to its endpoint, e.g., with a URL like https://localhost:8443/test1/authentication?serviceProviderId=walk-through-test-sp. You should be automatically redirected to an HTML that looks like this:

    ../_images/html-form.png

    Fig. 24 HTML form authenticator

    Note the following about this request:

    • We stipulated which application we would like to login for using the query string argument serviceProviderId. The value corresponds to the Service Provider created in Fig. 22.
    • Only one Authenticator is configured, so the user is automatically redirected to login with it. When multiple Authenticators are defined, the user will be presented with a choice of login options unless the caller stipulates a certain one.

Creating a Test User

Now that we have an Authenticator, we need a user account to login with. Because self-service registration was enabled in the Account Manager, we can create a new account during login. To do that, at the login prompt shown in Fig. 24, do the following:

  1. Click the Create account (or equivalent if viewing a localized version of the page).

  2. Fill in the registration form:

    ../_images/registration.png

    Then, click the Create Account button.

  3. Because email verification was turned off in the Account Manager, the new account is immediacy activated and usable. To do so, click the Return to login link.

  4. You should be at the login form again, like the one shown in Fig. 24. Enter the username and password that you used when registering. Then, click the Login button. After you do, you will be redirected to http://localhost/callback, which was the target-url of the test application defined in Fig. 22.

OAuth Security Token Server

So far in this walkthrough, we have setup an authentication profile and added an HTML form Authenticator with its related configuration. This allowed us to do basic login, at least enough to prove the concept. To keep it simple, we used a fictitious application to which we sent a login token that was disregarded. This is one way to interact with the Curity Identity Server, as a stand-alone Authentication Server. Another is to use it as an Security Token Server. In this role, the Curity Identity Server will consume this kind of short-lived login token emitted by the Curity Authentication Server and issue new ones of various kinds, including identity tokens, access tokens and refresh tokens. To see how these concepts can be put into practice, we will begin as we did before: by defining a profile.

OAuth Profile

To define such an OAuth profile, do the following in the admin UI:

  1. From the Token Service menu, select New Profile. This will open the Create Token Profile wizard.

  2. As was done when adding an authentication profile (shown in Fig. 7), a name (e.g., test1-oauth) and URL prefix (e.g., /test1-oauth) for the new OAuth profile should be stipulated. Then, click Next.

  3. On the Capabilities page, select the capabilities of the OAuth server. In other words, select the flows the new profile should allow. Clients will not be able to use any other flows or message exchanges than these. For the sake of this walkthrough, select all of them. When you do this, OpenID Connect is automatically enabled; leave this selected. Also, enabling the exposure of metadata.

    ../_images/oauth-capabilities.png

    Fig. 25 Enabling capabilities in the new OAuth profile

    Then, click Next.

  4. On the Signing Keys page, select Generate New Key and enter a Common Name of some kind, like test-key. Then, press Next.

  5. On the final page, select the service node that was previously created to deploy the new profile. Then, click Next.

  6. Finally, select to commit the changes by clicking the Commit button.

Now, the profile is configured and deployed, but we still need some client apps.

Adding Clients

Creating a Client that Supports the Client Credential Flow

Firstly, we’ll create a client that supports only the client credential flow. This interaction style is typically used for server-to-server communication. It allows an application that is capable of maintaining a secret – a “confidential client” in the wording of the OAuth specification – to exchange that credential for a token. This flow is typically used to normalize the types of credentials that an API or service needs to verify. Instead of having to validate passwords, X.509 client certificates, Kerberos tokens, SAML tokens, etc., the API can simply accept an OAuth token from its trusted OAuth Security Token Server. The Security Token Server can accept and translate these various kinds of input credentials and exchange them for tokens that the APIs can consume and verify. In this way, authentication is greatly simplified for APIs and Resource Servers.

To create such a client, perform the following steps:

  1. Create a client that only has the client credential capability. This will provide you with a useful way to get a token from a simulated server-based client later in the walkthrough. To create such a client in the admin UI, select the OAuth profile that was just created and then click Clients from the left-hand sidebar.
  2. Click the New Client button.
  3. Enter a name for the client, like client1, in the Name text field and click the Create button.
  4. In the Client Capabilities section, toggle on Client Credentials
  5. In the Client Authentication section, choose secret from the Authentication Method dropdown list.
  6. Enter a secret in the Secret text field.
  7. Commit the changes as normal.

Client Credential Flow

Unlike all the other flows, the client credential flow authenticates the organization or operator of the client app as opposed to the resource owner or user of the app. As mentioned above, this flow is typically used in server-to-server communicate to normalize the type of credential that an API accepts. This architecture is shown in the following figure:

../_images/cc_flow.png

Fig. 26 Client credential flow showing the exchange of a secret for a token that is presented to an API (AKA a resource server)

The request and response shown in Fig. 26 are standardized and require the client to make a proper request. A proper request conforms the following:

POST /(string: token_uri)

Requests a token using the client credential flow

Parameters:
  • token_uri – The token endpoint URI that was configured for the profile (e.g., /dev/oauth/token)
Request Headers:
 
Form Parameters:
 
  • grant_type – the value must be client_credentials to indicate to the Security Token Server that the client credential flow is to be used
  • scope – optional, space-separated list of scopes that the client wishes the token to be authorized for
Status Codes:
Response JSON Object:
 
  • expires_in (int) – the number of seconds till the token expires
  • scope (string) – a space-separated list of scopes that the issued token authorizes
  • token_type – the type of token, typically bearer

Example request:

Listing 8 Example request to the token endpoint using the client credential grant type
GET /dev/oauth/token HTTP/1.1
Host: sts.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=cc-client&client_secret=Password1

Example response:

Listing 9 Example response from a client credential request
HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "7b3e3320-9b2f-4ec4-8edd-e80fe30b60f4",
    "expires_in": 300,
    "scope": "",
    "token_type": "bearer"
}

To make a request that conforms to this API, issue one of the following curl commands:

Listing 10 Issuing a client credential request to the OAuth server’s token endpoint
$ curl -k -X POST \
    -d "grant_type=client_credentials&client_id=cc-client&client_secret=Password1" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    http://localhost:8443/dev/oauth/token

# Alternatively, basic authentication can be used like this:

$ curl -k -X POST -d "grant_type=client_credentials" \
    -u cc-client:Password1 \
    -H "Content-Type: application/x-www-form-urlencoded" \
    http://localhost:8443/dev/oauth/token

The response should be similar to the example response shown above. Note how authentication can be done it two different ways: by including the credentials of the client in the body (the first curl command) and using basic authentication (the second). Another thing to note in the response shown in Listing 9 is that there are no scopes. Scopes are an important part of OAuth, even in this simple case, so where are those?

What’s Next?

At this point, you have set up authentication and OAuth profiles as well as the necessary facilities (like account managers) to create user accounts, login, issue tokens, and more. By doing this walk-through you should also have familiarized yourself the admin UI, and learned more about the components within the Curity Identity Server. To continue exploring the functionality of the product, the following tutorials and resources may be a useful next step: