Workflow: Enroll an Oracle Radio Mobile Application

• Before You Begin.
• Step 1: Create a Device Registration.
• Step 2: Authenticate the Mobile Application.
• Step 3: Complete Device Registration.
• Step 4: Establish the Online Radio Session.
• Step 5: Verify the Enrollment.

Confirm the following requirements:

• The intended user exists and is active in the Public Safety and Security instance's Identity Domain.
• The corresponding Radio user is enabled and has radio.channel.list for WebSocket authentication.
• The Radio administrator has radio.enrollment.manage and radio.device.manage.
• The intended user has a supported Radio mobile application that can provide an opaque advertising ID for its installation.

Public Safety and Security provisions and maintains the public mobile OAuth client, callback, grants, authorization scope, and offline access. The administrator doesn't create or edit that configuration during device enrollment.

1. In Radio, select Devices.
2. Select Register device.
3. For Intended user, select the enabled Radio user who will register the application.
4. For Display name, enter a name that identifies this application installation.
5. For Expires at, enter a future date and time after which the registration value can't be used.
6. For a new device record, leave Reusable QR code cleared for this one-time workflow. Select Create QR code.
7. Give the QR value to only the intended user, and then select Done.

The value is short-lived and can be used only once. It supplies the Radio base URL, Identity Domain URL, public mobile client ID, authorization scope, and one-time registration grant. It doesn't contain the application's callback URI, a client secret, an access token, or a refresh token.

For the standalone administrator task, see Registering an Oracle Radio Device.

As the app user, scan the QR value and sign in as the intended user when prompted. The app performs the configuration, PKCE, token exchange, and validation actions described below; you don't enter OAuth parameters or copy tokens. QR setup and user sign-in are separate actions. For later sign-in failures, use session recovery.

1. In the supported Radio mobile application, scan the administrator-issued QR value. Allow camera access when prompted for scanning. If camera access was denied, use the app's permission guidance or your device's application settings to allow it.
2. Read the Radio base URL, Identity Domain URL, public mobile client ID, authorization scope, and one-time registration grant from the QR value.
3. Create a new authorization state value, nonce, and PKCE verifier and S256 challenge for this sign-in attempt.
4. Start the Identity Domain Authorization Code flow with the public mobile client ID and supported application callback. Request openid, offline_access, and the authorization scope supplied in the QR value.
5. Use the supplied authorization scope exactly as provided. Don't construct, normalize, or hard-code it.
6. Have the intended user sign in, and allow the browser to return through the application's supported callback.
7. Validate the callback state, exchange the authorization code with the PKCE verifier, and validate the ID token signature, issuer, audience, expiration, and nonce.

Protect the authorization code, PKCE verifier, access token, refresh token, and ID token. Don't put them in a URL, command line, application log, or support record. See Authenticate and Register the Radio Mobile Application.

Run the Radio REST completeDeviceRegistration operation as the authenticated intended user. Send the Identity Domain bearer access token in the Authorization header and supply these request properties:

For a registration request and response example, follow the quick start through REST verification and the first WebSocket messages.

Confirm that Radio returns the registered device. Store its Radio device ID as protected application-installation state. The registration grant and device ID don't replace the bearer access token. For the operation path and authorization boundary, see Device Registration and Management Operations.

1. Run the authenticated heartbeatRadioDevice operation for the returned Radio device ID while the application is active.
2. Construct the WebSocket URL from the registration descriptor's radioBaseUrl: use wss, the same hostname and any explicitly supplied port, and /ws/radio. Open the connection with the returned device ID in the X-Oracle-Radio-Device-Id header. After it opens, send the bearer access token in AUTH and wait for AUTH_SUCCESS.
3. Send WHO_AM_I and verify that the response identifies the intended Radio user and the expected connection-local state.
4. Send PING and verify that the connection returns PONG.

The access token authenticates the user. The Radio device ID binds the connection to the registered installation and renews its online state; it is not a credential. Supply it exactly once: a malformed, repeated, or unknown supplied ID causes authentication to fail. Device heartbeat and socket connectivity do not establish audio readiness. See Workflow: Managing an Oracle Radio WebSocket Session.

1. In Radio, select Devices.
2. Find the new device by its display name or intended user.
3. Confirm that its intended user and display name match the registration and that the expected advertising ID is recorded.
4. After Radio receives an authenticated heartbeat, confirm that the device reports its current best-effort online state.

Find answers to common questions about this Oracle Radio mobile workflow.

Does the QR value authenticate the user or device?

No. It supplies public client configuration and a short-lived, one-time registration grant. The user must sign in, and protected Radio REST requests require a valid bearer access token. For WebSocket, send the access token in AUTH when authenticating or renewing the session.

Do I configure the mobile callback or authorization scope?

No. Public Safety and Security maintains the supported public mobile OAuth configuration. The application uses its supported callback and the authorization scope supplied in the QR value.

Why can the device remain online briefly after disconnecting?

Radio derives a best-effort online state from recent authenticated heartbeats, so the state can remain online briefly after the application stops or loses its connection.

For more questions, see Radio Devices and Registration.

• Use Managing Oracle Radio Devices to list, inspect, rename, re-register, or delete registered installations.
• Review the supported device operations in Device Registration and Management Operations.
• Use the WebSocket workflows after the authenticated connection is established.
• Handle request and connection failures as described in Oracle Radio API Errors.