Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Expose Session module and update readme for 2.x release. #378

Merged
merged 2 commits into from
Jan 31, 2024
Merged

Expose Session module and update readme for 2.x release. #378

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1501f72
Expose `Session` module as `frodo.session`.
vscheuber Jan 31, 2024
0345f52
Update readme with 2.x functionality and remove feature section.
vscheuber Jan 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 73 additions & 67 deletions .github/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,14 @@

# Frodo Library 2.x - @rockcarver/frodo-lib

ForgeROck DO library, frodo-lib, a hybrid (ESM and CJS) library to manage ForgeRock Identity Cloud tenants, ForgeOps deployments, and classic deployments.
ForgeROck DO library, frodo-lib, a hybrid (ESM and CJS) library to manage PingOne Advanced Identity Cloud tenants, ForgeOps deployments, and classic deployments.

Frodo-lib powers [frodo-cli](https://github.com/rockcarver/frodo-cli), the command line tool to manage ForgeRock deployments.

## Quick Nav

- [New in 2.x](#new-in-2x)
- [Features](#features)
- [Limitations](#limitations)
- [Considerations](#considerations)
- [Installing](#installing)
- [Using the library](#using-the-library)
- [Library API docs](#library-api-docs)
Expand All @@ -20,72 +19,79 @@ Frodo-lib powers [frodo-cli](https://github.com/rockcarver/frodo-cli), the comma

## New In 2.x

2.x introduces breaking changes to support multiple instances of the library to run concurrently and connect to multiple different ForgeRock Identity Platform instances at the same time. [1.x](https://github.com/rockcarver/frodo-lib/tree/1.x) operates using a global singleton, making it impossible to connect to more than one platform instance at a time.

## Features

Frodo allows an administrator to easily connect to and manage any number of Identity Cloud tenants, ForgeOps deployment instances, or classic deployment instances from the command line. The following tasks are currently supported:

- Manage journeys/trees.

Export, import and pruning of journeys. Frodo handles referenced scripts and email templates.

- Manage applications.

List, export, and import applications (OAuth2 clients).

- Manage connection profiles.

Saving and reading credentials (for multiple ForgeRock deployments) from a configuration file.

- Manage email templates.

List, export, and import email templates.

- Manage IDM configuration.

Export of IDM configuration. Import is coming.

- Print versions and tokens.
### Multi-Instantiability

Obtain ForgeRock session token and admin access_tokens for a ForgeRock Identity Cloud or platform (ForgeOps) deployment

- View Identity Cloud logs.

List available log sources and tail them.

- Manage realms.

List realms and show realm details. Allow adding and removing of custom DNS names.

- Manage scripts.

List, export, and import scripts.

- Manage Identity Cloud environment specific variables and secrets.

List and view details of secrets and variables in Identity Cloud.

- Platform admin tasks.

Common tasks administrators need to perform daily that are tedious and repetitive. Advanced tasks, which used to be involved and potentially dangerous if performed manually, now made easy and safe.

- Create an oauth2 client with admin privileges.
- Get an access token using client credentials grant type.
- List oauth2 clients with admin privileges.
- Grant an oauth2 client admin privileges.
- Revoke admin privileges from an oauth2 client.
- List oauth2 clients with custom privileges.
- List all subjects of static user mappings that are not oauth2 clients.
- Remove a subject's static user mapping.
- Add AutoId static user mapping to enable dashboards and other AutoId-based functionality.
- Hide generic extension attributes.
- Show generic extension attributes.
- Repair org model (beta).

## Limitations
2.x introduces breaking changes to support multiple instances of the library to run concurrently and connect to multiple different ForgeRock Identity Platform instances at the same time. [1.x](https://github.com/rockcarver/frodo-lib/tree/1.x) operates using a global singleton, making it impossible to connect to more than one platform instance at a time.

`frodo` can't export passwords (including API secrets, etc), so these need to be manually added back to imported configuration or alternatively, edit the export file to add the missing fields before importing.
### New Library Structure

Removing the singleton pattern and introducing multi-instantiability forced a radical redesign of the core library functions while striving to maintain the basic usage pattern. The library is now exposing two main types describing its modules ([Frodo](https://rockcarver.github.io/frodo-lib/types/Reference.Frodo.html)) and state ([State](https://rockcarver.github.io/frodo-lib/types/Reference.State.html)). Each module in turn exports all its collection of functions as a type as well. Exposing the library structure as types enables auto-completion for both JS and TS developers with properly configured IDEs like Visual Studio Code or other and also serves as an abstraction layer between what the library exposes vs what and how it's implemented.

### New Modules

The following modules have been updated and/or added since [1.x](https://github.com/rockcarver/frodo-lib/tree/1.x):

| Module | Since | Capabilities |
| -------------------------- | ----- | ------------ |
| frodo.admin | 1.0.0 | Library of common and complex admin tasks. |
| frodo.agent | 1.0.0 | Manage web, java, and gateway agents. |
| frodo.app | 2.0.0 | Manage platform applications and dependencies. |
| frodo.authn.journey | 1.0.0 | Manage authentication journeys. |
| frodo.authn.node | 1.0.0 | Manage authentication nodes. |
| frodo.authn.settings | 2.0.0 | Manage realm-wide authentication settings. |
| frodo.authz.policy | 1.0.0 | Manage authorization policies and dependencies. |
| frodo.authz.policySet | 1.0.0 | Manage policy sets and dependencies. |
| frodo.authz.resourceType | 1.0.0 | Manage resource types and dependencies. |
| frodo.cache | 2.0.0 | Token cache management exposed through the library but primarily used internally. |
| frodo.cloud.adminFed | 1.0.0 | Manage PingOne Advanced Identity Cloud admin federation. |
| frodo.cloud.feature | 1.0.0 | Obtain info on PingOne Advanced Identity Cloud features. |
| frodo.cloud.log | 1.0.0 | Access PingOne Advanced Identity Cloud debug and audit logs. |
| frodo.cloud.secret | 1.0.0 | Mange secrets in PingOne Advanced Identity Cloud. |
| frodo.cloud.serviceAccount | 1.0.0 | Manage service accounts in PingOne Advanced Identity Cloud. |
| frodo.cloud.startup | 1.0.0 | Apply changes to secrets and variables and restart services in PingOne Advanced Identity Cloud. |
| frodo.cloud.variable | 1.0.0 | Manage variables in PingOne Advanced Identity Cloud. |
| frodo.conn | 1.0.0 | Manage connection profiles. |
| frodo.config | 2.0.0 | Manage the whole platform configuration. |
| frodo.email.template | 1.0.0 | Manage email templates (IDM). |
| frodo.idm.config | 2.0.0 | Manage any IDM configuration object. |
| frodo.idm.connector | 2.0.0 | Manage IDM connector configuration. |
| frodo.idm.managed | 1.0.0 | Manage IDM managed object schema (managed.json). |
| frodo.idm.mapping | 2.0.0 | Manage IDM mappings (sync.json). |
| frodo.idm.organization | 1.0.0 | Limited Org Model management exposed through the library but primarily used internally. |
| frodo.idm.recon | 2.0.0 | Read, start, cancel IDM recons. |
| frodo.idm.system | 2.0.0 | Manage data in connected systems. |
| frodo.info | 1.0.0 | Obtain information about the connected instance and authenticated identity. |
| frodo.login | 1.0.0 | Authenticate and obtain necessary tokens. |
| frodo.oauth2oidc.client | 1.0.0 | Manage OAuth 2.0 clients. |
| frodo.oauth2oidc.endpoint | 2.0.0 | Limited OAuth 2.0 grant flows exposed through the library but primarily used internally. |
| frodo.oauth2oidc.external | 1.0.0 | Manage external OAuth 2.0/OIDC 1.0 (social) identity providers. |
| frodo.oauth2oidc.issuer | 2.0.0 | Manage trusted OAuth 2.0 JWT issuers. |
| frodo.oauth2oidc.provider | 1.0.0 | Manage the realm OAuth 2.0 provider. |
| frodo.realm | 1.0.0 | Manage realms. |
| frodo.saml.circlesOfTrust | 1.0.0 | Manage SAML 2.0 circles of trust. |
| frodo.saml.entityProvider | 1.0.0 | Manage SAML 2.0 entity providers. |
| frodo.script | 1.0.0 | Manage access management scripts. |
| frodo.service | 1.0.0 | Manage access management services. |
| frodo.session | 2.0.0 | Limited session management exposed through the library but primarily used internally. |
| frodo.state | 1.0.0 | Manage library state. |
| frodo.theme | 1.0.0 | Manage platform themes (hosted pages). |
| frodo.utils.constants | 1.0.0 | Access relevant library constants. |
| frodo.utils.jose | 1.0.0 | Jose utility functions exposed through the library but primarily used internally. |
| frodo.utils.json | 1.0.0 | JSON utility functions exposed through the library but primarily used internally. |
| frodo.utils.version | 1.0.0 | Utility functions to obtain current library version and available released versions. |

### Secure Token Caching

The 2.x version of the library uses a secure token cache, which is active by default. The cache makes it so that when the `frodo.login.getTokens()` method is called, available tokens are updated in `state` from cache and if none are available, they are obtained from the instance configured in `state`. The cache is tokenized and encrypted on disk, so it persists across library instantiations. You can disable the cache by either setting the `FRODO_NO_CACHE` environment variable or by calling `state.setUseTokenCache(false)` from your application.
You can change the default location of the cache file (`~/.frodo/TokenCache.json`) by either setting the `FRODO_TOKEN_CACHE_PATH` environment variable or by calling `state.setTokenCachePath('/path/to/cache.json')`.

### Automatic Token Refresh

The 2.x version of the library automatically refreshes session and access tokens before they expire. Combined with the new token cache, the library will maintain a set of valid tokens in `state` at all times until it is shut down. If you do not want to automatically refresh tokens, set the `autoRefresh` parameter (2nd param) of your `frodo.login.getTokens()` call to `false`.

## Considerations

`frodo` doesn't export passwords and secrets. The platform supports configuration placeholders and environment secrets and variables allowing administrators to separate the functional configuration from sensitive secrets and variable configuration values. `frodo` assumes administrators take full advantage of these capabilities so that there is no need or expectation that exports include passwords and secrets. However, where the APIs support it, administrators can seed import data with raw secrets and `frodo` will import them.

## Installing

Expand Down
3 changes: 3 additions & 0 deletions src/lib/FrodoLib.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ import ResourceTypeOps, { ResourceType } from '../ops/ResourceTypeOps';
import Saml2Ops, { Saml2 } from '../ops/Saml2Ops';
import ScriptOps, { Script } from '../ops/ScriptOps';
import ServiceOps, { Service } from '../ops/ServiceOps';
import SessionOps, { Session } from '../ops/SessionOps';
import ThemeOps, { Theme } from '../ops/ThemeOps';
import TokenCacheOps, { TokenCache } from '../ops/TokenCacheOps';
import VersionUtils, { Version } from '../ops/VersionUtils';
Expand Down Expand Up @@ -131,6 +132,7 @@ export type Frodo = {

script: Script;
service: Service;
session: Session;

theme: Theme;

Expand Down Expand Up @@ -271,6 +273,7 @@ const FrodoLib = (config: StateInterface = {}): Frodo => {

script: ScriptOps(state),
service: ServiceOps(state),
session: SessionOps(state),

theme: ThemeOps(state),

Expand Down
Loading