Setup OAuth Application Access

The purpose of this page is to document how to configure CopyStorm desktop apps to require login via OAuth 2.0 identity provider.

This feature updates CapStorm applications to require a login prior to accessing the application GUI – this feature is separate from features enabling OAuth for Salesforce or database login.

OAuth login for CapStorm desktop applications is only supported on Windows.

Installation

• Download the plugin.

  • OAuth application authentication requires a plugin to be installed into CapStorm desktop applications.

  • Contact your CapStorm account representative to obtain the plugin zip file.

• Install the plugin.

  • Extract the OAuth2 plugin zip file to the plugin folder in the CapStorm application installation directory.

  • The plugin is a sub-folder of the main application installation directory – i.e. it is next to the “config” folder and “CopyStorm.bat” file.

Configuration

OAuth settings are stored in a file named AuthParams.xml in the CopyStorm config/ directory.

The specification for this file is:

<AuthParams>
  <Request url="https://your-oauth2-host/oauth2/authorize">
    <Param name="client_id"       value="YOUR_CLIENT_ID"/>
    <Param name="redirect_uri"    value="http://localhost:12345/callback"/>
    <Param name="response_type"   value="code"/>
    <Param name="scope"           value="openid email profile"/>
  </Request>
  <Validate url="https://your-oauth2-host/oauth2/token">
    <Param name="grant_type"      value="authorization_code"/>
    <Param name="client_id"       value="YOUR_CLIENT_ID"/>
    <Param name="client_secret"   value="YOUR_CLIENT_SECRET"/>
    <Param name="redirect_uri"    value="http://localhost:12345/callback"/>
  </Validate>
</AuthParams>

• Request: Parameters to configure OAuth requests.

  • url: the IdP’s authorization endpoint.

  • Param elements under the Request element are added to the OAuth HTTP request.

• Validate: Parameters to configure OAuth validation requests.

  • url: the IdP’s token validation endpoint.

  • Param elements under the Validate element are added to the token validation HTTP request.

• Be sure to update the following parameters inside the AuthParams.xml:

  • client_id

  • client_secret

  • redirect_uri

Make sure the redirect_uri matches the one registered in the OAuth IdP.

The CapStorm OAuth plugin requires token validation – if the OAuth request or token validation fails, then the application will not launch.

Using OAuth to access CopyStorm

When this feature is configured, CopyStorm will perform the following steps before displaying the application UI:

• Check for a valid AuthParams.xml file.

• Launch a browser, navigating to the IdP login page.

• Wait for the authorization code callback.

• Validate the authorization code using the token endpoint.

• Continue startup only if authentication succeeds.

If the OAuth login fails, the token request fails, the token fails validation, or the AuthParams.xml file is misconfigured – CopyStorm will not launch. Instead of launching the application, CopyStorm will either display an error window or write the error message to STDOUT / STDERR. If you do not see an error message, try launching CopyStorm from a CMD window as “CopyStorm.bat -debug”.

Getting Help

If assistance enabling this feature is needed please reach out to your CapStorm account representative or CapStorm support.