# Connect your application

{% hint style="info" %}
Note that after configuring your application, users will not be able to login be default. They would first need to have a role or Allow policy to be able to access your application(s). See [Set up access controls](/for-providers/ciam/set-up-access-controls.md) for more information on how to create a role or allow policy. 
{% endhint %}

To configure and connect your application with Veriam, follow these steps:

<details>

<summary>Steps to configure application on Veriam</summary>

{% hint style="info" %}
Before you can integrate your application with Veriam, you need to register it in the Veriam app. This allows Veriam to:

* Know **where to redirect users** after they sign up or authenticate
* Generate the **Client ID and Client Secret** required for secure integration
* Provide you with a **signup URL** to direct users into your Veriam-powered onboarding flow
  {% endhint %}

**Steps:**

1. Log In to the **Veriam App**
2. In the sidebar, navigate to **"Applications"**.
3. Click 'Add application'
4. Enter basic application details
   * **Application name**: This is for your internal reference.
   * **Description**: Provide context about what this app does.
5. Select application type - choose the option that best represents your application.
6. Provide the **Application URL**

   > *Note: This is only used for internal configuration—it will not be shown to end users.*
7. Configure **Redirect URLs**
   * On the **"Connection configuration"** tab.
   * Add at least one **Redirect URL**. This is where Veriam will send users after signup or login is complete.
   * If you add multiple Redirect URLs, ensure that your authentication request specifies which one to use.
8. **Save** the Application
9. **Copy Your Credentials**
   * After saving, a popup will display your **Client Secret**.

     > ⚠️ **Important:** Copy this immediately—you will not be able to view it again.
   * After closing the popup, your **Client ID** will also be visible on the application detail page.
   * Also note the **Veriam OpenID Connect Discovery URL** (provided in our integration docs).
10. **Add to Your Application Configuration**\
    In your app's authentication setup you will need the following from the app setup:
    * The **Client ID**
    * The **Client Secret**
    * The **Discovery URL**
    * The **Redirect URL(s)**
    * **Sign up URL**

</details>

<details>

<summary>Steps to connect your application to Veriam</summary>

{% hint style="info" %}
To connect your application with Veriam, you can use the standard **OpenID Connect (OIDC)** protocol for authentication and user identity management.&#x20;

Alternatively, if you prefer to handle integration directly in your codebase, you can use our official **TypeScript SDK**. The SDK provides simple, ready-to-use methods to authenticate users, retrieve identity information, and enforce access—all without needing to manage the full OIDC flow yourself.
{% endhint %}

#### Configure Veriam Credentials in Your Application

To begin, you’ll need the following details from your Veriam application configuration:

| Setting                | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| **Client ID**          | Retrieved from the **Connection Configuration** tab under your registered application in Veriam.        |
| **Client Secret**      | Provided immediately after you create the application. You can also generate a new one later if needed. |
| **OIDC Discovery URL** | Available on your application detail page.                                                              |

> **Note:** If you generate a new Client Secret, the old one will still remain active unless you explicitly delete it.

### Using Typescript SDK

Use our official **TypeScript SDK here** [`@veriam/ts`](https://www.npmjs.com/package/@veriam/ts) to easily connect your application with Veriam.

### Using OpenID Connect:

#### Handle Authentication (Single Page Application Example)

Veriam supports integration via the industry-standard **OpenID Connect (OIDC)** protocol, enabling secure authentication and identity management for your users. OIDC builds on OAuth 2.0 to provide a federated login flow along with user profile data, making it ideal for modern web apps.

Below is a breakdown for integrating with Veriam using OIDC in a **Single Page Application (SPA)** context:

**a. Install the Client**

```bash
bashCopyEditnpm install oidc-client-ts
```

This library (`oidc-client-ts`) provides a high-level abstraction over the OIDC protocol. It handles complex flows like Authorization Code with PKCE, token renewal, storage, and redirection automatically.

> 📘 *Note: `oidc-client-ts` is the modern TypeScript rewrite of the original `oidc-client` library and is actively maintained.*

**b. Configure the OIDC Client**

```ts
tsCopyEditimport { UserManager, WebStorageStateStore } from "oidc-client-ts";

const settings = {
  userStore: new WebStorageStateStore({ store: window.localStorage }),
  authority: "https://idp.myveriam.com", // Veriam OIDC provider URL
  client_id: "YOUR_CLIENT_ID",
  redirect_uri: "YOUR_CALLBACK_URL",
  post_logout_redirect_uri: "YOUR_POST_LOGOUT_URL",
  response_type: "code",
  scope: "openid email profile",
  automaticSilentRenew: true,
};

const userManager = new UserManager(settings);
```

**Explanation of Key Settings:**

* `authority`: The URL of Veriam’s OIDC-compliant identity provider. It hosts the `.well-known/openid-configuration` for discovery.
* `client_id`: Issued by Veriam when you register your app. Used to identify the client.
* `redirect_uri`: The callback URL to which the IDP will redirect after authentication.
* `post_logout_redirect_uri`: Where users are taken after logging out.
* `response_type: "code"`: Uses Authorization Code Flow (recommended for SPAs with PKCE for security).
* `scope`: Defines what information your app will receive. `openid` is required for OIDC. `email`, `profile` are optional standard claims.
* `automaticSilentRenew`: Ensures the user stays logged in by renewing the session silently (without user interaction), reducing session expiration issues.

**c. Trigger Login**

```ts
tsCopyEdituserManager.signinRedirect().then();
```

**What It Does:**\
Redirects the user to Veriam’s login page using the OIDC Authorization Code flow.

**Why:**\
OIDC relies on the browser redirect model for SPAs. The user authenticates with Veriam, and is redirected back to your app with an authorization code.

> 🔐 *Ensure your `redirect_uri` matches what you've configured in your Veriam app settings—case-sensitive and fully qualified.*

**d. Trigger Logout**

```ts
tsCopyEdituserManager.signoutRedirect().then();
```

**What It Does:**\
Logs the user out from both your application and the Veriam identity provider.

**Why:**\
OIDC supports **RP-Initiated Logout**, ensuring a complete sign-out experience.

> 🔁 *Consider adding a redirect or message after logout to improve UX.*

**e. Retrieve Authenticated User Info**

```ts
tsCopyEditimport { User } from "oidc-client-ts";

userManager.getUser().then((user: User) => {
  // Access user profile details via user.profile
});
```

**What It Does:**\
Returns the currently logged-in user's session and profile data, if available.

**Why:**\
This allows you to extract information like email, name, and custom claims (if any), to personalize your UI or control access.

> 🧪 *This is useful for conditionally rendering routes or verifying session state on page load.*

**f. Direct to Signup (Optional)**

To direct users specifically to the signup flow:

```ts
tsCopyEdituserManager.signinRedirect({
  extraQueryParams: {
    screen_hint: "signup",
  },
}).then();
```

**What It Does:**\
Instructs Veriam’s login page to present the **signup form** instead of login.

**Why:**\
This helps you streamline onboarding by linking directly to a registration experience.

> ✉️ *Use this in welcome emails, marketing CTAs, or "Sign Up" buttons.*

#### 3. Next Steps

* **Redirect URL Configuration**:\
  Make sure the `redirect_uri` used in your code is **registered** in the Veriam dashboard. Otherwise, login will fail due to a security mismatch.
* **Secure Client Credentials**:\
  Store your `Client ID` and `Client Secret` securely. For SPAs, avoid exposing secrets; instead, use PKCE (handled automatically by most OIDC libraries).
* **Signup Entry Point**:\
  Use the **signup URL** generated from your Veriam application config to onboard new users.

</details>

<details>

<summary>Optionally test integration using Postman</summary>

Test your integration with Veriam using Postman:

First, you need to add the Redirect URL from Postman to your application in Veriam:

<https://oauth.pstmn.io/v1/callback>

Then in the Postman application you need to choose the Authorization of Type OAuth 2.0, with the following settings:

* Header Prefix: Bearer
* Token Name: \<YOUR\_TOKEN\_NAME> (can be anything)
* Grant Type: Authorization Code (with PKCE)
* Authorize using Browser: (Selected)
* Callback URL: <https://oauth.pstmn.io/v1/callback> (this is pre-filled from selecting item above)
* Auth URL: <https://idp.myveriam.com/oauth2/authorize>
* Access Token URL: <https://idp.myveriam.com/oauth2/token>
* Client ID: \<YOUR\_CLIENT\_ID>
* Client Secret: \<YOUR\_CLIENT\_SECRET>
* Code Challenge Method: SHA-256
* State: \<YOUR\_STATE> (can be anything)
* Client Authentication: Send client credentials in body

Once those have been filled, click on Get New Access Token button and you should be redirected to login on Veriam and after a successful authentication you should be redirected to the Postman app with the access token for subsequent requests to the API.

</details>


---

# 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://docs.myveriam.com/for-providers/ciam/connect-your-application.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.