> For the complete documentation index, see [llms.txt](https://oten.gitbook.io/identity-support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oten.gitbook.io/identity-support/integration/integration-document/idp-integration/native-application-client.md).

# Native application client

This page helps you determine if a native application is the right choice for the application you are integrating with OXU Identity and how to configure guiding.

This section is part of OAuth 2.0 / OpenID Connect (OIDC) integration.\
Currently, the Quick Start guide and technical support for this client type are optimized for the **Swift (iOS)** framework.

### Why am i here? <a href="#i-am-new.-where-should-i-start" id="i-am-new.-where-should-i-start"></a>

If this is your first time integrating with Oten Identity, start with:

* **Creating an** [**integration app**](/identity-support/integration/integration-document.md)
* **Creating a regular web application client**
* **Using quick start to integrate authentication into your Swift native application**

**What is a Native Application?**

In the context of Oten Identity, a native application is an application installed directly on a user’s device, such as a mobile or desktop app.

Examples include:

* iOS and Android mobile applications
* Desktop applications running on user devices

Native applications cannot securely store client secrets, so they use authentication flows designed specifically for installed apps.

Choose a native application if your app:

* Runs on a user’s device (mobile or desktop)
* Does not have a secure backend for storing secrets
* Uses system browsers or embedded web views for login

#### Key characteristics include:

* Authentication is handled using OAuth 2.0 / OpenID Connect
* Uses redirect-based authentication with custom schemes or loopback URLs
* Integrates with Oten Identity using the authorization code flow with PKCE
* Does not use a client secret
* Client configuration is managed through the Oten Developer Portal

**Prerequisites**

Before you begin, ensure that you have:

* An active OXU **Developer account**
* An **Integration App** already created
* A **Native Application client** selected
* **Xcode 14.0 or later**
* An **Apple Developer account** (for device testing)
* Basic understanding of:
  * OAuth 2.0
  * OpenID Connect
  * iOS app development with Swift

### I already understand. How do I process step by step?

#### Step 1: Open create client

1. Sign in to the [**OXU Developer portal**](https://developer.oten.live/)
2. Navigate to: **App management** → **Integration app** → **App detail**
3. Select **Create app**<br>

   <figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FMvXiCDEkpv8yhtZvORPe%2Fimage.png?alt=media&amp;token=e39f8876-498c-4426-bddf-726b2641f603" alt=""><figcaption></figcaption></figure>

You are now on the **Create client** screen.

#### Step 2: Select client type <a href="#step-2-select-client-type" id="step-2-select-client-type"></a>

Select **Native application** as the client type.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FzmCpaB46DFC1cT4LMyt1%2Fimage.png?alt=media&amp;token=3ed69dae-6e2e-4d48-8d1a-7213527fff93" alt=""><figcaption></figcaption></figure>

This client type is designed for mobile and desktop applications.

#### Step 3: Review client characteristics

Confirm that the Native Application client:

* Is intended for mobile or desktop platforms
* Uses redirect URIs for authentication
* Does not require a client secret

#### Step 4: Configure redirect URIs

Under **Configure client URIs**, add your redirect URIs.

Examples:

* Custom scheme URI for iOS
* Local development callback URI

Only URIs listed here will be accepted during authentication.

`https://your-app.com/callback, http://localhost:3000/callback`\ <br>

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FQi3ZULc3NPCzB8MGA1YS%2Fimage.png?alt=media&amp;token=08d9da68-4801-482c-a803-38ac6361e0b8" alt=""><figcaption></figcaption></figure>

#### Step 5: Create client <a href="#step-5-create-the-client" id="step-5-create-the-client"></a>

Click **Create client** to generate the Native Application client.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FWZAn5hjQJJVVTfjLJPDf%2Fimage.png?alt=media&amp;token=b6cfd784-ef33-422c-920d-cc5b1e439c94" alt=""><figcaption></figcaption></figure>

You will be redirected to the **Client detail** page.

#### Step 6: Integrate application <a href="#step-6-integrate-your-application" id="step-6-integrate-your-application"></a>

**6.1 Quick start**

**6.1.1 Select your technology**

In the **Quick Start** tab, select **Swift** as your technology to receive tailored code samples.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FOgwGRezEa1TpwsmXPnRa%2Fimage.png?alt=media&amp;token=1362f1eb-289f-455d-b61d-fc6394c1c9d4" alt=""><figcaption></figcaption></figure>

**6.1.2 Review prerequisites**

Before you begin, ensure that you have the following:

* **Xcode 14.0 or later**\
  Required to build and run the iOS application.
* **An Apple Developer account**\
  Needed for running the app on a physical device and managing signing capabilities.
* **An Oten Identity account**\
  An Integration App and Native Application client must be created in the Oten Developer Portal (see Step 2).

**iOS Version compatibility**

This Quick Start supports:

* **iOS 16.0 or later**
* **Swift 5.7 or later**

\
**6.1.3 Create a new iOS project**

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FmzjU6NkkeNDoWduUuZTC%2Fimage.png?alt=media&amp;token=8741dd74-a457-478c-8990-c7723a46e6e0" alt=""><figcaption></figcaption></figure>

Create a new iOS project in Xcode:

* File → New → Project
* Select **App** under iOS
* Choose **Swift** as the language
* Select **SwiftUI** or **Storyboard** as the interface
* Select **Swift** for Language
* Click **Next** and choose location

**6.1.4 Configure OXU IDP application**

Create and configure a Native application client in the Oten Developer portal.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FZpx32ruJvD6XWDAPzUYL%2Fimage.png?alt=media&amp;token=7fec800b-2742-417e-ae69-31c9fd65ac57" alt=""><figcaption></figcaption></figure>

1. Go to the **OXU Developer portal**
2. Click **Start integration → Create app**
3. Select **Native application**, then click **Create client**
4. Open the **Client details** page
5. Navigate to the **Configure** tab
6. Copy the **Client ID** from the Client Credentials section (used in Step 4)

**Redirect URI (custom URL scheme)**

Configure a custom URL scheme for iOS redirect handling: `yourapp://auth`

The redirect URI must exactly match:

* The value configured in the Oten Developer Portal
* The URL scheme registered in the Xcode project
* The redirect URI used in `OtenAuthService`

**6.1.5 Add Oten authservice**

Create a new Swift file named `OtenAuthService.swift`.

This service implements OAuth 2.0 Authorization Code Flow with PKCE using `ASWebAuthenticationSession`.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FtZkFr09WsM8BKWEpXBnE%2Fimage.png?alt=media&amp;token=d77c307b-539c-4ef4-8cce-0e83a6e21572" alt=""><figcaption></figcaption></figure>

Responsibilities include:

* Generating PKCE code verifier and challenge
* Creating authorization requests
* Handling redirect callbacks
* Exchanging authorization codes for tokens
* Managing authentication state

**Security notes**

* **PKCE (Proof Key for Code Exchange)** is used to prevent authorization code interception
* A random **state parameter** is generated for each login attempt to mitigate CSRF attacks
* The callback validates that the returned state matches the original value

\
**6.1.6 Configure app on launch**

Update the application entry point to initialize `OtenAuthService` when the app launches.

This step configures the OAuth endpoints and binds the application to the Oten client created in the Developer Portal.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2F8iRnlu7SZWm47w9Cp81t%2Fimage.png?alt=media&amp;token=197d7133-e872-4d32-ae96-f144ca2da956" alt=""><figcaption></figcaption></figure>

Provide the following values:

* **Client ID**\
  The Client ID obtained from the Client Credentials section in the Oten Developer Portal.
* **Redirect URI**\
  The custom URL scheme configured earlier (for example: `yourapp://auth`).
* **Authorize URL**\
  Oten authorization endpoint used to start the login flow.
* **Token URL**\
  Oten token endpoint used to exchange the authorization code.

This configuration must be completed before any authentication action is triggered.<br>

**6.1.7 Create login UI**

Create the main user interface that allows users to authenticate using Oten.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FstDt6HeXjqFaaeB5rlXM%2Fimage.png?alt=media&amp;token=6fd20865-53ae-4ae9-aa2e-2b776d717f96" alt=""><figcaption></figcaption></figure>

This step defines a basic login experience that includes:

* A **Login with Oten** action that initiates the OAuth flow
* Handling authentication state
* Displaying authenticated user information after successful login
* Providing a logout option

The example implementation supports both:

* **SwiftUI** (`ContentView.swift`)
* **UIKit** (`ViewController.swift`)

Choose the UI framework that matches your project setup.

**6.1.8 Run your app**\ <br>

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2Fbm7Wvv6qzKzZKiqwDs7q%2Fimage.png?alt=media&amp;token=8cf94ed1-21e9-4887-9715-23e1a97ec86e" alt=""><figcaption></figcaption></figure>

Build and run the application using Xcode.

1. Open the project in **Xcode**
2. Select an **iOS Simulator** or a **physical device**
3. Press **⌘R (Command + R)** to run the app

**Sign In**

1. Tap **Login with Oten**
2. You will be redirected to the [**Oten login page**](https://account.oten.com/)
3. Complete authentication
4. After a successful login, you will be redirected back to the app and see your user information

**Note**: If the app does not return after login, verify that the Redirect URI is configured correctly in both the Oten Developer Portal and the Xcode project.

#### Step 7: Completion & next actions

Once authentication is working:

* Test on real devices
* Review security settings
* Prepare for production deployment

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FsjWww5aGlyRwL3Kvw53g%2Fimage.png?alt=media&amp;token=8a322f4c-53ce-48f5-b6eb-279845df2a1b" alt=""><figcaption></figcaption></figure>

#### Step 8: Additional configuration (optional)

**8.1 Client credentials**

The **Client credentials** section provides the information required to configure the SDK.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FIHqQXjsGzsx3hSPKqCwN%2Fimage.png?alt=media&amp;token=194eb57a-d5ba-4653-8b87-eb34261329b3" alt=""><figcaption></figcaption></figure>

* **Client ID**\
  A public identifier for your application. Use this value when initializing the Oten SDK in your app.
* **Client ssecret**\
  A confidential value used for server-side authentication.

**Important**

* Keep the Client Secret private
* Do not expose it in mobile apps, frontend code, or public repositories
* Only use the Client Secret in secure backend environments

For **native iOS applications**, authentication is handled using **OAuth 2.0 with PKCE**, and the **client Secret is not required**.

**8.2 Configure client URIs**

This section defines the application URLs used during authentication flows.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FC3m6woY4EcOi5yX6TXD2%2Fimage.png?alt=media&amp;token=8cf06198-c2fe-44ab-925d-f8015b635f4a" alt=""><figcaption></figcaption></figure>

**Redirect URIs**\
List of allowed callback URLs where users are redirected after a successful login.\
Enter one or more URLs, separated by commas or new lines.

**Allow origins (CORS)**\
List of origins allowed to make cross-origin (CORS) requests to Oten Authentication APIs.\
This is typically required for browser-based applications.

**Note**:

* Redirect URIs and Allowed Origins must exactly match your application URLs.
* Requests from unlisted or invalid URLs will be rejected.

**8.3 OpenID connect**

This section provides OpenID Connect–related configuration for the client.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FwLw1ftPrzU1r7gDY72rj%2Fimage.png?alt=media&amp;token=9bc071f0-d484-4ce7-8ef0-0fd68faa5253" alt=""><figcaption></figcaption></figure>

**Back-channel logout URI**\
Server endpoint that receives logout notifications from Oten Identity.\
When a logout event occurs, Oten calls this endpoint to invalidate user sessions without using browser redirects.

**This setting is optional and is typically used for:**

* Server-managed session invalidation
* Single Logout (SLO) across multiple applications

If your application does not require back-channel logout, this field can be left empty.

**Additional OpenID** **onnect** settings are optional and intended for advanced integration scenarios.

<figure><img src="https://40810359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNLjw84bGTVza9xA8NxxB%2Fuploads%2FZAH1mIoSeg6L99loXlcD%2Fimage.png?alt=media&amp;token=1b546d3c-9ac2-4d85-bb85-dba270bb5f03" alt=""><figcaption></figcaption></figure>