Overview of Public Safety and Security

Public Safety and Security has two customer-facing service boundaries. OCI administrators use the regional API to manage Public Safety and Security instances and work requests. Each active Public Safety and Security instance returns an API service endpoint and a user-interface endpoint for Oracle Radio.

OCI Identity Domains provides authentication for users and clients. Oracle Radio separately authorizes application access by using enabled Radio users, Radio group permissions, and applicable channel access rules.

1. An OCI administrator prepares a compartment, IAM authorization, an OCI Identity Domain, and an initial administrator Identity Domain user.
2. The administrator creates a regional Public Safety and Security instance. Public Safety and Security provisions and maintains the authentication applications required for the instance, including the supported Radio mobile application's callback, grants, resource scope, and offline access, and returns a work request for the asynchronous create operation.
3. When the instance reaches ACTIVE, its details include serviceEndpoint for API requests and uiEndpoint for Oracle Radio.
4. An authorized Radio administrator signs in and enables Radio access for Identity Domain users. Radio groups and permissions determine which application operations each enabled user can perform.
5. Authorized users access Oracle Radio through supported clients. Channel access rules can further limit channel visibility and communication behavior.

Create, update, move, and delete operations are asynchronous. Continue to monitor the returned work request until the operation reaches a terminal state.

Oracle Radio provides a ready-to-use mobile application for supported Radio workflows. The mobile instructions in this guide describe the Oracle-provided application. The features available to you depend on your permissions and your organization's configuration.

The supported authentication paths are the Oracle-provided browser application and Radio mobile clients. Bearer-token authentication is supported for mobile clients; command-line, custom-browser, and server authentication contracts are not currently supported. See client authentication. API examples describe requests used by supported clients, not a procedure for creating a separately authenticated custom application.

See Using Oracle Radio for mobile setup guidance and device registration. For your first iPhone voice and text exchange, follow the Oracle Radio iPhone quick start.

Use the following topics to administer Public Safety and Security resources, operate Oracle Radio, or develop supported clients.

The following key concepts describe Public Safety and Security and Oracle Radio.

Public Safety and Security instance

A regional OCI resource representing one isolated managed Public Safety and Security environment.

Work request

A customer-visible progress record that reports the outcome of an asynchronous Public Safety and Security instance operation.

Service endpoint

The HTTPS entry point returned for an active instance. Use this value instead of constructing an instance URL.

Identity Domain user

A person or agent authenticated by the Identity Domain configured for the instance.

Radio user

An enabled Oracle Radio authorization record linked to an Identity Domain principal.

Radio group

A Radio-owned group that grants Radio permissions to its members.

Channel

A named boundary for authorized live voice, text, presence, and communications history. Administrators can manage channels and their access rules.

Channel access rule

A Radio rule that further limits actions for a specific channel.

Channel subscription

A saved user preference for a channel.

Joined channel

A channel joined by the current live client connection.

Talk token

A short-lived floor-control grant that permits one user to transmit on one channel.

Access token

An OCI Identity Domain bearer credential used to authenticate a native or API client.

Radio device

A record representing one registered installation of the Radio mobile application. The Radio device ID is application state, not an authentication credential.

Registration grant

A value with an expiration that lets an intended enabled Radio user register an application installation. One-time use is the default; reusable registration allows that user to enroll multiple installations until expiry or revocation. The application supplies an opaque advertising ID when it completes registration.

Choose the API by the task your client needs to perform. REST uses individual requests and responses; WebSocket keeps a connection open for two-way messages and live events. A Radio integration can use both.

REST API

Your client sends an HTTP request and receives a response. Use the documented REST operations to retrieve information or change saved application state, such as registering a device, reading channel details, or managing saved channel subscriptions. To check for later changes, make another request.

WebSocket API

Your client establishes an authenticated connection over which both the client and server can send messages. Use the WebSocket operations for live channel communication, push-to-talk control, audio, text messages, and presence updates. Server events can arrive without a separate request for each update.

For example, use REST to retrieve channel information and manage a saved subscription, then use WebSocket to join the current connection to a channel and exchange live messages. Saving a subscription doesn't join a live connection or grant a talk token.

WebSocket clients must handle authentication, interrupted connections, and restoring live subscriptions after reconnecting. Follow the connection lifecycle guidance. Choose it when the task requires live interaction, not as a substitute for every REST operation.

The APIs aren't interchangeable. Each workflow's tabs describe the available methods; a REST operation doesn't imply a matching WebSocket operation. Protected operations on both interfaces require the applicable authentication, Radio permissions, and channel access.

An OCI administrator or automation client sends an authorized request to the regional Public Safety and Security control plane. The control plane validates the request, creates or updates the instance record, and returns a work request for an asynchronous change. Get both resources to observe customer-visible state and progress.

After provisioning, a Radio client connects through the appropriate managed instance API, user-interface, or WebSocket entry point. OCI Identity Domains authenticates the principal. Oracle Radio resolves the principal to an enabled Radio user and applies Radio permissions and channel access before processing REST or WebSocket actions.

• Identity Domain group membership doesn't grant Oracle Radio permissions. Configure Radio users, groups, permissions, and channel access separately.
• The Public Safety and Security instance update operation doesn't change the configured Identity Domain URL or initial administrator Identity Domain user.
• You can't use an instance create or update request to supply, replace, or change the callback, grants, scopes, or offline-access settings of authentication applications managed by Public Safety and Security.
• Don't construct an API or Oracle Radio URL from an instance OCID, display name, or raw API Gateway hostname. Use the returned serviceEndpoint or uiEndpoint for the applicable interface.

Public Safety and Security instances and work requests are regional OCI resources. Select the region where you want to manage the instance before using the Console or a regional API endpoint. The Public Safety and Security create request doesn't require a customer-selected availability domain.

For region identifiers and information about regions and availability domains, see About Regions and Availability Domains.

Public Safety and Security instances and work requests have Oracle Cloud IDs (OCIDs). Public Safety and Security instance configuration also references the compartment OCID and initial administrator Identity Domain user OCID. For more information, see Resource Identifiers.

Oracle Radio users, groups, channels, communications, access tokens, and talk tokens are application or identity concepts and aren't Public Safety and Security instance OCIDs.

Use the OCI Console or OCI REST API to manage Public Safety and Security instances and work requests. OCI also provides SDKs, the CLI, and Cloud Shell for supported service interfaces. For general REST API guidance, see Using REST APIs.

Use OCI authentication to manage Public Safety and Security instances and work requests. To operate Radio in its web application, sign in with the gateway-managed browser session. The supported mobile application uses OAuth with PKCE to obtain user access tokens for its own REST requests and WebSocket connection. The client and task determine the method; REST versus WebSocket doesn't select a different user identity. Follow Identity setup for instance prerequisites and the ordered authentication steps for Radio.

Before creating a Public Safety and Security instance, prepare:

• A customer compartment and the IAM policies required to create and manage Public Safety and Security resources.
• The OCI Identity Domain URL used to authenticate Public Safety and Security users. See Getting an Identity Domain's Details.
• The Identity Domain user OCID of the initial Public Safety and Security administrator. See Viewing User Details.
• Public Safety and Security manages the authentication applications required for the instance.

See Getting Started with Public Safety and Security for the complete first use sequence.

Use OCI IAM groups for users and dynamic groups for eligible resource principals. Grant only the IAM policies needed for Public Safety and Security resource administration and observability. The Identity Domain service policy separately authorizes the Public Safety and Security service, not these user groups.

For Oracle Radio, an authenticated Identity Domain principal must also have an enabled Radio user record. Radio administrators use Radio groups and permissions to authorize application behavior. Channel access rules can further restrict activity for a particular channel.

Configure OCI IAM policies for three distinct purposes:

• Identity Domain service access (IDCS): Authorize Public Safety and Security to provision its authentication applications and look up users in the selected Identity Domain. This required service policy belongs in the tenancy's root compartment. Follow the setup steps before creating an instance.
• Public Safety and Security instances and work requests: Authorize OCI IAM user groups to inspect, read, or manage regional Public Safety and Security resources. Choose the appropriate resource policies for each group's role.
• Metrics and events: Separately authorize users to query Public Safety and Security metrics, view OCI Events rules, or read OCI Audit records. These are different resource types with separate read policies; Public Safety and Security instance-management access doesn't include them automatically.

These policies don't replace Radio authorization. Radio administrators assign application permissions through Radio groups, with additional channel access rules where applicable. See the policy reference for statements and Getting Started for the setup sequence.

The following Public Safety and Security resource limits are regional and per tenancy.

For a list of applicable limits and instructions for requesting a limit increase, see Service Limits.

Oracle provides security of cloud infrastructure and operations, such as cloud operator access controls and infrastructure security patching. You are responsible for securely configuring your cloud resources. Security in the cloud is a shared responsibility between you and Oracle. See Security for Public Safety and Security.

Oracle's security responsibilities include:

• Physical security: Protect the global infrastructure that runs OCI services, including its hardware, software, networking, and facilities.

Your security responsibilities include:

• Access control: Give users only the access necessary to perform their work. Configure OCI IAM policies and Oracle Radio permissions for their roles.
• Physical security: Limit physical access to devices used with Oracle Public Safety and Security, including mobile devices running Oracle Radio.

Protect network access and bearer tokens, and apply organizational privacy and retention policies to communications data. See the security responsibilities for more information.