Migrating from Spring Security OAuth to Curity Identity Server

The Spring Security OAuth project has been deprecated some time ago, and if you used it to for your own Authorization Server you are most probably looking now for available solutions to replace it. One of the options is to move to another authorization server available on the market, like the Curity Identity Server.

Here is a guide that will help you migrate your current Spring Server to the Curity Identity Server. If you need help only with a given functionality of the Authorization Server, you can dive straight into the appropriate section:

1. Server Configuration
2. Configuring Authenticators
3. Configuring Grant Types
4. Endpoints Configuration
5. The Public Key Endpoint
6. The check_token Endpoint
7. Token Granter
8. Token Store
9. Migrating Clients
10. Migrating Users
11. Customizing the UI
12. Customizing Error Pages
13. Support for the Password Flow

Server Configuration

Configuration of a Spring Authorization Server resides partly in the yaml/xml configuration files and partly in the code itself. In the Curity Identity Server most of the functionality can be set in configuration using either the UI, a REST API (which uses the RESTCONF standard) or through an interactive Command Line Interface (CLI). As the Curity Identity Server is a dedicated Authorization Server, in many cases there won't be a need to additionally configure things or write code, which you would have done in Spring. For example, you don't have to configure the Curity Identity Server to allow unauthenticated access to the login screen, etc.

For a number of functions it is possible to create plugins using a Java SDK, should you need to further extend the functionality offered by Curity.

What is important is that the whole configuration can be dumped into an XML file, which allows it to be version-controlled.

Configuring Authenticators

The Curity Identity Server supports many authentication methods that you can quickly enable for your users. Authentication methods like username/password, login with Google or Facebook, or multi-factor authentication can be easily enabled by providing a few configuration options, with no need for coding or using external libraries or plugins.

Authentication methods in the Curity Identity Server can be chained and decorated with actions to create complex authentication scenarios. Both authenticators and authentication actions can be extended with the plugin system. Have a look at the Authenticators documentation to learn more about configuring authenticators in the Curity Identity Server.

Configuring Grant Types

In the Spring Authorization Server available grant types are configured using AuthorizationServerEndpointsConfigurer.

In the Curity Identity Server you can enable or disable grant types in the Token Service Profile -> General -> Client Settings configuration page of the admin UI under the section Capabilities.

Endpoints Configuration

In the Spring Authorization Server you could tailor the URLs of endpoints via the AuthorizationServerEndpointsConfigurer, either by adding a prefix to the default URLs or by changing the mappings using the pathMapping() method.

In the Curity Identity Server you can configure URLs of the different endpoints used by OAuth flows in the Token Service Profile -> Endpoints configuration page. You can also change URLs used by authentication and registration in Authentication Profile -> Endpoints panel. Moreover, you can add additional URLs and have, for example, different /token endpoints, with a different URL and a different behavior.

Have a look at the Token Procedures Scripting Guide to learn how you can change behavior of some endpoints without the need for creating plugins.

The Public Key Endpoint

If you used keys to sign JWT tokens in the Spring Authorization Server, then the server exposed an endpoint from which clients could obtain a key to verify signatures of tokens, the /oauth/token_key endpoint.

In the Curity Identity Server information about the keys used to verify tokens is exposed in a JWKS endpoint by default.

If you had Spring Security clients which used to read the certificate from this endpoint you will have to switch them to use JWKS instead.

E.g. if you had something like this in your configuration yaml:

security.oauth2.resource.jwt.key-uri=https://my-authorization-server.example.com/oauth/token_key

you will have to change it to something like this:

security.oauth2.resource.jwk.key-set-uri=https://my-authorization-server.example.com/oauth/v2/oauth-anonymous/jwks

The path used here is the base URL, that your server runs on, plus the path of an endpoint with type oauth-anonymous and /jwks. The oauth-anonymous path is also used to expose OpenID Connect metadata of your server. You can find it under the path {oauth-anonymous path}/.well-known/openid-configuration.

The check_token Endpoint

Although it is not explicitly named in the Spring Authorization Server, the /oauth/check_token endpoint is an implementation of the OAuth 2 Token Introspection. In the Curity Identity Server you can enable token introspection for any client. The URL for this endpoint is defined in the Token Service Profile -> Endpoints tab.

The Spring's implementation has one difference from the Token Introspection specification. In case of an inactive token (e.g. one which is past its expiration date) the Spring Authorization Server returns a 400 OAuth error response. The Curity Identity Server returns a 200 response with {"active": false}, as is required by the specification. If you have clients which rely on the code of the response, then they must be adjusted. Another option is to call the Introspection endpoint with Accept: application/jwt. In case of an inactive token, this will return a 204 response. For active tokens you will get a JWT corresponding to the access token. If the client needs data from this token, it would have to then verify and decode the JWT.

Token Granter

If you wrote your own TokenGranter in the Spring Authorization Server, you will want to mimic its behavior in the Curity Identity Server. Depending on what exact functionality your TokenGranter had you will use different solutions:

• If you used the TokenGranter to add some constraints on the authentication method or to trigger additional authentication methods, then have a look at Authenticators and Authentication actions, which can be chained together to create complex authentication scenarios.
• If you used the TokenGranter to add specific claims to the issued JWTs, then have a look at the Scopes and Claims section of the documentation, where mechanisms such as Claims Providers and Claims Mappers are described. If a more complex solution is needed, you can have a look at the Claims Provider Plugin in the SDK documentation.
• If you used to TokenGranter to modify the contents of the token, you can have a look at the Token procedures, which are JavaScript scripts you can use to modify the token or the response of some endpoints.

Token Store

The Curity Identity Server stores the generated access tokens in a Token Data Store. You can use any JDBC database as a Data Source in the Curity Identity Server, and you can use configuration to choose a Data Source to be used as a Token Store. If a more complex solution is needed, you can create a Data Access Plugin, which can implement a Token Store. Have a look at the TokenDataAccessProvider interface in the SDK reference.

If you used JwtTokenStore in Spring Authorization Server, and you were issuing JWTs to your clients, this is still possible in the Curity Identity Server, by changing a setting found in the Token Service Profile -> Token Issuers tab. If the access tokens are available publicly though, we strongly recommend you issue opaque access tokens and use the Phantom Token Approach.

Migrating Clients

Client data in the Curity Identity Server is kept as part of the configuration. You can use the RESTCONF API or the shell access to the configuration to automate the process of migrating client data to the Curity Identity Server.

You must map the data from Spring to XML nodes used in the Curity Identity Server:

• clientId to the <id> node
• secret to <secret> node
• scope - every scope token should be added as a separate <scope> node
• authorizedGrantTypes to <capabilities> node. E.g. if you want your clients to be able to use code grant, client credentials grant and token introspection (replacement for Spring's check_token), use the following XML:

<capabilities>
  <code/>
  <client-credentials/>
  <introspection/>
</capabilities>

• You can also check the OAuth Client documentation to learn what other settings should and can be set for a client.

If your clients were not using auto-approved scopes you must require User Consent by toggling appropriate option for the client.

Migrating Users

The Curity Identity Server uses an Account Manager to store information about users and a Credential Manager to verify the credentials.

There are a few different approaches you can apply when it comes to migrating user data to the Curity Identity Server.

1. Keep the existing database as a source.
2. Use a script to migrate data.
3. Perform a lazy migration of users.

Keep the Existing Database as a Source

If you want to keep the users' data in your current database you can write a Data Access Provider plugin and implement a UserAccountDataAccessProvider and a CredentialDataAccessProvider. These providers can either read directly from your current database (but is not considered a good practice, to have one service use the database of another service), or you can enable reading and writing this data by exposing endpoints with access to the existing database.

Have a look at the Plugins documentation or the RESTful Data Access Plugin example to learn more about writing such plugins.

Use a Script to Migrate Data

It is often simpler to migrate users to the database schema of the Curity Identity Server, and this will need to be done separately per environment. A script can use either SCIM or GraphQL to save users in the Curity Identity Server. The schema of the Curity Identity Server includes an attributes field, which is usually stored as JSON. This is used to store any custom identity data against users.

Have a look at the User Management documentation to learn more about the user management APIs.

Perform a Lazy Migration of Users

If you rather perform a lazy migration of the data, you can create an Authentication Action Plugin, which can perform actions during an authentication flow. The plugin could automatically migrate data of a given user during the authentication flow.

Have a look at the Plugins documentation or the Redirect Action Example to learn more how an authentication action can work.

Customizing the UI

To customize how the authentication process looks to the end user you have two options: either fiddle just with the css to tailor the look and feel to your needs, or rewrite templates used by the views. Both these approaches are described thoroughly in the Frontend development documentation.

Customizing Error Pages

If you need more customization than just overriding css, you can have a look at the Error templates documentation to learn how to override the templates used for rendering errors.

Better Support for Password Flow

If you have clients with OAuth password flow enabled chances are it is a first-party application in which you want to perform authentication without needing the user to leave the app and go to a browser (or to another browser tab). If this is the case, then the Curity Identity Server is enabling a better solution to such a problem, the Hypermedia Authentication API. The API lets you utilize all the power of OAuth and OpenID flows, as well as creating complex authentication scenarios, without the need of an intermediary user-agent, such as a browser. Have a look at the overview of the Hypermedia API to learn more about this solution.

Conclusion

Migrating from the deprecated Spring Security OAuth 2 Authorization Server to the Curity Identity Server is unfortunately not an automatic process, but can be done quite efficiently. Very often you will only need to work with the Curity Identity Server's configuration, without the need of additional coding. Should you find any problems during your migration process or think of solutions that could make the migration easier for you, do not hesitate to contact us.