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

    Type Alias RemoteProxy

    type RemoteProxy = {
        REMOTE_PROXY_TYPE: string;
        buildRemoteProxyClient(
            params: {
                clientId: string;
                clientSecret: string;
                description?: string;
            },
        ): NoIdObjectSkeletonInterface;
        buildRemoteProxyConfiguration(
            params: {
                clientId: string;
                hostVariableId?: string;
                realm?: string;
                receiverHost: string;
                secretId: string;
            },
        ): RemoteProxySkeleton;
        createRemoteProxy(
            proxyId: string,
            proxyData: RemoteProxySkeleton,
        ): Promise<RemoteProxySkeleton>;
        createRemoteProxyExportTemplate(): RemoteProxyExportInterface;
        deleteRemoteProxies(): Promise<RemoteProxySkeleton[]>;
        deleteRemoteProxy(proxyId: string): Promise<RemoteProxySkeleton>;
        exportRemoteProxies(): Promise<RemoteProxyExportInterface>;
        exportRemoteProxy(proxyId: string): Promise<RemoteProxyExportInterface>;
        generateRemoteProxySecret(length?: number): string;
        getFixedHostUrls(proxyData: RemoteProxySkeleton): string[];
        getRemoteProxyBaseUrl(proxyId: string): string;
        getTenantBoundSecrets(proxyData: RemoteProxySkeleton): string[];
        importRemoteProxies(
            importData: RemoteProxyExportInterface,
            resultCallback?: ResultCallback<RemoteProxySkeleton>,
        ): Promise<RemoteProxySkeleton[]>;
        isValidRemoteProxyName(proxyId: string): boolean;
        readRemoteProxies(): Promise<RemoteProxySkeleton[]>;
        readRemoteProxy(proxyId: string): Promise<RemoteProxySkeleton>;
        testRemoteProxy(proxyId: string): Promise<RemoteProxyTestResult>;
        updateRemoteProxy(
            proxyId: string,
            proxyData: RemoteProxySkeleton,
        ): Promise<RemoteProxySkeleton>;
    }
    Index
    REMOTE_PROXY_TYPE
    buildRemoteProxyClient buildRemoteProxyConfiguration createRemoteProxy createRemoteProxyExportTemplate deleteRemoteProxies deleteRemoteProxy exportRemoteProxies exportRemoteProxy generateRemoteProxySecret getFixedHostUrls getRemoteProxyBaseUrl getTenantBoundSecrets importRemoteProxies isValidRemoteProxyName readRemoteProxies readRemoteProxy testRemoteProxy updateRemoteProxy
    REMOTE_PROXY_TYPE: string

    Remote proxy type key used to build the IDM id: 'external.idm/'

    • Build the OAuth2 client a remote proxy needs on the receiving tenant: client credentials grant, client_secret_post, scope fr:idm:* and nothing broader. The result is data, ready for frodo.oauth2oidc.client.createOAuth2Client; it holds the secret in plain text, so hand it on and do not print or log it.

      Parameters

      • params: { clientId: string; clientSecret: string; description?: string }

        parameters

        • clientId: string

          id of the client

        • clientSecret: string

          secret of the client (at least 16 characters, see RemoteProxy.generateRemoteProxySecret)

        • Optionaldescription?: string

          optional description of the client

      Returns NoIdObjectSkeletonInterface

      the OAuth2 client

    • Build the configuration of a remote proxy with bearer authentication to a receiving tenant: the instance URL (with a trailing slash), the token endpoint of the realm, client secret post, scope fr:idm:*, and the secret as an ESV placeholder (&{esv.name}, derived from the id of the ESV secret that holds it). It is the portable form: the secret never appears in the configuration. The URLs name the receiving tenant, so a promotion would carry them to the next environment unchanged; with hostVariableId they hold an ESV placeholder instead of the host (https://&{esv.name}/openidm/) and each environment resolves its own receiver.

      Parameters

      • params: {
            clientId: string;
            hostVariableId?: string;
            realm?: string;
            receiverHost: string;
            secretId: string;
        }

        parameters

        • clientId: string

          id of the OAuth2 client on the receiving tenant

        • OptionalhostVariableId?: string

          optional id of the ESV variable on the sending tenant that holds the host name of the receiving tenant (no scheme and no path, e.g. 'openam-my-tenant.forgeblocks.com'), e.g. 'esv-remote-proxy-my-tenant-host'. Without it the URLs carry the host of receiverHost. The variable is not created here.

        • Optionalrealm?: string

          realm of the client on the receiving tenant (default: 'alpha')

        • receiverHost: string

          host URL of the receiving tenant, e.g. 'https://openam-my-tenant.forgeblocks.com/am' (https only)

        • secretId: string

          id of the ESV secret on the sending tenant that holds the client secret, e.g. 'esv-remote-proxy-my-tenant'

      Returns RemoteProxySkeleton

      the remote proxy configuration

    • Generate a random secret for the OAuth2 client of a remote proxy: URL-safe characters from a cryptographically secure random source.

      Parameters

      • Optionallength: number

        number of characters, 32 to 256 (default: 48)

      Returns string

      the secret

    • Get the URL properties (instanceUrl, tokenEndpoint) of a remote proxy whose host is written out. Such a URL names one receiving tenant, so a promotion carries that address to the next environment unchanged. A URL whose host is an ESV placeholder (&{esv.name}, https://&{esv.name}/openidm/) is resolved by each environment from its own ESV and is portable.

      Parameters

      Returns string[]

      names of the URL properties that have a fixed host

    • Get the IDM base URL that routes IDM REST calls through a remote proxy to the receiving tenant: <host>/openidm/external/idm/<proxyId>. Every IDM REST call (managed objects, config, ...) addressed below it is made on the receiving tenant by the mapped user of the proxy.

      Parameters

      • proxyId: string

        id/name of the remote proxy without the type prefix

      Returns string

      the IDM base URL of the remote proxy

    • Get the properties of a remote proxy that hold a secret encrypted by the tenant it was read from. IDM encrypts a plain text password or clientSecret on write and returns it as an encrypted $crypto object. That value belongs to one tenant: another tenant accepts it unchecked, and it fails only when the proxy is used. An ESV placeholder (&{esv.name}) is not encrypted and is the portable way to configure a secret.

      Parameters

      Returns string[]

      names of the properties that hold a tenant-bound secret

    • Import remote proxies. The name and the configuration of every remote proxy are checked before it is written, and a refused remote proxy is never sent to the tenant. Without a result callback every remote proxy is checked before the first one is written: if any of them is refused, nothing is imported.

      Parameters

      • importData: RemoteProxyExportInterface

        import data

      • OptionalresultCallback: ResultCallback<RemoteProxySkeleton>

        Optional callback to process individual results. When given, the outcome of every remote proxy is passed to it as it happens (a refused or failed remote proxy as an error that names it) and a refused or failed remote proxy does not stop the others and does not throw: the remote proxies that were imported are returned. The refused remote proxies are reported first, then the outcome of each write. Import data without a remoteProxy object always throws.

      Returns Promise<RemoteProxySkeleton[]>

      a promise that resolves to an array of remote proxy objects

      If the import data has no remoteProxy object (always), or, without a result callback, if any remote proxy is refused (nothing is imported) or cannot be written (after every remote proxy was tried). The error carries one nested error per remote proxy.

    • Check the name of a remote proxy. The name becomes part of the IDM entity id external.idm/<name> and of a REST path, so it is restricted: 1 to 100 characters, starting with a letter or a digit, containing only letters, digits, ., _ and -. Every operation of this module refuses any other name before it makes a request.

      Parameters

      • proxyId: string

        name of the remote proxy without the type prefix

      Returns boolean

      true if the name is allowed

    • Read remote proxy

      Parameters

      • proxyId: string

        id/name of the remote proxy (the name of the receiving tenant) without the type prefix

      Returns Promise<RemoteProxySkeleton>

      a promise that resolves to a remote proxy object

    • Check that a remote proxy works: make one read through it (GET /openidm/info/login on the receiving tenant) and classify the answer. A working proxy answers with the identity and roles the proxy is mapped to, which shows at once that the token request, the static user mapping and the routing work. It makes no change and returns no secret.

      Parameters

      • proxyId: string

        name of the remote proxy without the type prefix

      Returns Promise<RemoteProxyTestResult>

      a promise that resolves to the result of the check

    Settings
    Member Visibility

    On This Page
    Properties
    Methods