Introduction

The OAuth 2.0 Authentication plugin allows multiple authentication methods for ST user accounts, account templates and administrator accounts against an Identity Provider service:

• Resource Owner Password Credentials Grant (ROPC) type for HTTP/S, FTP/S, SSH

• HTTP/s Bearer token authentication with Oauth2 or OIDC for end users and administrators

• HTTP/s Authorization code Grant type authentication with Oauth2 or OIDC for end users and administrators

• HTTP/s Implicit Grant type authentication with Oauth2 or OIDC for end users and administrators

Table of contents

• Deploying the plugin
• Troubleshooting
• Limitations and known issues
• Plugin configuration options
• Configuration options (detailed)
  • Connectivity settings
  • Authorization Code flow prerequisite
  • Authorization Code flow configuration
  • Implicit flow prerequisite
  • Implicit flow configuration
  • Authentication with an access token as a header
  • Resource Owner Password Credentials flow
• End users authentication
• Administrators authentication

Deploying the plugin

The OAuth Authentication plugin for ST can be downloaded from the Axway Repository.

For complete list of prerequisites and installation instructions, refer to the plugin Readme.md file contained in the plugin archive. The Readme can also be accessed from the plugin download page in the Axway Support Portal.

Verifying the installation

Once the plugin had been deployed, go to the Admin UI → Operations → Server Configuration and search for the Plugins.Authentication.Admin.Registry and Plugins.Authentication.EndUser.Registry configuration options.

Enabling the OAuth Authentication plugin

Important: Before enabling the external authentication plugin, make sure its sources are configured and there is at least one ST administrator account with local credentials, that does not exist in the external authentication sources.

To enable the plugin and authenticate ST Administrator accounts update the value of the Plugins.Authentication.Admin.Registry ST server configuration parameter to oauth-authentication-plugin.

To enable the plugin and authenticate ST enduser accounts update the value of the Plugins.Authentication.EndUser.Registry ST server configuration parameter to oauth-authentication-plugin.

Troubleshooting

For troubleshooting purposes, you can enable debug logging in the dedicated Transaction Manager (TM) logger for the plugin, located in the <FILEDRIVEHOME>/conf/tm-log4j.xml file. Events related to the plugin are available in the Server Log. The configured logger will look like the example below:

<logger name="com.axway.st.plugins.authentication" additivity="false">
        <level value="debug" />
        <appender-ref ref="ServerLog" />
</logger>

To enable debug logging, set the level value to debug. However, change the value with caution. It is recommended to switch to levels different than INFO only temporarily, e.g. during troubleshooting sessions.

Limitations and known issues

For complete list of limitations, refer to the plugin Readme.md file contained in the plugin archive.

Plugin configuration options

The OAuth Authentication plugin for SecureTransport comes with the configuration options described in the following table. Keep in mind:

• All options are prefixed with Plugins.Authentication.oauth-authentication-plugin..

• Each ID Provider requires a different set of options to be configured.

After the plugin has been configured the ST services must be restarted.

Configuration options (detailed)

The following sections focus on the plugin configuration options required for specific authentication flows.

Connectivity settings

The settings are not needed only when authenticating with a JWT token using a static configurable signature validation key.

When Keycloak IDP is used two more cipher suites should be added in cipherSuites - TLS_AES_256_GCM_SHA384, TLS_AKE_WITH_AES_256_GCM_SHA384.

Authorization Code flow prerequisite - enable HTTP server redirect

The below settings for the HTTP service in ST are required to enable interactive authentication requiring a REDIRECT.

Please note that a proper account configuration (described further in this article) must be created in ST to map users. Otherwise, if the authentication at the Identity Provider side is successful, but there is no matching Account Template, local Account or Administrator, the browser will go into a redirect loop between SecureTransport and the Provider. This is because the unsuccessful login on SecureTransport will automatically trigger a redirect to the Identity Provider, but since the user already has an active session with the provider, an immediate redirection back to SecureTransport will occur. Browsers terminate such loops after a fixed number of attempts.

Authorization Code flow configuration

Implicit flow prerequisite - enable HTTP server redirect and allow FORM-POST authentication

The below settings for the HTTP service in ST are required to enable interactive authentication requiring a REDIRECT.

Implicit flow configuration

The only supported way of receiving tokens using the implicit flow is through FORM POST parameters. The plugin automatically sets the response mode to form-post when redirecting end users to Identity Providers. This method must be supported by the provider.

There are 3 possible combinations for receiving tokens when using Implicit flow and all combinations are supported by setting up different parameters:

• Only receiving an id_token - oidcEnabled is true and userInfoUrl is empty

• Receiving an id_token and access_token - oidcEnabled is true and userInfoUrl is <UserInfo endpoint>. Only the ID token is validated. The access token is used to authorize the UserInfo request.

• Only receiving an access_token - oidcEnabled is false.

Authentication with an access token as a header

Example cURL calls for authentication with access token as header

Using the Authorization header (recommended).

curl -k -v -X GET --header 'Referer: localhost' --header 'accept: application/json' --header 'Content-Type:multipart/form-data' --header 'Authorization:Bearer {<JWT encoded access token>}'  https://10.10.10.10/api/v1.4/files/

Using a custom header. The custom header should contain the token value as is. What is important to note is that the Basic Authorization header should be added as well with a base64 encoded string <dummy username>:<empty password>. For example base64-encoded "asd:" string would be YXNkOg==.

curl -k -v -X GET --header 'Referer: localhost' --header 'accept: application/json' --header 'Content-Type:multipart/form-data' --header 'Authorization:Basic YXNkOg==' --header 'CustomHeader:{<JWT encoded access token>}'  https://10.10.10.10/api/v1.4/files/

Token revocation

Each time the end user or admin logs out, the token is being revoked by sending an additional request with the token to a specific address.

Resource Owner Password Credentials flow

End users authentication

Navigate to Admin UI → Accounts → User Accounts → New Account and create a new account. The Account Name should match that from the IDP server. Make sure that the Password is stored locally (not in external directory) checkbox is unchecked.

Once the account has been authenticated, you can find messages like below in the TM log:

Account Templates can also be authentication with the OAuth Plugin in a similar manner. For more information on how to create an Account Template, you can refer to SecureTransport AdministratorsGuide.

Administrators authentication

Navigate to Admin UI → Accounts → Administrators → New Administrator and create a new administrator. The Administrator Name should match the name which is configured in the IDP server. Make sure that the Password is stored locally (not in external directory) checkbox is unchecked.

Once the account has been authenticated, you can find messages like below in the Admin and Audit logs: