exactmike / oneshell

OneShell is a PowerShell Connection Manager for Office 365, Azure, and other Cloud services that support PowerShell connectivity

What is OneShell

A Connection Manager for PowerShell connections to cloud and on premises systems and services designed to be used interactively by administrators, consultants and developers.

Overview

OneShell to rule them all . . .

The world is messy - endpoints fail; connection methods vary; forests, tenants, and endpoints multiply; sessions go bad; credentials need updating.

OneShell provides a framework for uniform and reliable connection management to assist in your daily administration, automation, or development of solutions.

OneShell is a PowerShell module designed for administration of cloud and on premises services (specifically, but not only, Office 365 workloads and supporting on premises infrastructure) in a single PowerShell session via reliable and easily re-connectable remote PSsessions or other connection types to those systems. OneShell provides administrators with a framework which allows for automation of connection/re-connection to these systems for interactive administration or for integration with functions, scheduled tasks and/or long-running operations. OneShell also provides a rich set of functionality via additional functions and helper modules that can be used in your own automation scripts for provisioning, maintenance, or reporting.

OneShell's extensible ServiceType system currently supports the following system types (for each of which multiple, simultaneous connections are supported, avoiding cmdlet 'clobber' issues by using prefixing or invoke-command per session):

• Azure AD
• MSOnline (-msol cmdlets)
• Exchange Online
• Exchange On Premises (2010-2016)
• Exchange Compliance Center
• Exchange 2007 (untested)
• Active Directory Domain
• Active Directory Global Catalog (Forest)
• Skype for Business Online
• Windows PowerShell PSRemoting Servers (with optional x86 endpoint support)
• Azure AD Sync/Azure AD Connect Servers

The following additional ServiceTypes are in development (an earlier version of OneShell included each of these):

• Lotus Notes
• SQL Server Databases
• Azure AD RMS
• MigrationWiz/BitTitan
• OneShell is designed to be easily extensible - add your own service type and or make a request. What other system/service types do you want support for?

We hope to soon add support for SSH remoting and endpoints for heterogenous environments.

Key Features

• Extensible ServiceType configuration.

  You can add additional system types/service types usually without any modifications to OneShell code by adding a ServiceType json file to the ServiceTypes directory. See the ServiceTypes folder (or run Get-OneShellServiceTypeName) for the current supported types. Examine the individual .json files in ServiceTypes and/or run Get-OneShellServiceTypeDefinition to examing the Service Type definition objects in detail.

• 'Org' Profiles

  • Store General 'per organization' System/Service instances which can be shared among multiple administrators
  • Define endpoints and preferences
  • Each System/Service can be configured with multiple endpoints

• User Profiles

  • Store Administrative Credentials (specific to each administrator)
  • Map Credentials to services
  • Store AutoConnect and/or AutoImport settings per System/Service instance
  • Store Prefix setting per System/Service instance
  • Stores additional preferences per System/Service instance, such as preferred endpoint

• Automated Connectivity to administrative endpoints

  • With one command connects an administrator to all Systems/Services and re-connects on demand as well when sessions break
  • Connectivity functions are suitable to embed in your own automation scripts to ensure connectivity during long running operations

Getting Started

See GettingStarted.md

Contributing

Guidelines TBA . . . In the meantime, there are issues and to do items noted in ToDoKnownIssuesEtc.md

oneshell's Issues

add admin profile prefix override for pssession import based systems

add User profile folder and machine name editing to set-adminuserprofile

The psm1 uses powershell instead of pwsh

Just opening an issue for my pull request #12 , pwsh is the new name for powershell core and the name of the supported production binary on *nix systems. The new name should be embraced to make sure the module is not broken going forward.

Nice presentation at the summit BTW.

Implement ManagedConnections in OneShell

OneShell is a connection/session manager for Systems/Services that can be accessed via PowerShell. It uses Profiles to implement this functionality, managing the system/service definitions, endpoints, credentials, etc. Connections can be made by OneShell via PowerShell Remoting (eg. Exchange Online, Skype Online, etc.) or via 'Local Connect' (eg. AzureAD via Import-Module and Connect-AzureAD) or a combination of these 2 techniques.

Currently, OneShell's connection/session management is limited to the following features:

• auto connection to a user defined set of systems
• on demand connection to user defined system(s)
• auto grouping of sessions into session management groups for one to many management (eg. Invoke-Command -Session $SessionGroup).
• on demand testing of connection
• re-connection to one or more existing connections if needed (if testing shows the connection has failed)

The goal of this issue is to define implementation of these additional features:

• multiple connections to the same system (for parallel operations, background jobs, etc.)
• 'clean' disconnection of an existing connection where possible (depending on service type support)
• tracking of connections to service types to avoid or warn about potential conflicts (for example, connection operations that would clobber existing commands in the local PowerShell session)
• get all OneShell connections
• Improved session management groups
• Improved/Robust support for Prefixing with 'LocalConnect' systems.
  This is needed to manage imports of modules with command prefixing if the user requests it in their profile configuration or connect-oneshellsystem parameters. And to handle disconnection if the same module was previously imported for a different system.

Implementation Proposal Summary

Implementation will require new functions and new connection tracking mechanism(s). The proposed solution would include the following (more detail to follow below):

• Module variable ManagedConnections array to track each Connection
• New function Remove-OneShellSystemPSSession (would remove an imported session from being imported but not the session itself)
• New function Get-OneShellConnection (or Get-OneShellSystemConnection)
• Update function Import-OneShellSystemPSSession to update ManagedConnections entry(ies)
• New function Disconnect-OneShellSystem to manage the 'cleanes' disconnection possible for a given ServiceType and connection type (PS Remoting or LocalConnect).

Implementation Proposal Detail

$Script:ManagedConnections

• Array of PSCustomObject
• Attributes
  • ManagedConnectionID (Incremented Int)
  • Identity (of the System from the OrgProfile)
  • Name (of the system from the OrgProfile)
  • OrgProfileIdentity
  • OrgProfileName
  • UserProfileIdentity
  • UserProfileName
  • PSSessionName (null for LocalConnect)
  • PSSessionID (null for LocalConnect)
  • Imported (bool for whether the PSSession is imported locally or import-module was used)
  • ImportedModuleName (the auto/random module name PS assigns to imported session modules)
  • ConnectionType (LocalConnect|PSRemoting)
  • PrefixApplied (at import - might be null)
  • EndpointIdentity (might be null)
  • First/Default Connection?

Update function Import-OneShellSystemPSSession

It needs to update a ManagedConnections entry attributes ImportedModuleName, Imported, Prefix

New function Remove-OneShellSystemPSSession

It needs to remove an imported session/session module but leave the session running for later import or disconnection. In other words, it's not doing the job of Remove-PSSession. Instead, it is reversing Import-PSSession (or in OneShell's case Import-OneShellSystemPSSession).

New function Get-OneShellConnection

Parameter Sets

• all
• byIdentity
• byServiceType
• other?

New function Disconnect-OneShellSystem

Parameter Sets

• All
• Identity (all connections for specified system(s) or scoped to ConnectionID)
• ServiceType (all connections for a servicetype or scoped to ConnectionID)
• ConnectionID (specific connection(s))

Description

branches depending on ConnectionType (LocalConnect or PSremoting)

• PSRemoting steps
  • If imported, remove imported module
  • If disconnect command is defined in servicetype, run disconnect command in PSSession
  • Remove PSSession from local session and session management group(s)
• LocalConnect steps
  • If disconnect command is defined in servicetype, run disconnect command locally
  • if not, optionally warn user (if warning is defined in servicetype). This is because certain connections can persist even through module removal (see MSOnline module for an example).

Autocompleters for parameters for all the above functions

• for Identity to limit ConnectionIDs
• for ConnectionID to limit Identities
• for ServiceType to limit ConnectionIDs and Identities