# 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](https://www.capstorm.com/contact-us/).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.capstorm.com/best-practices/setup-oauth-application-access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.