Frodo Library - v5.0.0-47
    Preparing search index...

    Type Alias Authenticate

    type Authenticate = {
        applyAccessToken(token: AccessTokenMetaType): Promise<Tokens>;
        dispose(): Promise<LogoutResult>;
        getAccessProfile(): AccessProfile;
        getTokens(
            forceLoginAsUser?: boolean,
            autoRefresh?: boolean,
            types?: string[],
            callbackHandler?: CallbackHandler,
            useDeviceFlow?: boolean,
            promptHandler?: BrowserLoginPromptHandler,
            credentialOverride?: "svcacct" | "user" | "browser" | "amster",
        ): Promise<Tokens>;
        getTokensInteractive(options: BrowserLoginOptions): Promise<Tokens>;
        hasCachedBrowserSession(host: string): boolean;
        listAccessAreas(): AccessAreaDescriptor[];
        logout(): Promise<LogoutResult>;
        probeDeploymentType(host: string): Promise<DeploymentTypeProbe>;
    }
    Index
    • Applies an already-obtained, externally-issued OAuth2 access token to state, ready for immediate use. Unlike getTokens()/ getTokensInteractive(), this never talks to an authorization endpoint itself — the token was already minted (and, by the caller's own contract, already verified) elsewhere; this only wires it onto state using the exact same deployment-type-specific handling a real browser login uses. Intended for hosts that resolve their own caller identity per request (e.g. an MCP server acting as an OAuth2 resource server) rather than performing a login themselves.

      Parameters

      Returns Promise<Tokens>

      object containing the tokens

    • Dispose of the instance when it is no longer needed (a host that creates instances over its lifetime, or exits): cancel the auto refresh timer, clear the refresh and credential handlers, forget the credentials, and end the user session only when this instance created it and did not share it. A session that came out of the token cache or was stored in it may be in use by other processes and is left to expire; the same goes for a session that this instance did not create. With the token cache switched off, the sessions that the instance created are ended.

      A disposed instance does not log in by itself any more: no timer fires and a request that finds a credential stale fails instead of logging in. Calling getTokens(), getTokensInteractive() or applyAccessToken() makes it work again. A login that is still running when dispose() is called is not interrupted and its session is not ended. A failed logout request is reported in the result and never thrown, so that a shutdown goes on.

      Returns Promise<LogoutResult>

      what happened to the session

    • Get the access profile of the current session: what the credential the library holds can do on a Cloud tenant. For an interactive login (a browser login with authorization code, or a device authorization login) and for a service account it says which scopes the token carries, whether the session can be refreshed, whether the token carries an Access Management session, which areas of the API are reachable and which are not and why (for example "the login did not request a scope that the client offers", "the access token of a device authorization login carries no Access Management session"), and what the library did differently from its defaults to make the login succeed. Every statement names its basis: what the token says, or a measured constant of the library with the date it was measured. The profile is computed from the token and the state, with no network call, so a session reused from the session cache has one too.

      What the profile says for the three interactive sessions of the built-in client (measured on a Cloud development tenant on 2026-11-14, one read call per area; "scope not requested": the client offers the scope, the login did not ask for it):

      Area Browser login, default scopes (fr:am:* fr:idm:*) Browser login, all five scopes Device login, without fr:am:*
      Access Management reachable reachable not reachable: no Access Management session
      Identity Management reachable reachable reachable
      Environment secrets and variables no: scope not requested reachable reachable
      Governance, configuration promotion, release information, certificates, custom domains, content security policy, cookie domains, SSO cookie, direct configuration session, telemetry no: the client does not offer the scope no: same no: same
      Admin federation no: the exchange client refuses the scope no: same no: same
      PingFederate administration no: an interactive login gets no PingFederate token no: same no: same

      The five scopes are fr:am:* fr:idm:* fr:idc:esv:read fr:idc:esv:update fr:idc:monitoring:*. None of these sessions has a refresh token; the access token lives 30 minutes.

      Returns AccessProfile

      the profile, or undefined if the session is not a Cloud session with an access token (a user session, Amster, ForgeOps, classic, no login yet)

    • Get tokens and store them in State

      Parameters

      • OptionalforceLoginAsUser: boolean

        true to force login as user even if a service account or Amster account is available (default: false)

      • OptionalautoRefresh: boolean

        true to automatically refresh tokens before they expire (default: true)

      • Optionaltypes: string[]

        Array of supported deployment types. The function will throw an error if an unsupported type is detected (default: ['classic', 'cloud', 'forgeops'])

      • OptionalcallbackHandler: CallbackHandler

        fills callback input in place, synchronously or asynchronously; returned or resolved values are ignored (see CallbackHandler)

      • OptionaluseDeviceFlow: boolean

        only consulted when a loaded connection profile prefers browser login (preferredCredential: 'browser', or the legacy authMode: 'interactive' for a profile predating that field) — falls back to the profile's own preferredDeviceFlow when not explicitly passed; see getTokensInteractive() (default: false)

      • OptionalpromptHandler: BrowserLoginPromptHandler

        required only when a loaded connection profile prefers browser login; every other case ignores it

      • OptionalcredentialOverride: "svcacct" | "user" | "browser" | "amster"

      Returns Promise<Tokens>

      object containing the tokens

    • Get tokens via a real interactive browser login (loopback-redirect or device-authorization grant) instead of a CLI-driven password/service- account/Amster login. Alongside getTokens(), not a replacement for it.

      Parameters

      Returns Promise<Tokens>

      object containing the tokens

    • Whether a browser-login session is cached for the host and would be reused: the cache holds one for the host's full URL (an alias or a unique substring of a saved profile is resolved to it) that is still fresh, with the same 30 seconds of headroom the cache read requires. Reads the local cache file only: no network call, nothing decrypted, nothing written to state. A session that passes can still be refused by the server later; getTokens() then falls back to its own login.

      Intended for callers that decide whether a command still needs input (a prompt, a connection form) before they log in.

      Parameters

      • host: string

        host URL, unique substring or alias of a saved connection profile

      Returns boolean

      true if a fresh browser-login session is cached for the host

    • List the areas of the API that the access profile covers, with the scopes the API calls of each declare. Static: the same list for every session. A caller that keeps its own table of what needs what (for example a command line that says which commands a login cannot run) checks it against this list.

      Returns AccessAreaDescriptor[]

      the areas, in the order the profile lists them

    • Log out: end the user session of this instance at AM (POST .../sessions?_action=logout with the session token) and remove the token cache entries that hold the credentials of that session, so that no other process picks up a session that is gone. This is the explicit logout, for a caller who asks for it: it ends the session even when the instance restored it from the token cache. The instance stops refreshing by itself afterwards (no timer, no refresh handler) and holds no credentials; getTokens() logs in again when it is called.

      An instance without a user session (a service account, a token that a caller presented) has nothing to end: the answer is none and nothing changes. The access token of a login is not revoked: the Ping documentation describes the token revocation endpoint for the clients that authenticate with a secret, but not for the public clients that these logins use, so no revocation is attempted and the token ends by its own expiry.

      Returns Promise<LogoutResult>

      what happened to the session. Throws if the logout request fails; the instance is then left as it was.

    • Anonymous deployment-type probe: identifies the deployment type of a host WITHOUT any credentials or session — two POSTs to /oauth2/authorize with the built-in admin client ids (no cookie, no CSRF token) and elimination:

      • idmAdminClient (cloud built-in) answers 302 → cloud
      • idm-admin-ui (ForgeOps built-in) answers 302 → forgeops
      • both answer 400 (neither client exists) → classic
      • anything else (no answer, a 404 or 403, an HTML page, both redirecting) is inconclusive: conclusive is false and deploymentType is 'classic' only for backward compatibility

      A 302 means "client exists AND its registered redirect URI matches" — the same clients with an unregistered redirect answer 400 redirect_uri_mismatch, and an unknown client answers 400 invalid_client. Verified live (2026-10-12) against a real AIC tenant (302/400) and a real ForgeOps deployment (400/302). Classic is inferred from two 400 answers and has not been verified live.

      Intended for pre-auth flows: prompts and previews that want the deployment type (realm map, cloud-only gating, help text) before any login is possible — e.g. a host that appears on the command line or via an env variable with no saved connection profile.

      Each request times out after 8 seconds. NOTE: reads nothing from state except the connection settings that shape the HTTP calls (allow-insecure, proxies, header overrides); never writes to it. Safe to call at any time.

      Parameters

      • host: string

        the AM base URL to probe, e.g. https://cdk.iam.example.com/am

      Returns Promise<DeploymentTypeProbe>

      the detected deployment type, whether the evidence supports it (conclusive), plus the raw per-client responses (for callers that want to log or branch on the evidence)