# Authentication

### OAuth 2.0 authorization methods in VARIO Cloud

In addition to its App frameworks, VARIO-Cloud exposes an HTTP API that is protected using **OAuth 2.0**.\
You can choose between three authorization methods:

* **Password** grant
* **Authorization Code** grant
* **Device Code** grant

All methods use the **client credentials** (`clientId`, `clientSecret`) that you obtain when creating an App in the Developer section.

{% hint style="info" %}
The exact URLs for the authorization and token endpoints depend on your tenant configuration.\
They can be found in the API-Clients section in the Admin Interface\
In the examples below, replace `https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/` with your actual base URL.
{% endhint %}

{% hint style="warning" %}
**User-Agent required**\
All API requests must include a `User-Agent` header (e.g. `MyApp/1.0`). Requests without `User-Agent` are blocked with `403 Forbidden`.
{% endhint %}

***

### Password grant

The **Password grant** allows your App to exchange a user’s **username and password** directly for an access token.

#### When to use

* For **trusted, server-side** applications that can securely store user credentials and client secrets.
* For **system integrations** where a technical user is used for automation.

{% hint style="warning" %}
**Security warning**\
Do **not** use the Password grant in public clients (single-page apps, mobile apps without secure storage, etc.), because it requires handling the user’s raw password.
{% endhint %}

#### Requirements

To use the Password grant, you need:

* a **user account** in the VARIO-Cloud tenant
* the user’s **password**
* the App’s **Client ID** (`clientId`)
* the App’s **Client Secret** (`clientSecret`)
* the user must be **explicitly allowed** to use the Password grant in their user settings

#### Enabling the Password grant for a user

The Password grant is disabled by default for all users and must be enabled per user and per installation.

1. Sign in to your VARIO-Cloud tenant as an administrator.
2. Open the **“Benutzer”** (Users) menu.
3. Select the user who should be allowed to authenticate via Password grant.
4. Select the relevant **installation** (tenant / environment) for that user.
5. Activate the checkbox\
   \&#xNAN;**„OAuth-Password-Grant-Type erlauben“**\
   (Allow OAuth Password Grant Type).
6. Save your changes.

Only users with this option enabled can obtain tokens via the Password grant.

#### Requesting a token with the Password grant

Once the user is enabled, you can request an access token with a standard OAuth 2.0 Password grant request:

```
curl -X POST "https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=<user-name>" \
  -d "password=<user-password>" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>"
```

The response contains an `access_token` (and usually a `refresh_token`), which you then use for API calls.

***

### Authorization Code grant

The **Authorization Code grant** is the standard flow for **web applications** and other clients that can handle browser redirects.\
The user signs in via the VARIO-Cloud login page, and your App never sees the user’s password.

#### When to use

* For **browser-based** or **server-side web apps** with a backend that can receive HTTP callbacks.
* When you want the user to explicitly **approve** the App’s access the first time it connects.

#### Requirements

To use the Authorization Code grant, you need:

* a **user account** in the tenant (the end-user who will authorize the App)
* the App’s **Client ID** and **Client Secret**
* a **running OAuth callback server**, i.e. a backend endpoint that:
  * is reachable from the internet, and
  * can receive the `redirect_uri` callback
* the callback URL must be **registered** for the App (according to your tenant configuration)

{% hint style="danger" %}
**Important**\
Unlike the Password grant, you **do not** send the user’s username/password to the token endpoint.\
The user authenticates directly against VARIO-Cloud in their browser and must **confirm** the access for your App on first connection in order to receive a valid token.
{% endhint %}

#### Typical flow

1. **Redirect the user** to the VARIO-Cloud authorization endpoint:

   ```
   curl GET https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/auth
       ?response_type=code
       &client_id=<your-client-id>
       &redirect_uri=<your-registered-redirect-uri>
   ```
2. The user logs in (if not already authenticated) and is asked to **grant access** to your App.
3. VARIO-Cloud redirects the user back to your `redirect_uri` with a `code` and `state` parameter.
4. Your backend exchanges the authorization code for tokens:

   ```
   curl -X POST "https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=<authorization-code>" \
     -d "redirect_uri=<your-registered-redirect-uri>" \
     -d "client_id=<your-client-id>" \
     -d "client_secret=<your-client-secret>"
   ```
5. The response contains an `access_token` (and usually a `refresh_token`), which you then use for API calls.