Okta VSCode Extension

Okta-Explorer

Purpose

Provide Application Developers, Dev Ops Administrators and OIN Partners a way to sign up for an Okta developer account and manage their Okta applications from within Visual Studio Code, see https://code.visualstudio.com/.

Installation

• Bring up the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of VS Code.
• Type okta in the search box.
• Click install next to Okta Explorer.

Sign Up

• Bring up the Okta Explorer view by clicking on the Okta Explorer icon in the Activity Bar on the side of VSCode.
• Click the Sign Up button in the Okta Explorer view.
• A terminal is displayed which prompts for your first name, last name, email and country.
• Activate your account by clicking the link sent to your email.

If the sign up process is already complete when the Okta Explorer view is opened the applications view is shown automatically.

Create Application

• From the Okta Explorer view click the + next to the Applications tree node.
• Select an application type from the pick list.
• Type a name for the application and press enter.

View Application

• From the Okta Explorer view select the application you'd like to view. An editor is displayed showing the configuration of the selected application.

Edit Application

• From the Okta Explorer view select the application you'd like to edit. An editor is displayed showing the configuration of the selected application.
• Edit the configuration.
• Save the document.

Auto Save

Because you can let VSCode save after every x milliseconds or so or save when the editor loses focus or when the window loses focus, the state of the configuration file may not be valid when a save occurs which results in errors returned by the server. To avoid excessive calls to the server, and to avoid submitting invalid configurations, it may be desirable to disable Auto Save while editing application configurations in Okta-Explorer.

Personas

The Visual Studio Code extension targets three primary personas as its audience.

Dev Ops Administrators - coordinates the work between software and operation teams. They set up processes and tools to help teams work efficiently.

Application Developer - responsible for creating, developing and modifying source code for software applications. They design and implement software that fulfills use case scenarios defined by a project team.

Integration Application Developer (OIN Partners) - responsible for adding new integrations to Okta in their SaaS application for submission to the OIN.

User Stories

As a Dev Ops Administrator or Application Developer, I want to sign up for an Okta developer account.

As a Dev Ops Administrator or Application Developer, I want to create a new Okta application from within the Visual Studio Code integrated development environment.

As a Dev Ops Administrator or Application Developer, I want to review an applications configuration in json or yaml format from within the Visual Studio Code integrated development environment.

As a Dev Ops Administrator or Application Developer, I want to update an applications configuration by editing and saving its json or yaml file representation from within the Visual Studio Code integrated development environment.

As a Dev Ops Administrator or Application Developer, I want to delete an application from within the Visual Studio Code integrated development environment.

As an Application Developer, I want to create a new local application project that is automatically configured with Okta authentication from within the Visual Studio Code integrated development environment.

Visual Studio Code Contribution Points

To add custom user interface elements to Visual Studio Code, extension authors define a contributes node in package.json. For further information about Visual Studio Code contribution points, see https://code.visualstudio.com/api/references/contribution-points.

The following json segment shows the contributes node of the Okta Visual Studio Code Integration.

"contributes": {
    "viewsWelcome": [
      {
        "view": "oktaApplications",
        "contents": "To use Okta Explorer you'll need to sign up for a developer organization.\n[Sign up](https://github.com/bryanapellanes-okta/okta-vscode-extension/blob/HEAD/command:okta.signUp)\n"
      }
    ],
    "viewsContainers": {
      "activitybar": [
        {
          "id": "okta-explorer",
          "title": "Okta Explorer",
          "icon": "resources/OktaIcon.png"
        }
      ]
    },
    "views": {
      "okta-explorer": [
        {
          "id": "oktaApplications",
          "name": "Applications",
          "icon": "resources/applications.png",
          "contextualTitle": "Applications"
        }
      ]
    },
    "commands": [
      {
        "command": "okta.signUp",
        "title": "Okta Sign-Up"
      },
      {
        "command": "oktaApplications.openOrg",
        "title": "Open Admin Console",
        "icon": "resources/openbrowser.png"
      },
      {
        "command": "oktaApplications.add",
        "title": "Add Application",
        "icon": "resources/add.png"
      },
      {
        "command": "oktaApplications.reload",
        "title": "Reload",
        "icon": "resources/reload.png"
      },
      {
        "command": "oktaApplications.edit",
        "title": "Edit",
        "icon": "resources/edit.png"
      },
      {
        "command": "oktaApplications.delete",
        "title": "Delete",
        "icon": "resources/delete.png"
      }
    ],
    "menus": {
      "view/title": [
        {
          "command": "oktaApplications.reload",
          "when": "view == oktaApplications",
          "group": "navigation"
        }
      ],
      "view/item/context": [
        {
          "command": "oktaApplications.delete",
          "when": "view == oktaApplications && viewItem == application",
          "group": "inline"
        },
        {
          "command": "oktaApplications.add",
          "when": "view == oktaApplications && viewItem == applicationsHeader",
          "group": "inline"
        },
        {
          "command": "oktaApplications.openOrg",
          "when": "view == oktaApplications && viewItem == organization",
          "group": "inline"
        }
      ]
    }
  }

Architecture

The top level composition class is OktaExplorer which is composed of OktaTreeDataProvider , OktaSignUpProvider and OktaEditor. The following sections provide a brief description of these components and their purpose.

OktaTreeDataProvider

The OktaTreeDataProvider provides data that is displayed in the tree view in Visual Studio Code. It is an implementation of the interface TreeDataProvider provided by Visual Studio Code. Internally it uses an OktaDataProvider to make Okta API calls. See, https://github.com/bryanapellanes-okta/okta-vscode-extension/tree/v1_main/okta-explorer/src/classes/oktaTreeDataProvider.ts#L11.

OktaSignUpProvider

The OktaSignUpProvider is responsible for signing a user up for an Okta developer organization. It is composed of DotNetInfo, ExtensionConfig, ApiConfig, OktaDataProvider, OktaWizardInstaller , OktaTerminal and a Logger. See, https://github.com/bryanapellanes-okta/okta-vscode-extension/tree/v1_main/okta-explorer/src/classes/injectables/oktaSignUpProvider.ts#L20.

OktaEditor

The OktaEditor is responsible for displaying application configuration as editable yaml or json files which are ultimately synchronized with the backing Okta organization. It is composed of ExtensionConfig, SyncedDataCache, DataSyncProvider, WorkspaceFolderProvider, DataTemplateManager, Notifier and a Logger. See, https://github.com/bryanapellanes-okta/okta-vscode-extension/tree/v1_main/okta-explorer/src/classes/oktaEditor.ts#L25.

Composition Components

The following are the components that constitute the top level composition classes.

• DotNetInfo - helps to determine if dotnet is installed.

• ExtensionConfig - configuration settings for the Okta Visual Studio Code extension.

• ApiConfig - configuration for API client access to the Okta API.

• OktaDataProvider - provides client access to retrieve and update Okta data.

• OktaWizardInstaller - installer for the Okta wizard.

• Logger - logs activity.

• SyncedDataCache - a synchronized cache for data.

• DataSyncProvider - synchronizes changes made to a data cache.

• WorkspaceFolderProvider - provides a Visual Studio Code workspace folder.

• DataTemplateManager - manages data templates.

• Notifier - provides user notifications.

Custom Templates

In addition to the default templates included with the Okta VSCode Exension, custom templates can be loaded from the file system. When the pick list is presented to create a new application, custom templates are presented along with the default templates. For a custom template to be displayed it must be saved to the .okta/data-templates/application/ folder in the VSCode workspace. The file must contain either json or yaml of an application configuration:

label: {Label} for {OrgDomain}
signOnMode: OPENID_CONNECT
status: ACTIVE
credentials:
  oauthClient:
    token_endpoint_auth_method: client_secret_basic
name: oidc_client
settings:
    implicitAssignment: false
    oauthClient:
      application_type: web
      consent_method: REQUIRED
      grant_types:
        - authorization_code    
      post_logout_redirect_uris:
        - http://localhost:8080
      redirect_uris:
        - http://localhost:8080/authorization-code/callback
      response_types:
        - code

The value {Label} is replaced by the name entered when creating a new application and the value {OrgDomain} is replaced by the configured organization domain.

OnCreate

To facilitate project initialization, a command can be specified in an onCreate node of a custom template. When using onCreate the application data should be specified as the data node:

onCreate:
  command: dotnet new oktawebapp
data:
  label: {Label} for {OrgDomain}
  signOnMode: OPENID_CONNECT
  status: ACTIVE
  credentials:
    oauthClient:
      token_endpoint_auth_method: client_secret_basic
  name: oidc_client
  settings:
      implicitAssignment: false
      oauthClient:
        application_type: web
        consent_method: REQUIRED
        grant_types:
          - authorization_code    
        post_logout_redirect_uris:
          - http://localhost:8080
        redirect_uris:
          - http://localhost:8080/authorization-code/callback
        response_types:
          - code

When a template that has an onCreate node defined is used, the Okta VSCode Extension runs the specified command after creating the application in the Okta organization.

Dependency Injection

To aide in adherence to best practice and SOLID principles, Okta VSCode Extension uses InversifyJS for dependency injection and inversion of control. See binding definitions, https://github.com/bryanapellanes-okta/okta-vscode-extension/tree/v1_main/okta-explorer/src/containers/releaseContainer.ts#L48-L74.

References

• https://code.visualstudio.com/api/get-started/your-first-extension
• TypeScript Handbook
• InversifyJS