> 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/solution-architecture/access/entry-points.md). # Entry points and the user's experience Decide where a user starts — a portal, a bookmark or a deep link — and whether sign-in is initiated at the application or at OpenIAM, on the principle that the design should work the way users already ## What this is, and when you need it *"Do I have to log in at the application's own URL, or at the OpenIAM portal?"* It is asked in every design conversation, usually by someone who has twenty bookmarks and no intention of giving them up. The answer is an architecture decision, not a preference: it determines which federation flows have to be enabled, what happens to a link in an email, and whether the programme is remembered as an improvement or as the thing that broke everybody's shortcuts. You need this page when designing the rollout, and again whenever someone proposes that all access should be "through the portal". ## The position **Work the way the user works, rather than making the user work the way we work.** A user with twenty bookmarked applications should keep using them. A deep link in an email — to a specific approval, a specific record, a specific report — should land on that thing, not on a home page. A portal should exist for discovery, for the applications people use monthly rather than hourly, and for requesting access. None of the three excludes the others, and a design that supports only one has chosen convenience for the implementers over adoption. The practical consequence is that entry points are a **capability** to enable, not a route to enforce. ## The decision | Entry point | What has to be true | What it costs | What it buys | | -------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | **The portal** — the user starts at OpenIAM and launches from a list | Applications are represented as resources the user is entitled to | A page to keep current, and a habit users have to acquire | Discovery, a single place to find and request applications, and a natural home for the request catalogue | | **A bookmark** — the user starts at the application, as they always have | The application initiates sign-in and OpenIAM answers | Every application must support the flow it initiates, and be configured for it | Zero change to how people work. The highest-adoption option by a distance | | **A deep link** — the user starts at a specific page inside an application | The return target survives the sign-in round trip | Configuration discipline; the traps below are real and silent | Links in email, in tickets and in chat continue to work. This is what people actually click | Almost every large estate needs all three. ## SP-initiated and IdP-initiated, and why both matter The two federation flows correspond directly to two of the entry points. **SP-initiated** is the bookmark. The user goes to the application, the application discovers there is no session and asks OpenIAM to authenticate them, and OpenIAM returns them to where they were going. It is the flow that preserves deep links, because the application tells OpenIAM what it wanted, and it is the flow to prefer wherever the application supports it. OpenIAM handles inbound authentication requests and audits them. **IdP-initiated** is the portal tile. The user is already signed in to OpenIAM, clicks an application, and OpenIAM sends an assertion to it unsolicited. OpenIAM supports this and provides a per-application initiation address for a portal to link to. Two constraints belong in the design rather than in the configuration: **Not every service provider accepts an unsolicited assertion.** Many disable it deliberately, because an unsolicited response is harder to protect against replay. Where an application refuses it, the portal tile must be a link to the application's own address — which turns the portal launch into an SP-initiated flow, and works fine. **IdP-initiated flows land the user wherever the application decides**, usually its home page. If the requirement is "the link in this email opens this record", that is an SP-initiated flow and no amount of portal configuration substitutes for it. ```mermaid sequenceDiagram autonumber participant U as User participant A as The application participant O as OpenIAM U->>A: Opens a bookmarked deep link A->>O: Asks OpenIAM to authenticate, carrying where the user was going O->>U: Authenticates the user, if there is no session yet O->>A: Returns an assertion, and the original destination A->>U: The page the user actually asked for ``` The point of the diagram is the fourth step: the original destination is carried through the round trip. That is the whole mechanism of deep linking, and the traps below are all ways of losing it. ## What breaks a deep link Three of them, and all three are silent. **A static relay state.** When OpenIAM is the identity provider, the destination can either be passed through from the application's own request or fixed to a static value. **If a static value is set, it wins over the application's own** — so every user lands on the same page regardless of what they clicked. This is the single most common way a working deep link stops working, and there is no error to notice. **A return target the platform will not accept.** Where the user is sent to OpenIAM to sign in and then returned, the return address is validated: it must be a path within the protected context rather than an arbitrary URL, which is an anti-open-redirect control and a correct one. It also means a design that expects users to be bounced back to a different host after sign-in needs a different mechanism than the return parameter. **An application whose deep links require a session it does not create.** Some applications will accept an assertion at their sign-in endpoint and then discard the requested path. That is the application's behaviour and no configuration on the identity side fixes it. Discover it by testing a deep link — not a home page — as the acceptance test for every integration. ## The portal OpenIAM ships one. Self-service presents the applications the signed-in user is entitled to, with a launch action per application, and a launch pad reachable from the header that ships enabled. It also surfaces the person's related accounts — so someone who does administrative work from a second identity can see and launch it from the same place, which is a small thing that saves a great deal of explaining. Design decisions the portal raises: **Which applications appear.** The list is driven by entitlement, which means the portal is only as complete as the resource model. An application nobody is entitled to in OpenIAM does not appear, however much it is used — a good forcing function for the inventory, and a poor surprise at go-live. **What the tile does.** For an application that accepts unsolicited assertions, the tile can initiate the flow at OpenIAM. For everything else, the tile is a link to the application's own address. Both are correct; mixing them without recording which is which makes later troubleshooting harder than it needs to be. **Whether the portal is the front door or a catalogue.** In most workforce estates it is a catalogue — the place to find something new or to request access — and daily work still starts at a bookmark. Setting the expectation that way early avoids an adoption metric that measures the wrong thing. ## Desktop and network entry points Two more entry points are worth naming because they change the experience more than any portal decision. **Desktop single sign-on.** Where workstations are domain-joined, a user who has already signed in to their workstation can reach protected applications with no prompt at all. That is the best entry-point experience available, it costs nothing at the point of use, and it is frequently omitted from designs because it is a domain-team dependency rather than an identity-team one. **Off-network access.** Bookmarks that resolve to internal addresses do not work from outside, whatever the identity design says. Where remote access is in scope, decide early whether applications are published externally through the gateway or reached over a network path — because that decision, not the SSO design, determines whether the bookmark works from home. ## Crossing to another organization Where a second organization's applications are in the picture, the entry-point question extends: a user follows a link or a portal tile into the other estate, is authenticated by their own identity provider, and arrives at an application governed there. Both flows still apply — a bookmark into the other estate is SP-initiated, a tile is IdP-initiated — and the same deep-link traps apply at the bridge. What does not cross is the request: a user reaches the other organization's catalogue rather than raising a request that is routed there. See Part 5, *Where a request lives when two catalogues exist*, and Part 5, *Cross-organization federation*. ## What we recommend **Enable SP-initiated flows for every application that supports them.** This is the recommendation that carries the most user goodwill per unit of effort, and it is the one that preserves bookmarks and deep links. **Enable IdP-initiated flows as well, where the application accepts them**, and use them for the portal. Where it does not, make the portal tile a link to the application's own address. **Never set a static return destination on a provider that has real users with real deep links.** If one is needed for a specific application, record why, and record that deep linking to that application is therefore not available. **Test a deep link, not a home page**, as the acceptance criterion for every integration. **Treat the portal as a catalogue rather than a mandatory front door**, and measure requests fulfilled rather than portal sessions. **Do not migrate users' bookmarks as a project task.** Make the bookmarks keep working instead. The circumstance that changes this advice is a population with no existing habits — a new customer-facing service, a newly acquired population being onboarded — where a portal-first experience costs nothing because there is nothing to preserve. ## What OpenIAM does not do here * **IdP-initiated sign-on depends on the service provider accepting an unsolicited assertion.** Many do not, by policy, and OpenIAM cannot make them. * **A static return destination overrides the application's own**, silently, with no error and no warning. * **The return target after sign-in must be a path within the protected context.** An arbitrary external address is refused, by design. * **The portal lists what the user is entitled to in OpenIAM.** It is not a discovery tool for applications OpenIAM does not know about, and it will not show an application whose access is granted somewhere else. * **Nothing rewrites a user's existing bookmarks.** Preserving them is achieved by supporting the flows they trigger, not by migrating them. * **OpenIAM cannot make a deep link work in an application that discards the requested path** after authentication. That is the application's behaviour. ## Related * [Choosing an SSO approach per application](/solution-architecture/access/sso-approach-per-application.md) — what each application supports, which determines which flows are available. * [Where authentication should live](/solution-architecture/access/where-authentication-lives.md) — who authenticates the user once they arrive. * *OpenIAM as a SAML identity provider* in the Administration Guide — the two flows, their addresses and the relay-state ordering. * Part 5, *Where a request lives when two catalogues exist* — the entry-point question when two platforms are live. *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/solution-architecture/access/entry-points.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.