> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/start/first-login.md). # Sign in and confirm your context Sign in to the Webconsole, establish what your account can actually administer, and confirm the version and configuration layer before your first change. ## What this is, and when you need it Your first session is a reconnaissance exercise, not a configuration exercise. OpenIAM decides what you may administer from your entitlements, not from an "administrator" flag, so two accounts on the same instance see genuinely different consoles. Before you change anything, establish three things: which menu items you hold, which context path you are in, and which product and schema version you are looking at. ## At a glance | | | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | A signed-in Webconsole session, a written list of the menu items your account actually holds, your own sign-in event found in the audit log, and the image tag, schema version and any `OPENIAM_PROP_*` overrides recorded against this environment | | **Where** | `/idp/login` to sign in, then `/webconsole/`; the menu tree at `/webconsole/menus`, the audit log at `/webconsole/auditLog`, and property values under **Administration → System Configuration** | | **You need first** | The host URL and the account you were given, a second browser session you can hold open as a known-good administrator, and read access to the deployment manifest | | **Takes** | 20 to 40 minutes, once per environment | | **Reversible** | Yes: nothing on this page changes configuration. Reading another identity's record can trigger the help desk verification flow, which is a prompt, not a change | ## What you need first * A URL for the OpenIAM host, and the account you were given. * A second browser session (different profile or private window) that you can keep signed in as a known-good administrator. Establish this before you touch anything in [Change configuration safely](/administration-guide/start/change-safely.md)'s "keep a way back in" list. * Read access to the deployment manifest, so you can check for `OPENIAM_PROP_*` overrides. ## Sign in {% stepper %} {% step %} ### Go to the identity provider, not the console Sign-in is served by the IdP context, at `/idp/login`. The shipped URI pattern `LOGIN_HTML` publishes `/idp/login.html` with authentication level grouping `NONE`, which is why the login page is reachable unauthenticated. If your login page returns a challenge or an error instead of a form, that pattern or its authentication level is the first thing to check. {% code overflow="wrap" %} ``` https:///idp/login ``` {% endcode %} Requesting `/webconsole/` directly works too: an unauthenticated request is redirected to the IdP and returned afterwards using the postback URL parameter. If it does not come back, the content provider's postback parameter name is the usual cause — see [Content provider and URI pattern reference](/administration-guide/access/content-providers-and-uri-patterns/content-provider-reference.md#shipped-field-defaults). {% endstep %} {% step %} ### Complete whatever second factor the policy demands The IdP exposes one route per authentication step, and which ones you see is decided by the authentication policy on the content provider, not by your account: `/idp/auth-password`, `/idp/auth-questions`, `/idp/auth-cert`, `/idp/auth-web`, `/idp/auth-sas`, `/idp/auth-captcha`, `/idp/auth-user-verification`, and `/idp/auth-select` when more than one method is offered. See [Authentication providers and MFA](/administration-guide/security/authentication-providers-and-mfa.md). {% endstep %} {% step %} ### Land in the Webconsole `https:///webconsole/` renders the landing page. Sign out at `/idp/logout` (`LOGOUT_PATTERN`, also authentication level `NONE`). {% endstep %} {% endstepper %} ## Confirm what you can administer OpenIAM's console navigation *is* an entitlement surface. Every menu item and every action button is a row in `RES` with `RESOURCE_TYPE_ID = 'MENU_ITEM'`, granted to you through `RESOURCE_ROLE`, `RESOURCE_GROUP` or `RESOURCE_USER`. The tree is computed per user from a named root menu, and returns only the branches you hold — so an empty area of the console means a missing grant, not a missing feature. Check it against another account with `/webconsole/getCurrentMenuTreeForPrincipal`. That has two consequences worth internalising on day one: * **A missing button is an entitlement problem, not a bug.** If a colleague can deactivate a user and you cannot, the difference is a `MENU_ITEM` grant, and it is named. The lifecycle buttons are individually entitleable — see [Run a user lifecycle action](/administration-guide/identities/user-lifecycle-actions.md) for the ten resource IDs. * **Menu visibility and authorization are separate checks.** Hiding a menu item does not protect the operation behind it: each operation checks the caller's own authorization independently, so an administrator who reaches it by typing the route is still refused. The reverse also happens — a granted operation whose menu item is not granted, which reads to the user as a missing feature. Treat menu configuration as ergonomics and entitlements as security, and grant both. {% stepper %} {% step %} ### Walk the top-level navigation and write down what is present The root menus are named by properties rather than by the menu rows themselves, so renaming a menu resource without changing the matching property makes that whole area disappear. The two you will meet first: | Property | Shipped value | Root of | | ---------------------------------------------- | ---------------- | ------------------------------------ | | `org.openiam.ui.landing.page.user.root.id` | `USER_ROOT_MENU` | The user search and creation area | | `org.openiam.ui.landingpage.user.edit.root.id` | `USER_EDIT_MENU` | Everything under an open user record | A third one worth knowing: `org.openiam.ui.webconsole.save.user.btw.menu.name` ships `SAVE_USER_BTN`. The **Save** button on the user edit page is itself a menu item; if you can open a user but not save one, that grant is missing. **None of the three is on a screen.** They have no row on **Administration → System Configuration**, so you cannot read their running values from the Webconsole; they are supplied to the Webconsole artifact by the deployment, and changing one is the deployment owner's job — see the [Installation Guide](/installation/installation.md). What you can observe is the consequence: if a whole area is missing from the navigation, compare the menu resource IDs on the menu administration screen at `/webconsole/menus` against the shipped values above, and ask the deployment owner to confirm the effective value before you conclude the menu row is wrong. {% endstep %} {% step %} ### Open the menu administration screen **Access Control → Menus** at `/webconsole/menus`, and an individual item at `/webconsole/editMenu`. This is the authoritative list of `MENU_ITEM` resources, their `URL` values and their `IS_VISIBLE` / `IS_PUBLIC` resource properties. Read it before you conclude that a feature is not installed. {% endstep %} {% step %} ### Prove your reach on a user record Open the user search at `/webconsole/users` and open any user. The buttons rendered on the user info page are the members of the `USER_INFO_PAGE` menu that you hold. If the page loads but no action buttons appear, you hold `USER_INFO_PAGE` and none of its children. {% hint style="info" %} `/webconsole/users/legacy` still serves the pre-4.2.2 search screen, deprecated as of 4.2.2. Use `/webconsole/users`; the legacy route is there for comparison, not for daily work, and no release since 4.2.2 has improved it. {% endhint %} {% endstep %} {% step %} ### Check whether a help desk gate is in front of you If `org.openiam.am.helpdesk.role.id` names a role and your account is a member of it, every action against another user requires that user to have been confirmed in this session first — `canHelpdeskPerform` throws on `GET` to send you to the identity-verification flow and returns `false` on anything else, which renders as `403`. The property ships **empty**, which disables the gate entirely; if it is set on your instance, that is a deliberate local decision. {% endstep %} {% step %} ### Note which context path you are in Look at the address bar. `/webconsole` and `/selfservice` are different applications with different behaviour for the same operation, and the guide will tell you when it matters. The full list is [The three URL surfaces](#the-three-url-surfaces), below. {% endstep %} {% endstepper %} ### When a menu change does not take effect Three things account for almost every "I changed the menu and nothing happened". They apply to action buttons too: a **Save** button missing from an edit screen is a missing menu grant, not a release difference. **Nothing you type in the item dialog is stored until you press Save Menu Tree.** Closing the dialog changes the tree in your browser only. **Is Public is not the opposite of hidden.** A public item is added to every user's entitled set, so clearing the flag does not hide it from a role that also holds its own grant — remove that grant on the role's **Menus** tab as well. The item's detail panel shows **Is Public**, **Is Visible** and the users, groups and roles entitled to it; read it before concluding anything. The same two checks answer the reverse case, an item a population should see and does not — **My Current Access**, for example, is the `MY_CURRENT_ACCESS` item under `MY_INFO_ACCESS_REQUEST`. **The result is cached twice.** The menu tree is rebuilt on the sweep governed by `org.openiam.authorization.manager.menu.threadsweep`, shipped `300000` — five minutes. Each user's entitlements are cached separately, `org.openiam.authorization.manager.cache.local.ttl.minutes` (shipped `30`) in the service and `org.openiam.authorization.manager.cache.remote.ttl.minutes` (shipped `60`) in Redis, and that user's copy is purged when they sign out. Having the affected person sign out and back in is the quick way to prove a grant landed. ## Confirm the version and the configuration layer Do this once per environment and keep the answer with your change records. | Fact | Where to get it | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Image tag | `OPENIAM_VERSION_NUMBER`-`BUILD_ENVIRONMENT` from `conf/starter/env.sh` (defaults `2026.8.1` and `dev`), or `kubectl describe pod` on a running service | | Schema version | Highest successful Flyway row in the `FLYWAY_OPENIAM_DATABASE_NAME` schema; baseline is `2.3.0.0`, and the newest release this guide describes is `2026.8.1.0` | | Effective property values | **Administration → System Configuration**, then compare against [System properties](/administration-guide/reference/system-properties.md) | | Container overrides | Search your Compose/Helm manifests for `OPENIAM_PROP_*` | {% hint style="danger" %} Do not skip the container-override check on a first session. A property set as an environment variable is invisible on the System Configuration screen — the screen keeps showing the database value while the service uses the variable. This is the single most common reason a new administrator believes a setting is wrong. See [Where settings live](/administration-guide/start/where-settings-live.md). {% endhint %} ## Verification Your first session succeeded when you can name, from evidence rather than assumption: * The menu items you hold, read from `/webconsole/menus`. * Whether the help desk gate applies to you (`org.openiam.am.helpdesk.role.id`). * The image tag, the schema version, and any `OPENIAM_PROP_*` overrides in force. * Your own sign-in event in the audit log. Open **Administration → Log Viewer** at `/webconsole/auditLog` and find it. If sign-in produced no audit row, your audit pipeline is not recording, and you should fix that before you make changes you may need to prove later — see [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md). ## When it goes wrong | Symptom | Cause | Fix | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `/webconsole/` redirects to `/idp/login` in a loop | The content provider's auth cookie domain does not match the host you are using. `DEFAULT_CP` sets `AUTH_COOKIE_DOMAIN` and `AUTH_COOKIE_NAME` in `CONTENT_PROVIDER` | Inspect the `CONTENT_PROVIDER` row for the domain pattern you are actually browsing | | Sign-in succeeds, Webconsole shows an empty navigation tree | No `MENU_ITEM` grants reach your account under `USER_ROOT_MENU` | Grant through a role at `/webconsole/menus`; check `RESOURCE_ROLE` for the root menu resource | | Menu item is visible but clicking it returns `401` or `403` | The item is visible, but the URI pattern in front of the operation and the operation itself each run their own authorization check | Grant the operation and its pattern, not the menu; the operation names are the resource IDs | | Cleared **Is Public** and the item is still there for a role | That role holds its own grant on the item, which `Is Public` was masking | Remove the grant on the role's **Menus** tab; the item's detail panel lists the roles entitled to it | | Granted a menu item or a button and the user still cannot see it | The menu tree cache and the user's entitlement cache have not turned over | Wait out `org.openiam.authorization.manager.menu.threadsweep` (five minutes), then have that user sign out and back in | | **Save** button missing from an edit screen | The button is itself a menu item and the role does not hold it | Grant it on the role's **Menus** tab — this is configuration, not a release difference | | A `GET` on another user's record bounces you to security questions | You are a member of `org.openiam.am.helpdesk.role.id` and that user is not the session's confirmed help desk user | Complete the verification flow, or remove yourself from the help desk role for administrative work | | Screen exists but a field or drop-down is empty | A migration did not complete; the seed rows for that feature are missing | Compare the Flyway history high-water mark against the image tag | | Setting looks right on screen, product behaves otherwise | `OPENIAM_PROP_*` override in the deployment manifest | Read the manifest; change it there, not in the Webconsole | ## The three URL surfaces OpenIAM does not present one web application. It presents three, each with its own context path, its own container and its own audience, and in the shipped topology one reverse proxy fronts them all on port 80, so administrators, employees and the sign-in flow are all reached on the same host. The mappings are deployment configuration, not Webconsole configuration — you cannot change them from any screen in this guide — but you need to recognise them, because a page that will not load is very often a context path that is not being forwarded. | Context path | What it is | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `/idp` | The identity provider — sign-in, logout, MFA step-up, SAML endpoints. Every unauthenticated user starts here | | `/webconsole` | The administration console. Everything in this guide happens here unless a page says otherwise | | `/selfservice` | The end-user and reviewer portal — profile, requests, approvals, direct reports, self-registration | | `/selfservice-ext` | The externally exposed SelfService variant | | `/reportviewer` | Rendered report output | | `/openiam-ui-static` | Shared static assets and locale bundles | | `/ui-v2`, `/webconsole-v2`, `/selfservice-v2` | The v2 single-page bundle. `/ui-v2` is the neutral asset prefix; the two app prefixes serve the same application | {% hint style="info" %} The context path is not cosmetic. Several behaviours change depending on which context the request arrived in. Termination reroutes through a workflow **only** under `/selfservice` (see [Run a user lifecycle action](/administration-guide/identities/user-lifecycle-actions.md)), and `org.openiam.selfservice.organization.search.enabled` narrows search **only** under `/selfservice` (see [Change many users at once](/administration-guide/identities/bulk-operations.md)). The same action reached from the Webconsole and from SelfService can therefore do different things — so when you reproduce a reported problem, reproduce it in the context the user was in. {% endhint %} Two shipped proxy behaviours matter to administrative work and cannot be changed from the Webconsole. The proxy caps request bodies at 30 MB, which is the real ceiling on CSV uploads for synchronization from file — a larger file is rejected before OpenIAM sees it, so split it or ask the deployment owner to raise the limit. It also sets `Referrer-Policy: strict-origin-when-cross-origin` globally, which OpenIAM relies on because several flows need the full referring URL rather than just the host. ## Related * [Start administering OpenIAM](/administration-guide/start.md) — the rest of this section, and where to go next * [The OpenIAM object model](/administration-guide/start/object-model.md) — what `MENU_ITEM`, `RES` and entitlements actually are * [Change configuration safely](/administration-guide/start/change-safely.md) — read before your first change *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/administration-guide/start/first-login.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.