REST clients & authentication

Owned by Joseph Kinyanjui
Oct 23, 2020

Since version 1.3.0 the plugin supports the authentication of REST clients using OpenID Connect. REST clients for Jira/Confluence typically use one of four authentication mechanisms when requesting protected resources from the /rest/* endpoints:

HTTP session cookies as well as the longer lived OAuth2 tokens can be acquired by logging in to the graphical UI. This means that these methods for authenticating REST clients work when using the OpenID Connect SSO mechanism of the graphical UI and have also worked with earlier versions of the plugin.

The HTTP GET/POST parameters and HTTP Basic Auth on the other hand directly send the username and password to Jira/Confluence. This does not go well with the usual OpenID Connect authentication flow where the user authenticates with the provider and the password is never given to the application.

Since version 1.3.0 the plugin offers the REST SSO option which uses the Resource Owner Password Credentials (also called Direct Access Grants) authentication flow to authenticate users with username and password. This guide describes how to set up this feature and what problems might occur.

This guide is applicable for the versions 1.3+ of the plugin.

Requirements and Setup

Before enabling the REST SSO authentication you have to check whether your configured OpenID Connect provider supports Resource Owner Password Credentials or whether this has to be specifically enabled. For Keycloak Resource Owner Password Credentials are enabled by activating Direct Access Grants Enabled in the client configuration tab.

Enabling authentication of REST clients with OpenID Connect in the plugin is as simple as enabling the REST SSO option in the plugin configuration. This option can be configured independently from the graphical OpenID Connect SSO.

WARNING: Please note that the plugin – however configured – does not attempt to prevent the authentication using local (non SSO) accounts. This means that there usually is a way to authenticate locally and you should not leave any local accounts with weak passwords.

When the option is enabled, all usernames and password sent to the /rest/* endpoints as os_username/os_password parameters or with HTTP Basic Auth will be authenticated against the configured OpenID Connect provider instead of checked locally. This means that all REST clients authenticating with these methods should work with OpenID Connect credentials without any other changes.

Risks and Problems

The problem with Resource Owner Password Credentials is that the user credentials pass through Jira/Confluence which is usually not necessary for authentication using OpenID Connect. Because of this authentication using OAuth2 tokens is preferred to HTTP parameters or HTTP Basic Auth.

WARNING: The plugin directly sends the username/password to the OpenID Connect provider. Make sure that all communication between the plugin and the provider is encrypted by only using https endpoints.

If the authentication fails even for correct usernames and passwords please check the Jira/Confluence error log as the plugin usually logs the reason the authentication failed. Errors like requestTokens provider rejected token request: Client not allowed for direct access grants indicate that Resource Owner Password Credentials are not enabled on your configured OpenID Connect provider.