Customer-facing setup instructions: what an Oracle Cloud administrator must configure in an OCI IAM identity domain (formerly Oracle Identity Cloud Service / IDCS), and which values to enter into Clarity.
Overview
The Clarity Oracle Cloud Identity Domain connector reads the users, applications, roles and groups of one OCI IAM identity domain through that domain’s own administration API (/admin/v1, the Identity Domains REST API).
What Clarity syncs | Identity domain source | Clarity entitlement type |
|---|---|---|
Users (accounts, active/inactive, primary email, display name, username) | GET /Users | — |
Last Access Date | lastSuccessfulLoginDate on each user’s userState extension | — |
Applications (integrated applications in the domain) | GET /Apps | application |
Application roles | GET /AppRoles | application role |
Groups | GET /Groups | group |
Dynamic resource groups | GET /DynamicResourceGroups | dynamic group |
A user’s group memberships | the groups attribute returned with each user | — |
Which roles, groups, dynamic groups and directly-granted users belong to each application | GET /Apps/{id} (adminRoles, userRoles, grants) | — |
Which users and groups hold each application role | GET /AppRoles/{id} (members) | — |
Application roles are named <application> - <role> in Clarity, so a role is always readable next to the application it belongs to.
Authentication is OAuth 2.0 client credentials — Clarity exchanges a Client ID and Client Secret for a one-hour access token at {tenant_url}/oauth2/v1/token, using the scope urn:opc:idm:__myscopes__. That scope is not something you configure: it simply means “everything the app role granted to this application allows”, so the application’s app role (Step 3) is what actually determines its permissions. There is no browser sign-in, no redirect URL and no user consent screen involved.
This connector is read-only. It imports users and entitlements for access reviews and reporting; it never writes anything back to the identity domain. See What Clarity does NOT do (section below).
Prerequisites
An OCI IAM identity domain (formerly IDCS) and access to the OCI Console with permission to create integrated applications in that domain — typically the Identity Domain Administrator or Application Administrator role.
Authority to grant the new application an identity-domain administrator app role (Step 3). Without an app role the credentials authenticate but every API call returns 403.
One Clarity application per identity domain. A domain is the unit of isolation in OCI: an application created in domain A cannot read domain B. Tenancies commonly have several domains (the Default domain plus one per environment, and one per Fusion environment where Fusion created its own), and each one that you want in Clarity needs its own confidential application and its own Clarity application.
Step 1 — Find your identity domain URL
Clarity calls the domain at its IDCS host, in the form:
https://idcs-<id>.identity.oraclecloud.com
To find it: OCI Console → Identity & Security → Domains → <your domain>. The Domain URL (sometimes shown as Domain URL / IDCS URL) on the domain’s overview page is the value you want. Copy the scheme and host only — no path, and no trailing slash (Clarity trims one if you leave it on).
Make sure you are looking at the domain you actually want to review. The Default domain of a tenancy and a Fusion-created domain are different domains with different idcs-<id> hosts and different user populations; credentials from one will not read the other.
Step 2 — Create a confidential application (client credentials)
In the OCI Console, in the domain from Step 1:
Go to Identity & Security → Domains → <your domain> → Integrated applications.
Select Add application, choose Confidential Application, then Launch workflow.
Give it a name that identifies it as a Clarity integration (for example Clarity Security — read-only). No Application URL or sign-in URL is needed; Clarity never sends a user to this application.
On the OAuth step, select Configure this application as a client now, and under Grant types enable Client credentials. Leave every other grant type off. Leave Redirect URL, Logout URL and Post-logout redirect URL blank — a client-credentials application authenticates as itself, so there is no redirect and no consent screen to configure. If a step in the wizard asks you to configure the application as a resource server, skip it; Clarity is a client, not a resource server.
Continue through the remaining wizard steps (web tier policy, resources) and select Finish.
Oracle shows the Client ID and Client Secret once, in the Application added dialog. Copy both now — the secret cannot be retrieved later, only regenerated.
Back on the application’s page, select Activate and confirm. An inactive application cannot obtain a token.
Step 3 — Grant it an identity-domain admin role
Client credentials on their own grant nothing. Permissions come from the app role attached to the application.
Open the application → OAuth configuration (the Client configuration section) → Token issuance policy.
Select Add app roles, then Add roles.
Select a role that can read the domain’s users, applications, application roles, groups and dynamic resource groups. Identity Domain Administrator is the role Oracle documents for full Identity Domains REST API access and is the one to use if you want a configuration that is known to work.
Save, and confirm the role is listed on the application. If you changed the role after Clarity had already connected, no action is needed in Clarity — the next token it requests picks the change up.
Least privilege — unverified. Oracle offers narrower administrator roles (for example User Administrator, Application Administrator, Security Administrator). We have not verified which minimal combination permits all of GET /admin/v1/Users, /Apps, /AppRoles, /Groups and /DynamicResourceGroups — reading applications and application roles in particular is broader than a user-only administrator role covers. If your security team requires least privilege, grant a narrower set, run Test connection and then a full sync, and check whether applications and application roles actually arrive. Add roles until they do, rather than assuming a smaller set is sufficient.
Clarity only ever issues GET requests against this domain, whatever role you grant.
Step 4 — Enter the credentials in Clarity
In Clarity, add a new Oracle Cloud Identity Domain application. Its credential fields are labelled with their raw field names — you will see the snake_case names exactly as written below, not friendly labels:
Clarity field (as shown) | Value |
|---|---|
client_id | The Client ID from the confidential application (Step 2.6). Required. |
client_secret | The Client Secret from the same application (Step 2.6). Required; masked and stored encrypted. |
tenant_url | The identity domain URL from Step 1, e.g. https://idcs-abc123def456.identity.oraclecloud.com. Required. Scheme + host only; a trailing slash is trimmed automatically. |
These three fields are the whole credential set — there is nothing else to enter and no scope to type in.
Choose Next, to use Clarity’s Test connection action. It performs a single GET /admin/v1/Users?limit=1 against the domain with a freshly issued token, so a pass proves three things at once: the Tenant URL resolves to a real identity domain, the Client ID/Secret produce a token, and the application’s app role is sufficient to read users. It does not prove that applications, application roles or dynamic resource groups are readable — only a full sync shows that.
Reusing these credentials for Oracle Fusion Cloud ERP. The Fusion Cloud ERP connector’s optional Last Access Date fields want exactly this kind of confidential application. If the idcs-<id> portion of this connector’s tenant_url matches the OAuth IDCS ID configured on a Fusion Cloud ERP application in Clarity, both point at the same identity domain and you can reuse this application’s Client ID and Client Secret there verbatim. If the idcs-<id> values differ, they front different domains (different Fusion environments, or the Default OCI domain versus a Fusion-created one) and each needs its own confidential application. See the Oracle Fusion Cloud ERP setup guide, section “Step 3 — Optional: Last Access Date via the OCI IAM identity domain”.
Troubleshooting
Symptom | Likely cause |
|---|---|
401 Unauthorized / invalid_client when requesting the token | Client ID or Client Secret is wrong or was regenerated in OCI; or the confidential application was never activated (Step 2.7); or the Client credentials grant is not enabled on it (Step 2.4). |
Token is issued, then 403 Forbidden on /admin/v1/Users | The application has no app role, or a role without read access to users. Add an app role under Token issuance policy (Step 3). This is the single most common failure. |
Test connection passes, but the sync brings in no applications or application roles | The app role is narrower than user-read. Grant a role that also covers applications and application roles (Step 3). |
404, an HTML error page, or a host that does not resolve | tenant_url is not the domain’s IDCS URL. It must be https://idcs-<id>.identity.oraclecloud.com — not the OCI Console URL (cloud.oracle.com), not a regional API endpoint, and not an application URL. |
The users that appear are not the ones you expected | Wrong identity domain. A tenancy’s Default domain and a Fusion-created domain each have their own idcs-<id> host and their own users. Re-check the Domain URL in Step 1 against the domain whose users you want to review. |
Last Access Date is empty for some or all users | lastSuccessfulLoginDate is only populated after a user has actually authenticated to this identity domain. Accounts that have never signed in, and accounts that sign in somewhere else (a federated IdP that does not report back, or another domain), have no value to report. Clarity leaves the field blank rather than guessing. |
Last Access Date looks “too recent” for an application-specific review | The timestamp is a domain-level attribute: it records the last successful authentication to the identity domain, not use of any one application in it. If the domain fronts several applications, a sign-in to any of them updates the one timestamp. |
What Clarity does NOT do
No provisioning or deprovisioning. Clarity cannot grant or revoke a group, an application role or an application grant in the identity domain. Access review decisions have to be actioned by an administrator in OCI.
No user creation or deletion. Clarity cannot create, delete, disable or re-enable an account in the domain. The connector’s user-creation path is explicitly unsupported and always declines.
No password, MFA or security-policy changes. Clarity never resets a password, enrols or resets a factor, or edits sign-on/MFA policies.
No attribute write-back. Clarity does not push identity attributes into the domain; the import is one-way.
No OCI tenancy-level IAM. This connector reads only inside one identity domain via /admin/v1. Tenancy-level OCI IAM objects — compartments, policies, dynamic groups defined at tenancy level, API keys, user capabilities — are a different API and are not imported by this connector. Do not expect compartments or policies to appear here.
One domain per application. There is no tenancy-wide view: each identity domain you want in Clarity is its own Clarity application with its own confidential application and credentials.
Need Help?
If you have any problems, contact your customer success team. You can also get in touch with our general support via email, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.