How to use Keycloak to configure SSO for command-line applications

Command-line interfaces (CLI) don't get as much mainstream attention as graphical user interfaces (GUI), but they remain popular among developers and sysadmins.

Keycloak, an open source identity and access management tool for modern web applications, is one approach to securing command-line apps. Basic knowledge of command-line application development is a prerequisite to getting the best out of this article. At the end of the article, you'll be familiar with what Keycloak is, know some important Keycloak terminologies, and learn a recommended way to use Keycloak with a command-line application.

What is Keycloak?

The Keycloak GitHub page defines it as an open source identity and access management (IAM) solution for modern applications and services. An IAM is software that manages user identities and access specifications and provides single sign-on (SSO) and multifactor authentication (MFA). SSO allows users to securely log into multiple applications using a single set of credentials. MFA enhances the security level by requiring the user to provide two or more factors as proof of identity. These factors could range from facial recognition to a one-time password (OTP).

Keycloak can also be referred to as an identity provider (IdP). An IdP is a service that can authenticate a user and provide identity management as a service. Some popular IdPs include Google, Facebook, and Twitter. IdPs allow existing sets of credentials to be reused across other service providers.

Users can authenticate with Keycloak rather than individual applications. Therefore, the applications don't have to deal with login forms, user authentication, and user account storage. Keycloak is the upstream project for Red Hat SSO.

Keycloak provides many desirable features for user authentication and authorization, including SSO, social media logins, and support for SAML, OpenID Connect, and OAuth2.0 protocols. Apart from its technical capabilities, several other factors make Keycloak a good choice. It is a free and open source software (FOSS) solution licensed with Apache License 2.0. Being open source, it has extensive community support, which guarantees a lot of examples, forum discussions, and help when you're stuck. It also comes with a web-based GUI that makes things simple to use.

[ See how your operating system can be the foundation that solidifies and unifies your IT infrastructure. ]

Keycloak realms

A Keycloak realm is an isolated management space that maintains a set of users, credentials, roles, and groups. By default, Keycloak has the master realm, whose sole purpose is to create and manage other realms in the system. Additional realms need to be created for application-based use. Configurations and users are specific to a realm.

Each realm can support multiple clients. A Keycloak client represents an application or web service that uses Keycloak to authenticate and authorize users.

Keycloak client configuration

To secure apps with Keycloak, you need to have a little knowledge of Keycloak client configuration. Below are a few essential configurations. to provide you a basic idea of how they work. To learn more, use the admin console, where each property is described by help text.

Here is what these fields mean:

• Client ID, Name, and Description: User-specified details to help identify a client
• Root URL: URL to the application's index page
• Valid redirect URI: Patterns that redirect Uniform Resource Identifiers (URIs) should comply with
• Base URL: Used if the authentication server needs to link back to the client
• Admin URL: URL to the client's admin interface
• Access type: OIDC (OpenID Connect) client type

[ Check out this free guide to boosting hybrid cloud security and protecting your business. ]

Keycloak allows the use of popular social identity providers, including Google, Facebook, LinkedIn, Instagram, Microsoft, Twitter, and GitHub. These can be configured at the realm level. To use them, the user must retrieve their client ID and client secret from the social media account. For example, to use the GitHub identity provider, you need to create a new OAuth app from GitHub's developer settings to generate a Client ID and Client Secret. The redirect URI should be specified in both Keycloak and the OAuth app.

Keycloak authentication

Public applications secured with Keycloak rely on browsers to authenticate users. Things can get tricky when a command-line app involves a browser login. The easiest way might seem to be a copy-paste authentication token, passing it as an argument with the CLI. This approach gets problematic because the credentials are stored in the terminal's history. Moreover, best practice states that users should authenticate using the authorization server's web page.

Instead, to handle command-line application authentication, first, the app needs to build the URL for the authorization server and open it using a browser. The URL is created by transposing Keycloak configurations. The URL looks roughly like this:

${keycloakURL}/realms/{realm}/protocol/openid-connect/auth?client_id=${clientID}&redirect_uri=${redirectURI}&response_type=code

Once the login page is ready, a lightweight embedded server runs concurrently to handle the redirection. The redirection URI you use must be registered with the client configuration. The redirection URI will have a code as a URL parameter. The embedded server should parse the code to obtain authorization codes by requesting the OpenID connect token endpoint. Then the server needs to be stopped, and control must be transferred back to the script.

The authorization codes need to be stored in a configuration file. A preferred location is XDG_CONFIG_HOME, which should store user-specific configuration files.

Learn more

Keycloak offers many benefits to enhance authentication options and improve security initiatives for command-line applications.

You can find an implementation of this approach in this repo, which has a CLI built using Cobra, a Golang library to create CLIs. You might also be interested in learning to deploy Keycloak single sign-on with Ansible. You can learn even more by watching the presentation Securing command-line applications with Keycloak at DevConf.CZ 2022.