Skip to content

Developer Reference

This document is a Plugin SDK reference. The Plugin SDK is part of Leapp Core and contains Base Classes that describe different types of plugins.

PluginEnvironment

A wrapper class used to expose a minumum set of methods from Leapp Core.

Currently available methods:

log

  • log(message: string, level: PluginLogLevel, display: boolean): void

Log a custom message in Leapp or in the log file

argument type description
message string the message to show
level LogLevel severity of the message
display boolean shows the message in a toast in the desktop app when true. Otherwise, log it in the log files

fetch

  • fetch(url: string): any

Retrieve the content of a URL. Returns a promise for the URL

argument type description
url string a valid HTTP URL to fetch from

openExternalUrl

  • openExternalUrl(url: string): void

Open an external URL in the default browser

argument type description
url string a valid HTTP URL to open in the default browser

createSession

  • createSession(createSessionData: SessionData): Promise<string>

Creates a new Leapp Session based on given SessionData

argument type description
createSessionData SessionData the metadata used to create the Leapp Session

cloneSession

  • cloneSession(session: Session): Promise<string>

This method allows you to clone the given Leapp Session. This operation is allowed for the following Leapp Session types:

  • AwsIamUserSession
  • AwsIamRoleFederatedSession
  • AwsIamRoleChainedSession
argument type description
session Session the Leapp Session that I want to clone

updateSession

  • updateSession(updateSessionData: SessionData, session: Session): Promise<void>

This method allows you to update the given session with the given updateSessionData. This operation is allowed for the following Leapp Session types:

  • AwsIamUserSession
  • AwsIamRoleFederatedSession
  • AwsIamRoleChainedSession
argument type description
updateSessionData SessionData the metadata used to update the given Leapp Session
session Session the Leapp Session that I want to update

openTerminal

  • openTerminal(command: string, env?: any): Promise<void>

Execute the given command in the platform-specific terminal; optionally, it is possible to set an env key/value object containing the env variables to export in the terminal, before the command execution.

The terminal window base path is set to the home directory.

argument type description
command string the command that I want to execute in the platform-specific terminal
env any optional key/value env variables object

getProfileIdByName

  • getProfileIdByName(profileName: string): string

Returns the id of a named profile from its name if it exists, otherwise creates a new profile and returns its id.

Can be used when creating/editing a session since SessionData requires the id of a named profile

argument type description
profileName string a valid named profile

getIdpUrlIdByUrl

  • getIdpUrlIdByUrl(url: string): string

Return the ID of the IdpUrl object from the given URL if it exists, otherwise creates a new IdP URL and returns its ID.

Can be used when creating/editing Federated Sessions since SessionData requires the ID of an IdP URL.

argument type description
url string the URL associated with the IdpUrl I want to retrieve

Example: display a toast message in Leapp

this.pluginEnvironment.log("Hello World", LogLevel.info, true);

Example: fetch basic usage

const res = await this.pluginEnvironment.fetch(""); //Insert a custom URL
const response = await res.json();

Example: open a URL in the browser

this.pluginEnvironment.openExternalUrl("https://leapp.cloud");

Example: create a session

async applySessionAction(session: Session, credentials: any): Promise<void> {
    const profileId = this.pluginEnvironment.getProfileIdByName("default");
    const idpUrlId = this.pluginEnvironment.getIdpUrlIdByUrl("put a valid url for an IdP here");

    this.pluginEnvironment.createSession(new AwsIamRoleFederatedSessionData(
      "arn:aws:iam::000000000000:saml-provider/test",
      idpUrlId,
      profileId,
      "us-east-1",
      "arn:aws:iam::000000000000:role/test",
      "New Name Session"
    ));
}

Example: edit the selected session

async applySessionAction(session: Session, credentials: any): Promise<void> {
    const profileId = this.pluginEnvironment.getProfileIdByName("default");
    const idpUrlId = this.pluginEnvironment.getIdpUrlIdByUrl("put a valid url for an IdP here");
    this
    .pluginEnvironment.updateSession(new AwsIamRoleFederatedSessionData(
        "arn:aws:iam::000000000000:saml-provider/test", 
        idpUrlId, 
        profileId, 
        "us-east-1", 
        "arn:aws:iam::000000000000:role/test", 
        "New Name Session"
    ), session);
}

Example: clone the selected session

async applySessionAction(session: Session, credentials: any): Promise<void> {
    await this.pluginEnvironment.cloneSession(session);
}

AwsCredentialsPlugin

A base class that needs to be extended by a plugin and serves as the action class.

After extending this class, you need to implement these methods:

applySessionAction

  • applySessionAction(session: Session, credentials: any): Promise<void>

Run your custom action

argument type description
session Session the Leapp session you run the action from
credentials any Leapp temporary-generated credentials

The credentials object has the following structure:

export interface CredentialsInfo {
  sessionToken: {
    aws_access_key_id: string;
    aws_secret_access_key: string;
    aws_session_token: string;
    region: string;
  }
}

get actioName

  • get actionName(): string>

Return a name for the action that will be display in Leapp (e.g. "My Awesome Plugin")

get actionIcon

  • get actionIcon(): string

Return a valid FontAwesome 5 code. Override default value in package.json

Example: display a session-based message in Leapp

async applySessionAction(session: Session, credentials: any): Promise<void> {
    if(session.type === Session.awsIamUser) {
        this.pluginEnvironment.log(`This is an IAM User session: ${session.sessionName}`, LogLevel.info, true); 
    }
    else {
        this.pluginEnvironment.log(`This is NOT an IAM User session: ${session.sessionName}`, LogLevel.info, true);
    }
}

package.json metadata

property values description constraints
name a custom string the name of the plugin the same used in the plugin folder
author a custom string the name of the author none
version a custom string the version of the plugin must be a semver string
description a custom string the description of the plugin none
keywords a string array the name of the plugin must contain at least "leapp-plugin"
leappPlugin an object the plugin custom configuration must contain at least "supportedOS" and "supportedSessions"
leappPlugin.supportedOS a string array ["mac", "windows", "linux"] if not specified, all OSs will be considered compatible
leappPlugin.supportedSessions a string array ["anyType, "aws", "azure", "awsIamRoleFederated", "awsIamRoleChained", "awsSsoRole", "awsIamUser"] at least one of these values must be specified
leappPlugin.icon a custom string fontAwesome code for an icon (e.g. "fa fa-globe") must be a valid FontAwesome 5 code

Plugin Examples

Open Web Console

import { Session } from "@noovolari/leapp-core/models/session";
import { AwsCredentialsPlugin } from "@noovolari/leapp-core/plugin-sdk/aws-credentials-plugin";
import { PluginLogLevel } from "@noovolari/leapp-core/plugin-sdk/plugin-log-level";

export class WebConsolePlugin extends AwsCredentialsPlugin {
  get actionName(): string {
    return "Open web console";
  }

  get actionIcon(): string {
    return "fa fa-globe";
  }

  async applySessionAction(session: Session, credentials: any): Promise<void> {
    this.pluginEnvironment.log("Opening web console for session: " + session.sessionName, PluginLogLevel.info, true);

    const sessionRegion = session.region;
    const sessionDuration = 3200;
    const isUSGovCloud = sessionRegion.startsWith("us-gov-");
    let federationUrl;
    let consoleHomeURL;

    if (!isUSGovCloud) {
      federationUrl = "https://signin.aws.amazon.com/federation";
      consoleHomeURL = `https://${sessionRegion}.console.aws.amazon.com/console/home?region=${sessionRegion}`;
    } else {
      federationUrl = "https://signin.amazonaws-us-gov.com/federation";
      consoleHomeURL = `https://console.amazonaws-us-gov.com/console/home?region=${sessionRegion}`;
    }

    if (sessionRegion.startsWith("cn-")) {
      throw new Error("Unsupported Region");
    }

    this.pluginEnvironment.log("Starting opening Web Console", PluginLogLevel.info, true);

    const sessionStringJSON = {
      sessionId: credentials.sessionToken.aws_access_key_id,
      sessionKey: credentials.sessionToken.aws_secret_access_key,
      sessionToken: credentials.sessionToken.aws_session_token,
    };

    const queryParametersSigninToken = `?Action=getSigninToken&SessionDuration=${sessionDuration}&Session=${encodeURIComponent(
      JSON.stringify(sessionStringJSON)
    )}`;

    const res = await this.pluginEnvironment.fetch(`${federationUrl}${queryParametersSigninToken}`);
    const response = await res.json();

    const loginURL = `${federationUrl}?Action=login&Issuer=Leapp&Destination=${consoleHomeURL}&SigninToken=${(response as any).SigninToken}`;
    this.pluginEnvironment.openExternalUrl(loginURL);
  }
}