Oracle Cloud Infrastructure Documentation

Getting Started with Public Safety and Security

Prepare IAM, create a Public Safety and Security instance, confirm the initial administrator, and prepare Oracle Radio users, channels, and mobile devices.

Before You Begin

You need permission to work with the target compartment, Identity Domain, users, and policies and to create Public Safety and Security resources. The Identity Domain service policy and your Public Safety and Security resource permissions serve different purposes. To view metrics, Events rules, or Audit records, also request the appropriate read policies.

Choose the correct authentication method for OCI administration or Oracle Radio. Review the service limits before creating an instance.

Important

Grant least-privilege access to Public Safety and Security resources. Never put an access token or other credential in an API request field, CLI argument, tag, display name, or documentation example unless the interface explicitly requires it.

Step 1: Prepare the Identity Domain and IAM Policy

Use an existing compartment and Identity Domain or create a new compartment before creating the Public Safety and Security instance. The domain must contain an active user who will become the initial Radio administrator.

Public Safety and Security provisions and maintains the integrated applications required by the instance. Don't create or edit those applications as part of this procedure.

  1. In the OCI Console open the navigation menu, select Identity & Security, and then select Compartments.
    Create or select the compartment for the Public Safety and Security instance, and copy its OCID.
  2. Under Identity, select Domains.
    Use the compartment filter to find an existing domain, or create a domain in the intended compartment.
  3. Select the Identity Domain, verify that its status is Active, and copy its OCID and Domain URL.
  4. In the Identity Domain, select Settings, and then select Domain settings. Under Access signing certificate, enable Configure client access.
    Oracle Radio needs to read the domain's public signing keys without signing in to validate token signatures. This setting doesn't grant anonymous access to Radio. See the official OCI instructions for certificate access.
  5. Select Save changes.
  6. On the domain details page, select User management, and then select Users.
    Select the user who will initially administer Radio, verify that the user is active, and copy the user OCID.
  7. In Identity & Security, select Policies, and add the following statements to a policy in the root compartment.
    Add both statements to the same policy in your tenancy's root compartment. Enter each statement on a separate line and replace the <identity-domain-OCID> placeholders in both statements. Each statement authorizes different principals.
    Allow any-user to {idcs_appservice_create, idcs_appservice_get, idcs_appservice_delete, idcs_user_viewer} in tenancy where all {request.principal.type = 'domain', request.app.provisioning.principal.name = 'pss', request.app.provisioning.principal.type = 'service', target.resource.domain.id = '<identity-domain-OCID>'}

Allow service pss to {idcs_user_viewer} in tenancy where target.resource.domain.id = '<identity-domain-OCID>'
  8. Confirm that you have the compartment OCID, Identity Domain OCID and URL, and active initial-administrator user OCID.

The customer-owned compartment, Identity Domain, active initial administrator, and Public Safety and Security service policy are ready for instance creation.

Step 2: Create a Public Safety and Security Instance

Create the instance in the target compartment and associate it with the Identity Domain and initial administrator. For all available options, see instance creation.

Use the Identity Domain HTTPS origin only. An explicit default HTTPS port, :443, is accepted. Don't include credentials, a non-default port, a path, a query, or a fragment.

    1. In the OCI Console, open the Navigation menu, select Oracle Public Safety and Security, and then under Public Safety and Security, select Instances.
    2. Select Create Public Safety and Security Instance.
    3. Select the target compartment and optionally enter a display name.
    4. Select or paste the Identity Domain URL.
    5. Select or paste the OCID of the active Identity Domain user who will initially administer this instance.
    6. Add defined or free-form tags if required, and submit the request.

    Public Safety and Security creates the instance resource and returns a work request. During provisioning, Public Safety and Security verifies the initial administrator exists and is active, enables the corresponding Radio user, and adds that user to the Radio Administrators group.

  • Use the following command to create a Public Safety and Security instance:

    oci pss instance create \
    --compartment-id <compartment-OCID> \
    --identity-domain-url <identity-domain-url> \
    --admin-user-id <identity-domain-user-OCID>

    The response includes the Public Safety and Security instance OCID and the work request used to monitor provisioning.

    For a complete list of flags and variable options for CLI commands, see the Command Line Reference.

  • Run the CreateInstance operation with the compartment OCID, Identity Domain URL, and initial administrator Identity Domain user OCID. Use the work request returned by the operation to monitor provisioning.

Step 3: Monitor the Work Request

Creating the instance may take a few minutes, wait for the process to complete. Monitor the asynchronous create operation until it succeeds or reports an error. For more information, see work request details.

    1. Follow Listing Public Safety and Security Work Requests to open the instance's work requests.
    2. Select the work request returned by the create operation.
    3. Review the status, percent complete, related resources, and timestamps.
    4. Use the work request status to choose the next action.
      • If the status is SUCCEEDED, continue to the next step and verify that the Public Safety and Security instance is ACTIVE.
      • If the status is FAILED or NEEDS_ATTENTION, review the work request errors and log entries before retrying or changing the input.

  • Use the following command to get the current work request:

    oci pss work-request get \
    --work-request-id <work-request-OCID>

    If the operation fails, use the work-request error and log commands described in Public Safety and Security Work Requests.

    For a complete list of flags and variable options for CLI commands, see the Command Line Reference.

  • Run the GetWorkRequest operation with the returned work request OCID. If the operation fails, use ListWorkRequestErrors and ListWorkRequestLogs to review customer-visible details.

Step 4: Get the Active Instance Endpoints

After the create work request succeeds, confirm that the instance is active and obtain its API and user-interface endpoints. For more information, see instance details.

An ACTIVE lifecycle state doesn't rule out a subscription restriction. If lifecycleDetails reports a restriction, follow the subscription guidance before continuing.

    1. In the OCI Console, open the Navigation menu, select Oracle Public Safety and Security, and then under Public Safety and Security, select Instances.
    2. Select the compartment, and then select the Public Safety and Security instance.
    3. Verify that the lifecycle state is ACTIVE.
    4. Copy the Oracle Radio API service endpoint and the user-interface endpoint.
      Radio API service endpoint:
      https://<unique-id>.pss.<region>.oci.oraclecloud.com/api/
      Radio user-interface endpoint:
      https://<unique-id>.pss.<region>.oci.oraclecloud.com/ui/
      and uiEndpoint to open Oracle Radio.

  • Use the following command to get the instance lifecycle state, API service endpoint, and user-interface endpoint:

    oci pss instance get \
    --instance-id <instance-OCID>

    Continue only when the returned lifecycle state is ACTIVE.

    For a complete list of flags and variable options for CLI commands, see the Command Line Reference.

  • Run the GetInstance operation with the instance OCID. Continue only when lifecycleState is ACTIVE. Use the returned serviceEndpoint for API requests and uiEndpoint to open Oracle Radio.

Step 5: Sign In as the Initial Administrator

The Public Safety and Security instance must be active. Sign in with the same active Identity Domain user selected as the initial administrator when the instance was created.

  1. Open the Public Safety and Security instance uiEndpoint. 
    https://<unique-id>.pss.<region>.oci.oraclecloud.com/ui/
  2. If prompted, sign in to the OCI Identity Domain configured for Public Safety and Security.
  3. After the browser returns to Radio, verify the displayed identity.
  4. In Radio, verify that you can view Users and Groups.

The initial administrator can now enable Radio users and assign Radio-owned access. For more information, see sign-in guidance. If you need to see create another user or handoff the administrator user.

Step 6: Enable Oracle Radio Users and Assign Oracle Radio Groups

To enable users or change their Radio group memberships, you must have the Oracle Radio application permission radio.user.manage. The initial administrator automatically receives this permission through the initially seeded Radio Administrators group. This permission is separate from the OCI IAM permissions used to create or manage the Public Safety and Security instance.

  1. In the Radio App, select Users.
  2. Find an active Identity Domain user, select the check box next to the user you want to enable.
  3. Select Enable and confirm to create or enable the Radio authorization record. Or select Manage to review the Directory details that contains the user's Identity Domain details, Radio access status, and Radio user ID.
  4. Optionally, select the group check box to assign and save the user to a group.
  5. Repeat these steps for each user who needs Oracle Radio access.

The users have Radio access. Assigned Radio groups grant their Oracle Radio application permissions. To automate these changes with REST, follow user management.

Step 7: Prepare and Join Oracle Radio Channels

Have a Radio administrator prepare the channel and its access policy in the Radio app. Use the method tabs to choose how operators discover the channel and save a selection or connect to a live session. See the API comparison.

Administrators need the channel permissions for the setup action. Operators need the permissions for their chosen subscription or channel operation and the applicable channel access. Authenticate using the supported client flow.

    1. In Radio, select Channels.
    2. Create a channel if needed, enter a unique channel name and user-facing display name, and configure the approved channel properties.
    3. For a restricted channel, configure the access policy required by its users.
    4. Test the channel with an authorized user.
    5. In Radio, have each operator find the channel in the Channels rail and select Join.
    6. Verify that the joined channel appears in the Radio view.

    The instance is ready for approved Radio workflows, see channel management and channel use.

  • Start with an authenticated WebSocket session.

    1. Discover an accessible, existing channel with LIST_CHANNELS.
    2. Send SUBSCRIBE for the channel and verify the successful result.
    3. Inspect connected participants with LIST_CHANNEL_USERS.

    This establishes participation on the current connection. For the complete sequence, see joining channels.

    1. Find an accessible, existing channel with listChannels and inspect it with getChannel.
    2. For a persistent channel, save the user's selection with addSubscription.
    3. Verify the saved selection with getMySubscriptions.

    A REST saved subscription alone doesn't connect a live session. Use the WebSocket API tab for live participation. In the browser app, Join saves membership and starts listening; on connection, the browser also starts listening to saved joined channels. Check the channel's connection state before talking or messaging. See channel steps.

Step 8: Register an Oracle Radio Mobile Device

This quick start uses the default one-time grant. For repeated enrollment by the same intended user, see reusable registration.

Choose a method to create the one-time registration grant. The intended user then signs in through the supported mobile application to complete registration.

Creating a grant requires radio.enrollment.manage. The Radio app's Devices page also requires radio.device.manage. The intended user must be enabled in Radio. The seeded Radio Administrators group includes these permissions.

    1. In Radio, select Devices.
    2. Select Register device.
    3. For Intended user, select the enabled Radio user who will register the application.
    4. Enter a Display name for the application installation and a future Expires at date and time.
    5. Leave Reusable QR code cleared, then select Create QR code.
      The QR code supplies the public client configuration and one-time registration data. It doesn't contain the installed application's callback URI, a client secret, or OAuth tokens. Public Safety and Security manages the callback, grants, scope, and offline access.
    6. The radio user scans the QR code with the supported Oracle Radio mobile application and sign in to finish registration.
      The application supplies its opaque advertising ID when it completes registration. The QR code is short-lived and can be used only once. It doesn't authenticate the user or the device. After Identity Domain sign-in, the browser returns to the installed application through its supported callback.
    7. Select Done.

    Radio registers the application installation and assigns it a Radio device ID. The application uses the returned refresh token to renew access and sends a valid access token on each Radio REST request. For WebSocket, send the access token in AUTH when authenticating or renewing the session. For more information, see device registration.

  • Use the supported authentication flow.

    1. Find the intended enabled user with listDeviceRegistrationUsers. Use the returned Radio user ID.
    2. Call createDeviceRegistration with that ID, an installation display name, and a future expiration.
    3. Give the returned qrValue securely to the intended user for the supported mobile application.
    4. Have the intended user sign in and complete device registration. For a client implementation, follow the API quickstart.

    Creating a grant doesn't enroll the installation. The completion response supplies the Radio device ID used for subsequent device requests.