Authenticating against the UniPhi API using an OAuth 2.0 App Registration

1 hour ago

5 min read

What is OAuth, in plain English?

OAuth can be seen as a guest pass system for software. Instead of handing your actual username and password to every app or system that wants to talk to UniPhi, OAuth lets you issue a special, limited-purpose pass instead. That pass:

• Proves who (or what) is asking to get in, without exposing your real login details.

• Can be handed to a machine, an integration, or an app.

• Can be revoked or replaced at any time without changing your own password.

In UniPhi, this "pass" is called an OAuth 2.0 App Registration. It's how other systems — reporting tools, mobile apps, integrations with other software — securely connect to the UniPhi API on your behalf.

There are two different ways to issue this pass in UniPhi, depending on who or what is doing the connecting. The rest of this article explains both, and walks through setting one up.

Client Credentials vs. Authorization Code with PKCE: which One Do I Need?

UniPhi supports two OAuth 2.0 grant types. You'll only ever need one of them for a given integration, and the choice comes down to a single question: is a human logging in, or is it just two systems talking to each other?

Grant	When to use it
Client Credentials (recommended default)	Server-side, machine-to-machine integrations where the client secret can be stored securely
Authorization Code with PKCE	Apps that can't keep a secret safe — e.g. mobile apps or browser-based JavaScript apps

Client Credentials is for when two systems talk to each other with no human involved. Picture a nightly process that automatically pulls data from UniPhi into a reporting tool — nobody is sitting there logging in, it's machine-to-machine. The application has its own "ID and password" (kept safely on a secure server) and uses those to prove who it is. You choose this when the application is acting on its own behalf, not on behalf of any particular user.

Authorization Code with PKCE (pronounced "pixy") exists specifically for situations where you cannot securely store the Application Secret — most commonly, a real person logging in through a mobile app or a browser-based app. Anything installed on a phone or running in a browser can be picked apart by a curious user, so you can't safely hide a secret inside it. PKCE solves this with a one-time handshake: the app generates a fresh, single-use secret for each login attempt, so even if part of the exchange is intercepted, it can't be reused to complete a login. You choose this when the application is acting on behalf of a specific user who signs in.

To answer the question: - Is it a human logging in, especially through a mobile app, desktop app, or browser-based app? Use PKCE. - Is it just one trusted backend system talking to another, with no human involved? Use Client Credentials.

All UniPhi OAuth clients support Client Credentials by default. PKCE must be explicitly enabled per client (see below).

Who should set this up?

App Registrations are created by an Administrator, under Configuration > Authentication > OAuth.

When a Registration is created, UniPhi generates two things: a Client ID (username-like to identify the registration, not sensitive) and a Client Secret (password-like, to prove the registration is who it claims to be, sensitive).

The Secret is shown only once, at the moment the registration is created. After that, UniPhi doesn't display it again, so if you lose it, you can only regenerate a new one (which invalidates the old one).

As a best practice, Registrations should be created by an Administrator or a technical/semi-technical person who will actually be using the Client ID and Secret.

If an Administrator does need to create the Registration on someone else's behalf and pass the credentials on afterwards, they need a secure way to transmit the Secret.

One approach: place the secret in a text file inside a password-protected .zip, email the zip file, and send the password to unzip it separately (e.g. via SMS). Note this isn't possible with Windows' built-in zip tool — 7-Zip is a free application that supports password-protected archives and works well for this.

Best-practice setup checklist

Before creating a registration, keep these principles in mind:

1. Create a separate App Registration for each integration you build. Don't reuse one registration across multiple integrations.

2. Name it clearly so it's obvious at a glance which integration it belongs to.

3. Impersonate a service account where possible. Every App Registration acts on behalf of a licensed UniPhi user.

4. Copy the Secret immediately. It's only ever displayed once, at creation time. If it's lost or compromised, you'll need to regenerate it, which invalidates the old one immediately.

Step-by-step: creating an App Registration

1. Log in as an Administrator and go to Configuration > Authentication > OAuth.

2. Click Add to open the "Add New OAuth Registration" screen.

3. Enter a Registration Name that clearly identifies the integration.

4. Under Impersonate, select the user the Registration will act as, ideally a service account created for this purpose (see best practices above).

5. Click Save.

6. Copy the Client ID and Client Secret shown and store them securely (encrypted storage recommended).

7. If this integration needs the PKCE grant (e.g. a mobile or browser-based app), edit the registration, enable Authorization Code with PKCE, and enter the redirect URI(s), comma-separated.

Endpoints

Endpoint	URL
Token	https://{your-uniphi-deployment}/oauth/token
Authorization	https://{your-uniphi-deployment}/oauth/authorize

The token endpoint returns an access token, a refresh token, and an expiry (in seconds). Requests to it must be sent as a POST with a body of MIME type application/x-www-form-urlencoded.

Client Credentials Grant

Make a single POST request to the token endpoint with:

grant_type: client_credentials client_id: {client id} client_secret: {client secret}

That's it, no user interaction required, which is what makes this grant suitable for unattended, server-to-server integrations.

Authorization Code with PKCE Grant

PKCE proves that the same actor makes both the authorize request and the token request, by pairing a hashed code challenge with its unhashed code verifier.

1. Create a code verifier and challenge

Generate a secure random string (36 characters is optimal): this will be your code verifier.Hash it with SHA-256: the result will be your code challenge.

2. Direct the user to the authorization URL

https://{your-uniphi-deployment}/oauth/authorize?response_type=code&client_id={client id}&redirect_uri={redirect endpoint}&code_challenge={hashed code challenge}&code_challenge_method=S256

3. Receive the authorization code

Once the user authorizes access, they're redirected to:

{redirect endpoint}?code={code}

4. Exchange the code for tokens

POST to the token endpoint with:

grant_type: authorization_code code: {code from redirect uri} code_verifier: {code verifier} client_id: {client id} client_secret: {client secret}

Using the Access Token

Include the token as a Bearer token in the HTTP header of each API request:

Authorization: Bearer 81mYoEkN8e5dwibvwoEodLoCguBSuT65kTL...

When the token expires, use the refresh token to obtain a new one (or re-authenticate, depending on the grant type used).

Token lifetimes and handling

Token	Lifetime	Handling
Access token	7 days	Dispose of it immediately after use — avoid persisting it
Refresh token	30 days	Avoid storing where possible; if persistence is required, store it encrypted

A note on Microsoft Power BI

Power BI does not support OAuth 2.0 in a user-friendly manner. For Power BI connections, enable Microsoft Authentication in UniPhi instead, and connect using the "Organizational Account" option rather than an OAuth App Registration.