PTT Pro Okta Integration Guide

This document outlines the process for integrating Zebra's PTT Pro (Workcloud Communication) with Okta, leveraging OAuth2 and OpenID Connect (OIDC) for user authentication.

Introduction

Workcloud Communication supports OAuth2 authentication using the Okta identity provider. This enables multiple users to share a single device, known as the Shared Device Model. While Workcloud Communication solutions with AD/ADFS services support User Authentication, User Provisioning, and Attribute Transformations via LDAP, the Okta integration primarily focuses on User Authentication. User Provisioning and Attribute Transformations are supported indirectly through Workcloud Communication's Flat File Import functionality. The Okta integration utilizes the OpenID Connect (OIDC) protocol, which requires the Authentication Connection Service (ACS). ACS facilitates Workcloud Communication's authentication with Okta via OIDC. This guide details the Okta and ACS configuration necessary for user authentication and its impact on PTT Pro for Android and Workcloud Communication Profile Manager.

Requirements

• An Okta instance must be configured and running.
• PTT Pro for Android users must be provisioned in the Okta IdP.

Configuration Overview

The configuration process is divided into four sequential phases, where each phase relies on elements from the preceding one:

1. Phase 1: Establish the Realm and Client on the ACS server. This involves creating a realm and obtaining a client URL for Okta configuration.
2. Phase 2: Create the Application in the Okta server. This phase involves generating Authentication and Token Access URLs, along with the Client ID and Client Secret, which are essential for establishing the Identity Provider connection in ACS.
3. Phase 3: Create the Identity Provider and finalize the ACS configuration.
4. Phase 4: Configure the PTT Pro Server OAuth connection using the necessary URLs and certificates to link with the ACS.

Phase 1 – Configuring the ACS

This phase involves creating the realm, retrieving the signing certificate, configuring the client, and setting up the user property mapper.

Creating the Realm

Create a realm with a descriptive name. The example uses WFC-OKTA-Connector.

Visual Description: A screenshot shows the ACS interface for adding a realm, with fields for 'Name' and 'Enabled' status, and a 'Create' button.

Steps:

1. Select 'Add realm' from the 'Select realm' menu.
2. Enter the desired name for the new realm in the 'Name' text box.
3. Click 'Create'.

Upon creation, the realm is enabled, and the OpenID endpoint is established.

Retrieving the Signing Certification of the Realm

The signing certificate is crucial for configuring the PTT Pro Server.

Steps:

1. Navigate to Realm Settings > Keys.
2. Copy the RS256, RSA signing certificate to a local file on your computer. This certificate will be used for PTT Pro Server configuration. Note: Two RSA keys exist: one for encoding (ENC) and one for signing (SIG). The PTT Pro Server uses the signing certificate.
3. Save the certificate in the X.509 format.

Visual Description: A screenshot displays the ACS 'Keys' tab, showing different algorithms (AES, RSA) and their types (ENC, SIG). Another screenshot shows the sample signing certificate content.

The realm is now established.

Creating the Client

Create a client to enable PTT Pro for Android users to authenticate with Okta.

Steps:

1. Select 'Clients' to view the list of default clients.
2. Click 'Create'.
3. Enter a name for the client in the 'Client ID' text box. The example uses oidc.client.
4. Verify that the 'Client Protocol' is set to openid-connect.
5. Click 'Save' to configure the client.

Visual Description: Screenshots show the ACS 'Clients' list and the 'Add Client' dialog with fields for 'Client ID', 'Client Protocol', and 'Root URL'.

Configuring the Client

Complete the client configuration to ensure integration with PTT Pro for Android.

Steps:

1. Click 'Clients' under the 'Configure' menu.
2. Select the client (e.g., oidc.client).
3. Verify the following settings in the 'Settings' tab:
   • Client Protocol: openid-connect
   • Access Type: confidential (Note: 'public' works but without a client secret; 'bearer-only' does not work).
   • Standard Flow Enabled: ON (If OFF, PTT Pro for Android shows a blank screen without prompting for credentials).
   • Direct Access Grants Enabled: ON (If OFF, PTT Pro for Android shows a login screen followed by a blank screen, failing the connection).
   • Valid Redirect URIs: Enter https://localhost. An incorrect URI will cause an error on the device and prevent the login screen from displaying.
4. Click 'Save'.

Visual Description: A screenshot shows the 'oidc.client' settings page in ACS, highlighting the 'Settings' tab with various configuration options.

Copying the Client Secret

The client secret is required for PTT Pro for Android configuration. Copy both the secret and the Client ID.

Steps:

1. Click the 'Credentials' tab to access the client secret.
2. Copy the client secret, which is automatically generated.
3. Save the client secret and the client ID (e.g., oidc.client) in a secure location.

Visual Description: A screenshot shows the 'Credentials' tab for the 'oidc.client', displaying the 'Client ID' and 'Secret' fields.

Example Client Secret: 31941cec-9b16-46b8-8749-2e6c3fa4ff23

Creating a User Property Mapper

This maps the token claim 'sub' to the username attribute used by PTT Pro for Android. Failure to complete this step results in a blank screen after credential entry.

Steps:

1. Click the 'Mappers' tab in the client definition.
2. Click 'Create' to define a mapping:
   • Name: username
   • Mapper Type: Select User Property
   • Property: username
   • Token Claim Name: sub
   • Claim JSON Type: Select String
3. Click 'Save' to return to the client definition screen.

Visual Description: Screenshots show the ACS 'Mappers' tab and the 'Create Protocol Mappers' dialog.

Copying the Identity Provider Redirect URI

The Redirect URI from ACS is needed to complete the Okta configuration. The ACS IdP requires this information from the Okta application setup.

Steps:

1. Select 'Identity Providers' from the client configuration.
2. Select 'Open ID Connect 1.0' from the menu to display the redirect URI.
3. Copy the redirect URI from the 'Redirect URI' field.

Visual Description: Screenshots show the ACS 'Identity Providers' interface and the 'Add identity provider' dialog, highlighting the 'Redirect URI' field.

Example Redirect URI: https://<ACS-server-name>/auth/realms/WFC-Okta-Connector/broker/okta.oidc.connector/endpoint

Phase 2 – Configuring Okta

This phase involves adding and configuring a new Workcloud Communication native application using elements from ACS. Ensure users are already provisioned in Okta.

Creating an App

Use Okta to create a new native application for PTT Pro for Android.

Steps:

1. Open Okta and navigate to Applications > Applications, then click 'Create App Integration'.
2. Select OIDC - OpenID Connect as the Sign-in method.
3. Select Native Application as the Application type.
4. Click 'Next'.

Visual Description: Screenshots show the Okta dashboard, the 'Applications' page, and the 'Create a new app integration' dialog, guiding the user through selecting OIDC and Native Application types.

Configuring the New Native App

Configure the app with the provided settings, including naming the app and adding the previously created redirect URI.

Steps:

1. Enter a name in the 'App integration name' field (e.g., Native PTT-Pro App).
2. Optionally, add an application logo.
3. Select the 'Grant type'. 'Authorization Code' is selected by default. 'Refresh Token' can be set for persistent refresh. Additional types can be selected as needed.
4. Modify the 'Sign-in redirect URIs':
   • Delete the default redirect URI.
   • Enter the Redirect URI obtained from the OIDC Identity Provider (refer to 'Copying the Identity Provider Redirect URI' on page 11).
   • Click 'Add URI' and enter https://localhost.
5. Do not modify the 'Sign-out redirect URIs'.
6. Under 'Assignments', configure user access:
   • Set 'Controlled Access' to 'Allow everyone in your organization to access'.
   • Choose whether to grant immediate access with 'Federation Broker Mode'. When enabled, all users can access the application. When disabled, selective access and custom claims are required.
7. Click 'Save' to preserve the 'General Settings'.

Visual Description: Screenshots illustrate the Okta 'New Native App Integration' settings, including fields for app name, grant type, redirect URIs, and assignments.

Configuring Access to the Native App

If Federation Broker is not used for granting access, follow these steps to determine who can access the app.

Steps:

1. Open the application and select the 'Assignments' tab.
2. Select the appropriate access for your environment (e.g., make the PTT-Pro App available to the 'Everyone' group).

Visual Description: A screenshot shows the 'Assignments' tab within the Okta application configuration, demonstrating how to assign access to groups.

Completing the Native App Configuration

Finalize the app configuration to complete the ACS Identity Provider setup.

Steps:

1. Open the application and navigate to the 'General' tab.
2. Click 'Edit'.
3. Copy the 'Client ID' from the 'Client Credentials' field. Example: 0oa5km1v306LXN57y5d7.
4. Under 'CLIENT SECRETS', reveal and copy the 'Secret' to your computer. Example: QUndeR7dkcARwPFjVyGVh6NeFjzbs00Md2xWYFLS.
5. Click the 'Sign On' tab to edit the 'OpenID Connect ID Token' screen.
6. Select the Okta URL from the 'Issuer' menu.
7. Verify that 'Audience' is populated with the Client ID.
8. Select 'Filter' for the 'Group claims type'.
9. Enter the 'Group Claims Filter' (e.g., .*).
10. Click 'Save'.

Visual Description: Screenshots show the Okta 'Native PTT-Pro App' general settings, client credentials, and the 'Sign On' tab for token configuration.

Phase 3 – Completing the ACS Configuration

With the application configured in Okta (Client ID and Client Secret obtained), this section details completing the Identity Provider configuration in ACS using Okta information.

Creating A Simple Login Authentication Flow

This flow allows the mobile client to pass credentials seamlessly through ACS to the Okta IdP, improving the user sign-in experience.

Steps:

1. Select Authentication > Flows > New.
2. Enter an 'Alias' (e.g., Simple Login Flow) and select generic from the 'Top Level Flow Type' menu.
3. Click 'Save' to create the flow.
4. In the 'Authentication' view, select the new flow and click 'Add Execution'.
5. From the 'Provider' menu, select 'Create User If Unique'.
6. Click 'Save'.
7. In the 'Authentication' view, select 'Alternative' to activate the flow.

Visual Description: Screenshots illustrate the ACS 'Authentication' view, the 'Create Top Level Form' dialog, and the process of adding an execution for 'Create User If Unique'.

Creating the Identity Provider

Create the identity provider in ACS using information from Okta.

Steps:

1. Select 'Identity Providers' from the ACS interface.
2. Select 'Open ID Connect 1.0' from the menu.
3. Configure the Identity Provider:
   • Alias: okta.oidc.connector (example)
   • Enabled: Set to ON.
   • (Optional) Set 'Store Tokens' and 'Store Tokens Readable' to ON.
   • Select 'Simple Login Flow' from the 'First Login Flow' menu.

The 'Redirect URI' displayed in the 'Redirect URI' field is used as the Okta Redirect for the native app. Example: https://<acs-server-name>/auth/realms/WFC-Okta-Connector/broker/okta.oidc.connector/endpoint

Visual Description: Screenshots show the ACS 'Identity Providers' interface and the 'Add identity provider' dialog with configuration fields.

Collecting Information from the Well-Known URL

To complete the Identity Provider configuration, gather additional details from the well-known URL. This includes the Authentication URL, Token URL, Client Authentication, Client ID, Client Secret, and Client Assertion Signature Algorithm.

Access the well-known URL using the Okta domain and client ID. The structure is: https://<domain>/.well-known/openid-configuration?client_id=<client-id>.

Example well-known URL: https://dev-84941762.okta.com/.well-known/openid-configuration?client_id=0oa5km1v306LXN57y5d7

The JSON response from this URL provides necessary information like the Authorization endpoint and Token endpoint.

Visual Description: A screenshot shows the Okta 'Applications' page with the 'Native App PTT-Pro' and its 'Client ID'. The JSON response structure is also detailed.

Completing the Identity Provider Configuration

Use the information from the well-known URL's JSON response to finalize the Identity Provider configuration.

Steps:

1. Open the Identity Provider and complete the configuration.
2. Use the example configuration data:
   • Authorization URL: https://dev-84941762.okta.com/oauth2/v1/authorize
   • Token URL: https://dev-84941762.okta.com/oauth2/v1/token
   • Client Authentication: Set to Client secret as jwt. Other options like 'Post' or 'basic auth' may work, but 'JWT Signed with Private Key' will fail.
   • Client ID: 0oa5km1v306LXN57y5d7 (assigned by Okta).
   • Client Secret: QUndeR7dkcARwPFjVyGVh6NeFjzbs00Md2xWYFLS (assigned by Okta).
   • Client Assertion Signature Algorithm: HS256 (or HS384, HS512).
   • Default Scopes: Enter openid offline_access profile. Other combinations may lead to errors or blank screens.
   • Prompt: Enter login.
3. Click 'Save'.

Visual Description: A screenshot shows the ACS 'OpenID Connect Config' dialog with fields for Authorization URL, Token URL, Client ID, Client Secret, etc.

Setting the Login Browser Flow

After configuring the Identity Provider, set the 'Identity Provider Redirector' to enable the Okta login screen. If this is not done, the ACS login screen will appear.

Steps:

1. Select 'Authentication' and click the 'Flows' tab.
2. Click the 'Actions' menu for the 'Identity Provider Redirector' and select 'Configuration'.
3. Configure the oidc.connector:
   • Alias: oidc.connector (example).
   • Default Identity Provider: okta.oidc.connector (example).
4. Click 'Save'.

Visual Description: Screenshots show the ACS 'Authentication' view and the configuration dialog for the 'oidc.connector'.

Validate the Configuration

Validate the configuration before testing on a mobile device using Postman and the jwt.io token validator.

Validating with Postman

Testing with Postman confirms the accuracy of collected information.

Create a Postman profile with the following parameters:

• Auth URL
• Access Token URL
• Client ID
• Client Secret
• Scope: openid profile offline_access (The 'profile' scope is used for refresh tokens).

Steps:

1. Insert the URLs into the Postman profile along with the Client ID and Client Secret. These URLs can be found by entering the well-known URL into a browser. Example URLs:
   • Authorization endpoint URL: https://<acs-server-name>/auth/realms/WFC-Okta-Connector/protocol/openid-connect/auth
   • Access Token URL: https://<acs-server-name>/auth/realms/WFC-Okta-Connector/protocol/openid-connect/token
2. Click 'Get New Access Token'. A successful test displays the Okta login screen from ACS.
3. Enter user credentials.
4. Analyze the access token using https://jwt.io/.
5. Review the decoded payload to verify user identification (e.g., the 'sub' claim is the UserID).

Visual Description: Screenshots show the Postman 'Configure New Token' dialog, the 'Connecting to' screen, and the jwt.io token analysis interface.

Configuring the Workcloud Communication System

After validating Okta and ACS configurations, configure the PTT Pro Server. Mobile devices connect to the PTT Pro Server, which then uses the URLs to connect to the ACS server, redirecting the user to Okta.

The PTT Pro Server requires three configuration parameters:

• Access URL
• Token URL
• Signing certificate

Steps:

1. Log in to the Workcloud Communication PTT Pro Management Portal and navigate to Customer > Profile to configure OAuth.
2. Enter the Access URL and Authorization Endpoint URL (OAuth URL) in the 'Configure OAuth' dialog. These are the same URLs used in Postman validation.
3. Enter the OAuth Token Certificate, copied previously from 'Retrieving the Signing Certification of the Realm'. Ensure it is formatted correctly with -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
4. Enter the device serial number in the PTT Pro Server and create OAuth user accounts with an accurate OAuth name.
5. Add the JSON configuration to the mobile devices for PTT Pro client connection to the ACS server:

   {
     "oAuthClientID" : "oidc.client",
     "oAuthClientSecret" : "31941cec-9b16-46b8-8749-2e6c3fa4ff23",
     "oAuthBasicHeader" : true
   }

6. Use a mobile device to verify the configuration. The Okta sign-on screen should display. If a blank screen appears after credential entry, check for certificate issues or incorrect Authorization/Access URLs.

Visual Description: Screenshots show the 'Configure OAuth' dialog, the 'Modify User' dialog in PTT Pro Server, and the Okta sign-on screen on a mobile device.

Revision History