Website | Roadmap | Blog | Slack | Documentation | Troubleshooting
⚡ Lightning Fast, Safe, Desktop App for Cloud credentials managing and generation
Leapp is a Cross-Platform Cloud access App, built on top of Electron.
The App is designed to manage and secure Cloud Access in multi-account environments, and it is available for MacOS, Windows, and Linux.
This README covers all the steps required to build a simple plugin for Leapp. If you are in a rush, you can jump directly to the build section!
Just click the green button above ⬆️ or use this quicklink. This action will fork the repository and gives you a ready-to-use template project for creating a new plugin.
Just clone the forked repository and use
npm install
You are ready to go.
Inside the project folder you will find 3 configuration file but you need to edit ony package.json:
PACKAGE.JSON overview of metadata:
{
"name": "<YOUR-PLUGIN-NAME-IN-SNAKE-CASE>", // Must be unique on npm and can contain your organization name as well
"author": "<YOU-OR-YOUR-ORGANIZATION>", // The author of this plugin
"version": "1.0.0", // Any Semver Value is ok, be sure to always use a value > of the one on your npm repository
"description": "<YOUR-AWESOME-PLUGIN-DESCRIPTION>", // Describe your plugin
"keywords": [
"leapp-plugin", // THIS IS MANDATORY!!!!
"AWS" // Any other meaningful tag
...
],
"leappPlugin": {
"supportedOS": [
"mac", "win", "linux" // You can insert one, two or all the values, you can also leave this tag blank to include all OSs
],
"supportedSessions": [
"awsIamRoleFederated", // Possible values are: any, aws, azure, awsIamRoleFederated, awsIamRoleChained, awsSsoRole, awsIamUser
"awsIamRoleChained",
"awsSsoRole"
...
]
},
...
}
Remember:
"keywords": [ "leapp-plugin" ]
is Mandatory to allow Leapp to recognize the plugin!
Open plugin-index.ts
and add a class for your plugin. plugin-index.ts is the entry point for your plugin.
E.g.
export { WebConsolePlugin } from "./web-console-plugin";
. We are declaring WebConsolePlugin as our plugin class.
You are done with plugin-index.ts
.
Create a new typescript class and extend AwsCredentialsPlugin
.
export class WebConsolePlugin extends AwsCredentialsPlugin { ... }
Note:
AwsCredentialsPlugin
is a class from Leapp that gives you access to temporary credentials for a given session.
Add 3 imports (usually the editor will do this step for you)
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";
Inside the class you define 2 properties and 1 method, it's as simple as that! Let's see:
get actionName(): string {
return "Open web console"; // Friendly Name of your plugin: will be used to show the action in the Leapp Menu and Leapp plugin List
}
get actionIcon(): string {
return "fa fa-globe"; // An icon for your plugin! Currently compatible with Font-Awesome 5+ icon tags.
}
Here you can find a list of compatible icons!
Now the main dish: the action method! Leapp will use this method to execute an action based on a session's temporary credentials set, in this case will use them to generate a link shortcut to open AWS web console for that specific session's role.
async applySessionAction(session: Session, credentials: any): Promise<void> { ... }
In this method you have access to 3 important variables:
-
session Leapp session the user clicked on, or selected in the Leapp CLI.
export class Session { sessionId: string; status: SessionStatus; startDateTime?: string; type: SessionType; sessionTokenExpiration: string; constructor(public sessionName: string, public region: string) { this.sessionId = uuid.v4(); this.status = SessionStatus.inactive; this.startDateTime = undefined; } expired(): boolean { if (this.startDateTime === undefined) { return false; } const currentTime = new Date().getTime(); const startTime = new Date(this.startDateTime).getTime(); return (currentTime - startTime) / 1000 > constants.sessionDuration; } }
-
credentials Credentials set for the session.
export interface CredentialsInfo { sessionToken: { aws_access_key_id: string; aws_secret_access_key: string; aws_session_token: string; region: string; } }
-
pluginEnvironment A set of methods to help you develop your plugin:
-
log
(message: string, level: PluginLogLevel, display: boolean): void
Log a custom message in Leapp or in the log fileargument 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
(url: string): any
Retrieve the content of an URL. Returns a promise for the URLargument type. description url string a valid HTTP URL to fetch from -
openExternalUrl
(url: string): void
Open an external URL in the default browserargument type description url string a valid HTTP URL to open in the default browser
-
Finally you can find the complete code reference for our example plugin here.
Use npm run build
. A complete project will be created inside the root folder.
Note: you can test your plugin before submission, by copying the output folder of
npm run build
inside~/.Leapp/plugins/
.
- Login to npm (you need to be registered on npm as a user or an organization) using
npm login
in the plugin folder. - Publish the plugin with
npm publish --access public
.
You can find examples of plugins for Leapp in the dedicated section of our documentation.
If you want a more detailed explanation of the plugin system please go to the dedicated section in our documentation.