# Device Authentication Methods Used in KCloud-Platform-IoT: OAuth2 Grant Types Explained

> Explore KCloud-Platform-IoT's device authentication with ten OAuth 2.0 grant types, including Device Code flow. Learn how Spring Security OAuth2 secures your IoT ecosystem.

- Repository: [laokou/kcloud-platform-iot](https://github.com/koushenhai/kcloud-platform-iot)
- Tags: how-to-guide
- Published: 2026-03-05

---

**KCloud-Platform-IoT supports ten distinct OAuth 2.0 grant types—including the Device Code flow for headless IoT devices—to authenticate devices via Spring Security OAuth2 Authorization Server.**

The **koushenhai/kcloud-platform-iot** repository implements a comprehensive, standards-based authentication layer for IoT ecosystems. Understanding the **device authentication methods used in KCloud-Platform-IoT** is essential for integrating constrained devices, mobile apps, and service-to-service communications securely.

## OAuth 2.0 Grant Types Supported in KCloud-Platform-IoT

According to the source configuration in [`application.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/application.yml) (lines 95-106), the platform configures a rich set of **OAuth 2.0 grant types** within the Spring Security OAuth2 Authorization Server. Each grant exposes a distinct authentication method tailored to specific device capabilities:

- **username_password**: Devices authenticate using pre-assigned credentials (username and password).
- **mail**: One-time email verification code authentication for devices with email capabilities.
- **mobile**: SMS verification code authentication for cellular-connected devices.
- **test**: Special test-only flow reserved for CI and demo environments.
- **refresh_token**: Silent token refresh without requiring repeated user interaction.
- **client_credentials**: Machine-to-machine authentication where devices hold client secrets.
- **urn:ietf:params:oauth:grant-type:device_code**: The **Device Code flow** designed for headless IoT devices that cannot display a user interface.
- **urn:ietf:params:oauth:grant-type:jwt-bearer**: Token exchange for devices already possessing signed JWTs.
- **urn:ietf:params:oauth:grant-type:token-exchange**: Converts short-lived device tokens to long-lived service tokens.
- **authorization_code (PKCE)**: QR-code or short URL flows where users scan to authorize devices via Proof Key for Code Exchange.

## Device Code Flow for Headless IoT Devices

The **Device Code grant** (`urn:ietf:params:oauth:grant-type:device_code`) serves as the primary mechanism for authenticating headless devices in KCloud-Platform-IoT. This flow decouples the device requesting access from the user authorizing it, solving the input-constraint problem common in IoT hardware.

The authentication sequence follows these steps:

1. **Device requests authorization**: The device calls the device-authorization endpoint (`POST /oauth2/device_authorization`) to obtain a `device_code` and `user_code`.
2. **Device polls for token**: The device repeatedly polls `/apis/auth/api/v1/oauth2/token` with `grant_type=device_code` until authorization completes.
3. **User authorizes**: On a separate device (mobile app or web UI), the user enters the `user_code` and approves the request.
4. **Server issues token**: Once approved, the token endpoint returns an `access_token` and optional `refresh_token`.
5. **Device accesses APIs**: The device includes the token in the `Authorization: Bearer` header for subsequent IoT API calls.

## Implementation Architecture

The authentication logic resides in the **`laokou-auth`** module, with specific providers handling each grant type:

- **[`laokou-service/laokou-auth/laokou-auth-infrastructure/src/main/java/org/laokou/auth/config/authentication/OAuth2UsernamePasswordAuthenticationProvider.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-auth/laokou-auth-infrastructure/src/main/java/org/laokou/auth/config/authentication/OAuth2UsernamePasswordAuthenticationProvider.java)**: Implements the username/password grant validation.
- **[`laokou-service/laokou-auth/laokou-auth-infrastructure/src/main/java/org/laokou/auth/config/authentication/OAuth2MobileAuthenticationProvider.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-auth/laokou-auth-infrastructure/src/main/java/org/laokou/auth/config/authentication/OAuth2MobileAuthenticationProvider.java)**: Handles SMS verification logic.
- **[`laokou-service/laokou-auth/laokou-auth-infrastructure/src/main/java/org/laokou/auth/config/authentication/OAuth2MailAuthenticationProvider.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-auth/laokou-auth-infrastructure/src/main/java/org/laokou/auth/config/authentication/OAuth2MailAuthenticationProvider.java)**: Processes email verification codes.

Central configuration defining supported grant types and TTL settings appears in **[`laokou-service/laokou-standalone/laokou-standalone-auth/laokou-standalone-auth-start/src/main/resources/application.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-standalone/laokou-standalone-auth/laokou-standalone-auth-start/src/main/resources/application.yml)** (lines 95-106). Frontend clients interact with these endpoints through the wrapper defined in **[`ui/src/services/auth/auth.ts`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/ui/src/services/auth/auth.ts)**, which provides type-safe access via the definitions in **[`ui/src/services/auth/typings.d.ts`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/ui/src/services/auth/typings.d.ts)**.

## Practical Integration Example

Below is the TypeScript implementation from the UI service layer demonstrating how devices poll for tokens using the Device Code grant:

```typescript
// ui/src/services/auth/auth.ts
export async function getDeviceToken(deviceCode: string): Promise<API.Result> {
  const url = '/apis/auth/api/v1/oauth2/token';
  const params: API.OAuth2Param = {
    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
    device_code: deviceCode,
    client_id: '95TxSsTPFA3tF12TBSMmUVK0da',
  };
  return request<API.Result>(url, {
    method: 'POST',
    data: params,
  });
}

```

The `OAuth2Param` interface in [`typings.d.ts`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/typings.d.ts) ensures type safety for the request payload, requiring `grant_type`, `device_code`, and `client_id` parameters. The `client_id` must match the device-code client defined in the [`application.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/application.yml) PKCE client block (lines 124-132).

## Summary

- **KCloud-Platform-IoT** exposes **ten OAuth 2.0 grant types** to accommodate diverse device authentication scenarios, from headless sensors to mobile applications.
- The **Device Code flow** (configured in [`application.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/application.yml) lines 104-105) provides the primary authentication path for input-constrained IoT devices.
- **Spring Security OAuth2 Authorization Server** powers the backend, with dedicated `AuthenticationProvider` classes handling credential validation for each grant type.
- Frontend and device clients use the **[`auth.ts`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/auth.ts)** service wrapper to ensure consistent, type-safe communication with the token endpoint at `/apis/auth/api/v1/oauth2/token`.
- All authentication configurations are centralized in the **standalone auth service**, enabling centralized security policy management across the IoT ecosystem.

## Frequently Asked Questions

### What is the primary device authentication method in KCloud-Platform-IoT?

The **Device Code flow** (`urn:ietf:params:oauth:grant-type:device_code`) serves as the primary method for headless IoT devices. This OAuth 2.0 grant type allows devices without browsers or input capabilities to authenticate by displaying a code to the user on a secondary device, such as a smartphone.

### How does the Device Code flow work for IoT devices?

The device first requests a `device_code` from the authorization server, then polls the token endpoint until the user completes authorization on a separate device. According to the source code in [`auth.ts`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/auth.ts), devices call `/apis/auth/api/v1/oauth2/token` with `grant_type=device_code` and wait for the server to return an `access_token` once the user approves the request.

### Where is the OAuth2 configuration defined in KCloud-Platform-IoT?

All supported grant types and client configurations are defined in **[`laokou-service/laokou-standalone/laokou-standalone-auth/laokou-standalone-auth-start/src/main/resources/application.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-standalone/laokou-standalone-auth/laokou-standalone-auth-start/src/main/resources/application.yml)** (lines 95-106). This file configures the Spring Security OAuth2 Authorization Server, including token TTLs, client credentials, and enabled grant types.

### Can devices use alternative authentication methods besides Device Code?

Yes. The platform supports **username/password**, **SMS (mobile)**, **email (mail)**, **client_credentials**, **JWT-bearer**, and **PKCE authorization code** flows. Each method has a dedicated `AuthenticationProvider` implementation in the `laokou-auth-infrastructure` module, allowing developers to choose the appropriate mechanism based on device capabilities and security requirements.