Oracle Fusion Cloud EPM

Customer-facing setup instructions: what an Oracle Fusion Cloud EPM administrator must configure in their environment, and which values to enter into Clarity.

Overview

The Clarity Oracle Fusion Cloud EPM connector talks to the EPM Cloud Security REST API at {your EPM instance URL}/interop/rest/security. It reads your EPM users, groups, and roles for access review, and can provision role and group membership.

Why the Role Assignment Report matters. Some EPM role grants originate in the identity layer rather than the application layer, and those are not visible through the user or group listings. Clarity therefore reads role assignments from the Role Assignment Report, which joins both layers — that is the only way to see a user’s complete role picture.

Last login. Clarity requests the User Login Report for the trailing 119 days and records each user’s most recent access as their last login. Oracle retains this audit data for a maximum of 120 days, so 119 is the widest window that reliably returns data. A user who has not signed in within that window has a blank last login in Clarity — blank means “no login in the last 119 days”, not “never logged in”.

Clarity supports two authentication methods. Neither has a browser consent screen or redirect URL inside Clarity.

Prefer OAuth wherever your environment supports it — Clarity never stores the service account’s password, and the interactive device-code sign-in satisfies any MFA policy on your identity domain.

Choose your authentication method

Is my environment OCI (Gen 2) or Classic?

Oracle supports OAuth 2.0 for the EPM REST API only on OCI (Gen 2) environments. Classic environments must use Basic authentication — skip Steps 3–5 and fill in only the Basic Auth fields in Step 6.

A quick indicator is the environment URL: OCI (Gen 2) URLs contain .ocs.oraclecloud.com (for example https://mycompany.epm.us6.ocs.oraclecloud.com), whereas Classic URLs do not (for example https://epm-exampleDomain.epm.us6.oraclecloud.com). OCI (Gen 2) environments are also listed under Oracle Cloud Services in the identity domain in the OCI Console. (If you are unsure, confirm the environment generation with your Oracle account team before starting the OAuth steps.)

Which method Clarity uses

Clarity decides from the fields you fill in — there is no method selector:

1. All three required OAuth fields present — Identity Domain URL (OAuth), OAuth Client ID and OAuth Refresh Token → Clarity uses OAuth 2.0, even if a username and password are also saved.

2. Otherwise, username and password both present → Clarity uses HTTP Basic. If some but not all OAuth fields are filled in, Clarity falls back to Basic and logs a warning naming the missing OAuth fields.

3. Otherwise → Test credentials (and every sync) fails with an error that names the missing fields.

Prerequisites

• An Oracle Fusion Cloud EPM environment (Planning, Financial Consolidation and Close, Tax Reporting, Narrative Reporting, Account Reconciliation, and so on) — the Security REST API is common to all of them.

• Someone with Identity Domain Administrator access in the OCI Console (to create the service account, assign its application role and — for OAuth — register the OAuth application), or an existing Service Administrator who can do the role assignment.

• A service account that will be dedicated to Clarity, holding the Service Administrator predefined role. With OAuth, this is the user who signs in during the device-code step, and Clarity’s API calls run as that user.

• For Basic authentication: the service account must be able to authenticate with a password over REST — i.e. not subject to an MFA or password-less policy for API access.

• For OAuth 2.0: your identity domain must allow the Mobile Application client type and the Device code and Refresh token grant types. Some hardened identity domains disable these; if yours does, OAuth is not available and you must use Basic authentication (or have the policy relaxed).

• For OAuth 2.0: a machine with curl and a web browser for the one-time device-code sign-in (Step 5). This must be completed within five minutes once started.

Step 1 — Identify your EPM instance URL

Clarity needs the base URL of the EPM environment, and nothing after the hostname. Clarity appends /interop/rest/security itself.

The format is:

https://<tenant>.epm.<dc>.ocs.oraclecloud.com

for example https://mycompany.epm.us6.ocs.oraclecloud.com. Older or differently-provisioned environments may present as https://epm-<identitydomain>.epm.<dc>.oraclecloud.com — either is fine for Clarity, though a URL without .ocs. usually means a Classic environment (Basic authentication only — see Choose your authentication method).

The reliable way to get it: sign in to your EPM business process and copy the scheme + host from the browser address bar. Then:

• Keep https://.

• Remove everything after the hostname — no /epmcloud, no /HyperionPlanning, no trailing /, and never /interop/rest/security.

Your identity domain name is visible in that same host. For https://epm-exampleDomain.epm.us6.oraclecloud.com the identity domain is exampleDomain (the text between the first - and the next .); for a test environment https://epm-test-exampleDomain.epm.us6.oraclecloud.com it is the text between test- and the next .. You may need it in Step 2.

Step 2 — Create the integration service account and grant Service Administrator

Create a dedicated account for Clarity rather than reusing a person’s login — a named individual’s account will break the integration when they leave, rotate their password, or (with Basic auth) get MFA enrolled.

Why Service Administrator. Every endpoint Clarity uses lives under the Security REST API, and Oracle gates that surface on the Service Administrator role (or, for some read-only report calls, an application role plus the Access Control — Manage / View granular roles). Both the Role Assignment Report and the User Login Report name Service Administrator as a sufficient role; the provisioning calls (add user, remove user, assign/unassign role, add/remove group members) require it outright. A Power User, User, or Viewer account will authenticate and then fail on the very first sync call.

1. Create the user in the identity domain. In the OCI Console, go to Identity & Security → Domains, open the identity domain backing your EPM environment, and create a user with a working email address. (Exact clicks in the OCI Console vary by tenancy layout and Oracle revises this console — confirm against your own tenant.)

2. Assign the Service Administrator application role. In the IAM interface:

   • Click the Oracle Cloud Services tab — your EPM and EDM environments are listed.

   • Click the name of the EPM environment you are connecting to Clarity.

   • Click the Application roles tab.

   • Click the ellipsis next to Service Administrator and choose Manage users.

   • On Manage user assignments, click Assign users, search for your service account, select it, and click Assign. It should then be listed with member type Direct.

3. Complete first sign-in (Basic). Sign in to the EPM environment once as the service account and clear any forced password change or welcome prompt. An account still in “must change password” state will fail Basic auth.

4. Note the username form (Basic). Basic authentication accepts either username or identitydomain.username (e.g. exampleDomain.clarity.svc). Plain username works on most environments; if authentication fails with a 401, retry with the identity-domain-prefixed form using the identity domain from Step 1.

You can review who holds which application role from the EPM business process itself: from the Home page click Tools, then Access Control, which opens on Manage Groups and also provides the role and audit reports. (Access Control shows role assignments; creating users and granting predefined roles is done in the OCI Console / IAM interface as above.)

Step 3 — (OAuth only) Register a Mobile Application in the identity domain

Skip Steps 3–5 if you are using Basic authentication.

Oracle’s documented OAuth flow for EPM uses a Mobile Application — a public client with no client secret. In the OCI Console:

1. Go to Identity & Security → Domains and select the identity domain where your EPM environment is deployed.

2. Note the Domain URL on the domain’s overview — it has the form https://idcs-<id>.identity.oraclecloud.com. This is Clarity’s Identity Domain URL (OAuth) field.

3. Open the Integrated applications tab, click Add application, choose Mobile Application and click Launch workflow.

4. Enter a name (for example Clarity EPM connector) and description, leave the remaining fields at their defaults and click Submit.

5. Open the OAuth configuration tab and click Edit OAuth configuration. Under Client configuration → Authorization → Allowed grant types:

   • Select Refresh token.

   • Select Device code.

   • Make sure Implicit is not selected.

6. Token issuance policy — resources and scope. Enable Add resources, click Add scope, select the EPM environment you are connecting to Clarity and click Add. Note the scope shown for that resource; it has the form:

• urn:opc:serviceInstanceID=<SERVICE_INSTANCE_ID>urn:opc:resource:consumer::all

• You need it in Step 5. Select one EPM environment per Clarity application — see the note below.

1. Token issuance policy — app roles. Enable Add app roles, click Add roles, choose Identity Domain Administrator and click Add.

• Why this role: this step is part of Oracle’s own documented EPM OAuth registration procedure (Authentication with OAuth 2 — Only for OCI (Gen 2), Token Issuance Policy), so Clarity follows it as written. Oracle does not state a reason, and Clarity itself never calls the identity domain’s admin APIs — it only exchanges the refresh token at /oauth2/v1/token and calls the EPM REST API as the signed-in service account. Be aware that the role is granted to the application, not to the service account. If your security policy forbids it, you can try omitting it and confirm with Test Connection after Step 6; if the token exchange or EPM calls then fail, add it back.

1. Click Submit, then Actions → Activate → Activate application.

2. Note the Client ID under General Information. This is Clarity’s OAuth Client ID field.

One refresh token per EPM environment. Oracle binds each token to a single EPM environment and does not support scopes spanning several environments. If you connect more than one EPM environment (for example Planning and Financial Consolidation and Close), create a separate Clarity application for each, and run the device-code sign-in (Step 5) separately for each one with that environment’s scope. The same Mobile Application and Client ID can be reused across them.

Confidential application (optional). Oracle’s EPM guide documents only the public Mobile Application path above, and that is what Clarity expects by default. If your security policy requires a confidential application with a client secret instead, enter the secret in OAuth Client Secret (optional); Clarity then authenticates the client with HTTP Basic (client ID + secret) on each token call. Leave that field blank for a Mobile Application.

Step 4 — (OAuth only) Enable token refresh on the EPM service

Complete this for each EPM environment you selected in Step 3:

1. In the same identity domain, open the EPM Cloud service (under Oracle Cloud Services) that you added as a resource in Step 3.

2. Open its OAuth configuration tab and click Edit OAuth configuration.

3. Enable Add secondary audience and add the environment’s base URL — the URL you use to reach EPM with the trailing context path removed. For example, if you reach EPM at https://mycompany.epm.us6.ocs.oraclecloud.com/epmcloud, the secondary audience is https://mycompany.epm.us6.ocs.oraclecloud.com (the same value as Clarity’s EPM Instance URL).

4. Enable Allow token refresh.

5. Recommended: on this same OAuth configuration page, extend the refresh-token lifetime beyond Oracle’s 7-day default. Clarity keeps the token alive through its hourly connection health check (see How Clarity keeps the OAuth token alive below), so a longer lifetime only widens the safety margin for outages; Oracle advises caution when extending token expiry, so choose a value your security team accepts.

6. Save the changes.

Step 5 — (OAuth only) Obtain the refresh token with the device-code sign-in

Clarity cannot run this step for you: Oracle requires an interactive sign-in by the user the API calls will run as. You run two curl requests and one browser sign-in, then paste the resulting refresh token into Clarity once. See Oracle’s Authentication with OAuth 2 for OCI (Gen 2) environments for Windows PowerShell / Command Prompt variants.

In the commands below, replace:

• <IDENTITY_DOMAIN_URL> — the Domain URL from Step 3.2 (e.g. https://idcs-<id>.identity.oraclecloud.com).

• <CLIENT_ID> — the Client ID from Step 3.9.

• <SERVICE_INSTANCE_ID> — from the scope you noted in Step 3.6.

5.1 — Device authorization request. Note the trailing offline_access in the scope — it is what makes Oracle issue a refresh token.

curl --location --request POST '<IDENTITY_DOMAIN_URL>/oauth2/v1/device' \
--header 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
--data-urlencode 'response_type=device_code' \
--data-urlencode 'scope=urn:opc:serviceInstanceID=<SERVICE_INSTANCE_ID>urn:opc:resource:consumer::all offline_access' \
--data-urlencode 'client_id=<CLIENT_ID>'

The response contains a device_code, a user_code and a verification_uri. Both codes expire in 300 seconds (5 minutes) — complete 5.2 and 5.3 within that window, or start again from 5.1.

5.2 — Browser sign-in. Open the verification_uri in a browser. If you are already signed in to Oracle as someone else, sign out first. Sign in as the Clarity service account from Step 2 (completing any MFA prompt or forced password change), enter the user_code when prompted, and wait for the Successful message. Then sign out and close the browser window.

5.3 — Token request.

curl --location --request POST '<IDENTITY_DOMAIN_URL>/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
--data-urlencode 'device_code=<DEVICE_CODE_FROM_5.1>' \
--data-urlencode 'client_id=<CLIENT_ID>'

The JSON response contains an access_token and a refresh_token. Copy the refresh_token value — you paste it into Clarity in Step 6. You do not need the access token.

Treat the refresh token like a password. Do not save it in shell history, tickets or chat. Oracle refresh tokens are single-use: do not call the token endpoint with it yourself (for example to “test” it) after copying it, because that consumes it and the value you paste into Clarity will no longer work. If that happens, repeat Step 5.

Step 6 — Enter the credentials in Clarity

In Clarity, add a new Oracle Fusion Cloud EPM integration (or edit the existing one) and fill in either the OAuth fields or the Basic Auth fields. EPM Instance URL is always required.

The username and password are optional because an OAuth-only application needs neither — but you must complete one full set (see Which method Clarity uses above).

Save, then use Clarity’s Test credentials action before the first sync — it issues a lightweight GET /v2/role/getavailableroles call, which fails fast if the URL, credentials, or role are wrong. For OAuth, a successful test also performs Clarity’s first token exchange.

How Clarity keeps the OAuth token alive

• Rotation. Every token exchange returns a new refresh token and invalidates the old one. Clarity saves the new token immediately, so the value you pasted is used exactly once; after that Clarity works from its own stored, rotated token.

• Hourly health check as keepalive. Oracle refresh tokens expire after 7 days by default, and Clarity sync schedules can be weekly or monthly. Clarity does not need a separate keepalive job: its hourly connection health check tests every application — including paused applications and ones that have not synced yet — and whenever the EPM access token has expired (Oracle issues them for about an hour) that test performs a refresh-token exchange and stores the rotated token. Oracle’s 7-day clock therefore restarts many times a day. A failed exchange marks the application unhealthy in Clarity with the reason Oracle returned. Extending the refresh-token lifetime (Step 4.5) gives more margin if Clarity or Oracle is unavailable for several days.

• When you need to paste a new token. Only if the chain breaks:

  • 7 days (or your extended lifetime) pass without a successful exchange;

  • a crash between Oracle consuming the old token and Clarity saving the new one (rare, but possible);

  • the token or the Mobile Application is revoked or deactivated in Oracle.

• To recover, repeat Step 5 and paste the new refresh token into OAuth Refresh Token. Clarity detects that the pasted value has changed and re-seeds from it. Re-saving the application with the same value it already holds does not override Clarity’s live, rotated token — so editing other fields on the application is safe.

Troubleshooting

What Clarity does NOT do

• No OAuth on Classic environments. Oracle supports OAuth 2.0 for EPM only on OCI (Gen 2); Classic environments use Basic authentication.

• No unattended OAuth bootstrap. Clarity cannot run the device-code sign-in; a person must complete Step 5 and paste the refresh token. Clarity does not use the client-credentials or JWT-assertion grants for EPM.

• No multi-environment OAuth application. One Clarity application holds one refresh token for one EPM environment.

• No application-level artifact security. Clarity manages predefined and application roles and groups. It does not read or write business-process artifact security — Planning form/dimension access permissions, data grants, approval unit security, Financial Consolidation and Close or Narrative Reporting object permissions. Those stay in the business process.

• No password management. Clarity never resets, rotates, or reads a user’s password. Creating a user sends Oracle’s “reset password” flag so Oracle emails the new account its own credentials; Clarity is not involved beyond that.

• No group or role lifecycle. Clarity can add and remove members, but it does not create, rename, or delete groups or roles in EPM.

• No deactivate / suspend. The connector supports user delete only, and deleting a user removes them from the identity domain — which means from every EPM environment sharing that identity domain, not just this one.

• No attribute write-back. Clarity does not push identity attributes (name, email, manager, department) into EPM.

• Group membership is not marked direct vs inherited. Oracle returns all member users of a group, including those inherited through nested groups, without distinguishing them, so Clarity records membership without that flag. Roles granted via a group are annotated — the Role Assignment Report’s “granted through group” value is captured on the assignment.

• Group-to-role relationships are not currently imported. Clarity requests the group list without the embedded roles payload, so the “this group confers these roles” mapping is not shown today.

• Last login is a 119-day window, not lifetime history. Oracle retains only 120 days of login audit data; Clarity stores the most recent access within that window and nothing earlier.

Need Help?