Migrating to the Client Credentials (OCIM) Authentication Scheme

Follow the below steps only for environments that are migrating from a resource owner group (Shared Security Domain - SSD) authentication scheme to a client credentials authentication scheme (OPERA Cloud Identity Management - OCIM).

What is OCIM and why is Oracle moving to it?

OCIM is a cloud-ready identity and access management service for OPERA Cloud. OCIM replaces SSD as the core identity and access management engine for OPERA Cloud, thereby, increasing security and making managing integrations easier. In OCIM, each chain belongs to an enterprise with an enterpriseId.

Migration Notification and Brief Downtime

Oracle will notify customers and their integration partners well in advance of migration dates. This ensures all stakeholders can adequately prepare for the migration.

Overview

Oracle is migrating one OPERA Cloud environment at a time to OCIM.

Customers and partners who call APIs through the Oracle Hospitality Integration Platform (OHIP) authenticate using an OAuth token. In SSD, this relies on an integration user’s username and password; this is called the “resource owner” flow. In OCIM, this relies on a ClientId and ClientSecret; this is called the “client credentials” flow. This change enhances security and manageability of your integrations.

This chapter details the steps for customers and partners throughout the migration, outlining operational changes before, during, and after migration. It also covers important considerations related to integration user management and post-migration validation.

Migration Phases

Migration Phase	Customers
Before Migration	Use SSD authentication. Developer Portal URL: SSD URL All internal integrations use a single ClientId per environment and separate integration users. No action required.
During Migration	Developer Portal URL: SSD URL Use the OPERA Cloud Role Manager to reissue passwords to integration users. No new partner integrations can be added. Customers with internal integrations: Reissue ClientId for each chain. Use either resource owner or client credentials to connect. Must switch to OCIM Client Credentials Authentication before migration completes. All internal integrations use the one (reissued) ClientId per environment. To reissue passwords for integration users, use OPERA Cloud Role Manager (see above).
After Migration	New Developer Portal URL: OCIM URL Integration users are no longer required. Customers with internal integrations: Use only OCIM client credentials. Integration users are automatically converted to OCIM clients. Either use a new OCIM client and provide its credentials to the relevant internal integration team, so they can update their integration to use the new (separate) OCIM client or create a new named OCIM client for each internal integration team. Integration users are no longer required. Use developer portal analytics to validate that integrations are not resulting in errors.

Migration Phase

Customers

Before Migration

Use SSD authentication.

Developer Portal URL: SSD URL

All internal integrations use a single ClientId per environment and separate integration users.

No action required.

During Migration

Developer Portal URL: SSD URL

Use the OPERA Cloud Role Manager to reissue passwords to integration users.

No new partner integrations can be added.

Customers with internal integrations:

Reissue ClientId for each chain.
Use either resource owner or client credentials to connect.
Must switch to OCIM Client Credentials Authentication before migration completes.
All internal integrations use the one (reissued) ClientId per environment.
To reissue passwords for integration users, use OPERA Cloud Role Manager (see above).

After Migration

New Developer Portal URL: OCIM URL

Integration users are no longer required.

Customers with internal integrations:

Use only OCIM client credentials.
Integration users are automatically converted to OCIM clients.
Either use a new OCIM client and provide its credentials to the relevant internal integration team, so they can update their integration to use the new (separate) OCIM client or create a new named OCIM client for each internal integration team.
Integration users are no longer required.
Use developer portal analytics to validate that integrations are not resulting in errors.

Switching from Resource Owner to Client Credentials Authentication

The image below shows the key differences between the resource owner group (SSD) authentication flow and the new OCIM client credentials flow as well as the steps to update your integration.

Code that calls the OAuth API must be changed (as shown below) to work with OCIM authentication.

Note that the scope value is always the following:

urn:opc:hgbu:ws:__myscopes__

This image shows the changes you must make in the OAuth token API.

Special Considerations During Migration

Advance Notification: Customers and partners are notified well in advance by Oracle. This includes advice about the enterpriseId to which the chain belongs.
New Partner Integrations: New partner integrations cannot be initiated with chains that are in the process of migrating. They must wait until the migration has completed.
Integration User Management:
- Customers: If an integration user’s password must be changed during migration, customers can manage integration users using OPERA Cloud Role Manager. Refer to Managing Interface Users in the OPERA Cloud Identity Management Administrator Guide.
- Partners: Cannot create or change integration users during the migration using SSD. If you need to change a user’s password or create a new user, you must switch to OCIM authentication and reissue the ClientSecret. While a partner may have had more than one integration user in SSD, only one ClientId is permitted per chain for each partner in OCIM.

For Customers

Before Migration

Access the Developer Portal using the SSD URL.
If you have internal integrations:
- Each environment (typically one per login) displays a single client ID used by all your internal integrations.
- Authentication uses the resource owner group (SSD) method. This involves sending an integration user’s username and password as well as the client ID and Client Secret as described in Authenticating to Oracle Hospitality Property APIs (SSD).
- No action is required at this stage.

During Migration

Continue to use the SSD URL for Developer Portal access.

Customers with internal integrations:

For each chain being migrated:

Log in to the Developer Portal.
Go to the Environments tab.
Click View Details on your environment.
Use Reissue Client ID to convert your client to OCIM and receive new OCIM client credentials (ClientId and ClientSecret). Integrations that are using the resource owner group (SSD) authentication will continue to work as before.
Update all your internal integrations to use the new OCIM client credentials for authentication.

It is still possible to use the resource owner group (SSD) authentication method to obtain OAuth tokens during this period. However, all integrations must switch to client credentials (OCIM) authentication before the migration has completed.

Integration User Management:

Customers can add or change integration users and passwords using OPERA Cloud Role Manager. See Managing Interface Users for more information.

New Partner Integrations:

It is not possible for new partners to begin new integrations with chains that are migrating.

After OCIM Migration

Begin using the OCIM URL to access the Developer Portal. This is available from the link in OPERA Cloud and will be communicated by Oracle. This URL is in the following format:

For production OPERA environments: https://<ohip-domain>/<enterpriseID>prd/ui
For non-production OPERA environments: https://<ohip-domain>/<enterpriseID>uat/ui

Integration users are no longer required or supported. Authentication and access control is now exclusively managed using OCIM client credentials.

ClientIds now appear in OPERA Audit Logs and not in the integration usernames.

Customers with internal integrations:

Any integration users previously created for internal integrations are now converted to separate OCIM clients. View these by logging in to the developer portal for a given chain and selecting View Details on the environment card. These are named with globally universal identifiers (GUIDs).
Alternatively, create new OCIM clients by logging in to the developer portal for a given chain and selecting View Details on the environment card. You can choose part of the name of the OCIM clients you create.
Update each internal integration to use its own (separate) ClientId instead of a shared ClientId.

Validation Required:

Use the developer portal Analytics tab to check that integrations are not producing errors.
Confirm all applications and integrations function as expected post-migration.
Report any issues to Oracle Support – see Opening a Support Request.

Property-level authorization:

If desired, restrict partner integrations to specific properties by Managing Partner Connections.
If desired, restrict internal integrations to specific properties by Managing Client Applications.

For Partners

Before Migration

Authentication uses the resource owner group (SSD) method.
No action is required at this stage.

During Migration

For each chain that is migrating:

Log in to the Developer Portal. The partner Developer Portal URL does not change.
Select the environment for the chain being migrated. It will show a 'Migrating Soon' label.
Use Reissue Client ID to convert the client to an OCIM ClientId. This generates new OCIM client credentials.
Update your integration(s) to use OCIM client credentials authentication.

Authentication Method:

It is still possible to use the resource owner group (SSD) authentication method to obtain OAuth tokens during this period.
All integrations must be updated to use client credentials (OCIM) authentication prior to completion of the migration.

Integration User Management:

It is not possible to access the SSD user interface during the migration.
If a password change is required during migration, you must do the following:
- Reissue your ClientSecret.
- Change your integration to use OCIM client credentials authentication.
Note:
Even if you have multiple integration users per chain, it is only possible to have one ClientId per chain and OPERA environment in the new OCIM authentication model.

New Partner Integrations:

Partners cannot initiate integrations with chains that are migrating until migration has completed.

After OCIM Migration

You will have one OCIM client per chain and OPERA environment, and integration users are no longer required or supported.
Authentication is exclusively managed through OCIM client credentials.
Ensure all integrations are updated to use the OCIM client credentials authentication.

Validation Required:

Log in to the Developer Portal, select the Environments tab, and select View Details on environments recently migrated to check whether the customer has limited your access to specific properties. If your access is now restricted to specific properties, verify that restriction with the customer.
Select the developer portal’s Analytics tab to check that integrations are not producing errors.
Verify all your applications and integrations are functioning correctly post-migration, and you can obtain OAuth tokens and call APIs.
Contact Oracle Support promptly if issues are detected. For more information, see Opening a Support Request.

To initiate an integration with a chain that has migrated to OCIM, follow this process: Adding an Environment.

After Migration: Discontinuation of Integration Users

After migration to OCIM authentication, integration users are no longer needed. All authentication and access management are handled by OCIM client credentials providing enhanced security and eliminating the need for individual integration user accounts.

Table 8-1 Troubleshooting Client Credentials Authentication

API Called	HTTP Response Code	Response Body	Troubleshooting Steps
OAuth	403	invalid_grant_type_or_scope	Ensure you include the “scope” attribute in the body with the value “urn:opc:hgbu:ws:__myscopes__”.
OAuth	401	Enterprise id is required	Ensure you include the “enterpriseId” header.
OAuth	403	Enterprise does not have access to gateway	Ensure you have entered the correct enterpriseId and the correct gateway URL. These can be checked on the developer portal Environments tab.
OAuth	401	Failed to authenticate application	Ensure the applicationId is correct and you are using the correct authentication scheme for the environment (which can be seen on the Developer Portal’s Environments tab). Also, ensure the credentials are correct.

See Common Error Messages for more information.

Terms

ClientId

A ClientId is a unique identifier issued by OPERA Cloud Identity Management system (OCIM) for a client application or integration accessing OHIP APIs. In the client credentials model, each integration or application uses its assigned ClientId (along with a secret) to authenticate and obtain access tokens for API calls.

Enterprise Id

In OCIM, each chain is part of an enterprise. Each enterprise has a globally unique identifier called the Enterprise ID. Enterprise IDs are never shared across multiple customers and are a key identifier for routing authentication and authorization requests. It is never the same as any chain code or property code within that enterprise. Refer to Enterprise IDs in the OCIM documentation for the format of Enterprise IDs.

Integration User

An integration user is a user account set up specifically to enable integrations between external systems and OHIP APIs. They are created directly in the Shared Security Domain (SSD). Integration users (along with passwords) are used in the resource owner group (SSD) authentication model. After the migration to OCIM, integration users are no longer needed or supported as authentication is handled through OCIM client credentials.

Authentication Method

An authentication method is the process or protocol used to verify the identity of a client or user for API access. In OHIP, authentication methods include the resource owner group (SSD) flow—where username, password, and ClientId are provided—and the new OCIM client credentials flow — where only ClientId and client secret are required to obtain an OAuth token.

OAuth token

An OAuth token is a secure, time-limited credential issued by the OCIM or SSD authentication systems. After a valid authentication request, the token is provided and must be included in the authorization header (Bearer <token>) of subsequent OHIP API calls to prove identity and access rights.

Customer Internal Integration

A customer internal integration refers to interfaces or applications built and managed by the customer for their own internal business needs. These integrations are distinct from partner or external integrations, and after full OCIM migration, each typically receives its own OCIM client credentials.

Streaming API

The Streaming API permits real-time, continuous delivery of Business Events (such as event or reservation updates) from OHIP to subscribed applications or integrations. See Streaming API (push) for more information.

8 Migrating to the Client Credentials (OCIM) Authentication Scheme