Migrating from Spring Security OAuth to Curity Identity Server

Migrating from Spring Security OAuth to Curity Identity Server

tutorials

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 product 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 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 Curity 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

Curity Identity Server comes with almost 30 authentication methods that you can quickly enable for your users. Authentication methods like username/password, login with Google or Facebook, 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 Curity 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 Curity Identity Server.

Configuring grant types

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

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

Endpoints configuration

In 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 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 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 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 you server runs on + the path of an endpoint with type oauth-anonymous + /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’s not explicitly named in the Spring Authorization Server, the /oauth/check_token endpoint is an implementation of the OAuth 2 Token Introspection. In 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. 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 Curity Identity Server. Depending on what exact functionality your TokenGranter had you will use a different solution in Curity:

  • 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 Plugins 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 Curity, 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 Curity, 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 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 Curity:

  • 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>

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

Note on PPID and PKCE

By default clients in Curity Identity Server have the two options enabled: Pairwise Pseudonymous Identifiers (PPID)and Proof Key for Code Exchange. We strongly advise you to use these options. You can learn from the referenced articles why they are important. Still, if your clients are not able to utilize them, you must disable them for each client.

Migrating users

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 user data, when migrating to Curity Identity Server.

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

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 to Curity

Users in Curity Identity Server are managed using the SCIM standard and you can expose endpoints for managing the users through a REST API. This can be then used to write a migration script which will move all the data from your current database to the Curity’s one.

Have a look at the User Management documentation to learn more about the SCIM API.

Perform a lazy migration of users to the Curity database

If you’d 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 Curity 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 a the overview of the Hypermedia API to learn more about this solution.

Conclusion

Migrating from the deprecated Spring Security OAuth 2 Authorization Server to Curity is unfortunately not an automatic process, but can be done quite efficiently. Very often you will only need to work with 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.

Let’s Stay in Touch!

Get the latest on identity management, API Security and authentication straight to your inbox.

Keep up with our latest articles and how-tos using RSS feeds