Onica SSO Documentation - Release 6.3.1.dev21 Onica Group

Onica SSO Documentation
           Release 6.3.1.dev21

                 Onica Group

                     Aug 18, 2021

CONTENTS

1   What is Onica SSO?                                                                                                                                                                                      1
    1.1 New User Guide . . .       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    1
    1.2 Installation . . . . . .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    2
    1.3 Upgrading . . . . . .      .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    3
    1.4 Commands . . . . . .       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    4
    1.5 How To Documents .         .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    7
    1.6 FAQ/Troubleshooting        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   10
    1.7 Lab Accounts . . . . .     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   14

2   Developers Guide                                                                                                                                                                                       17
    2.1 Development Environment .              .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   17
    2.2 Commands . . . . . . . . .             .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   18
    2.3 Contribution Requirements              .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   19
    2.4 Release Process . . . . . . .          .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   21

3   Indices and tables                                                                                                                                                                                     23

                                                                                                                                                                                                            i

ii

CHAPTER

                                                                                                                   ONE

                                                                                   WHAT IS ONICA SSO?

The Onica SSO cli (sso ) allows users to log into multiple AWS accounts using SAML auth. It also allows
AWS Console access using sso console.

1.1 New User Guide

Welcome to the Onica SSO new users guide. Below you will find the steps to getting started with Onica SSO, what do
to next, and reference material if you want to know more about how it works.

1.1.1 Getting Started

   1. Join the Onica SSO Yammer Community.
   2. If you have not done so already, install Onica SSO. It is recommended to install the standalone release.
   3. If you have not received a YubiKey yet, ask your direct manager how to get one. If you are in one on Onica’s
      offices, chances are we will have one in stock. If you are not in one of the offices, you should have received one
      with your laptop.
   4. Post a request in the Onica SSO Yammer Community to receive your Onica SSO credentials.
   5. Insert your YubiKey into your laptop and run init | sso-init to initialize your CLI. This will rotate your credentials
      making the ones sent to you no longer valid, register your YubiKey as an MFA device for your IAM user, and
      register your YubiKey for Onica SSO FIDO2 authentication.

1.1.2 Whats Next?

Important: Creation of individual lab accounts has been suspended indefinably. This means that step 1 can’t be
completed at this time.

   1. Create a lab account.
   2. Login to your lab account.
   3. Open the AWS console for your lab account.
   4. List the other accounts you can access.

                                                                                                                          1

Onica SSO Documentation, Release 6.3.1.dev21

1.1.3 Reference Articles

You do not need to read these. They are only provided for more information information about how Onica SSO works.
     • All account access is given by assuming roles.
     • When logging into an account, Onica SSO outputs the credentials as environment variables or, saves them to
       the credentials file. These are better explained in the awscli documentation which shows precedence. This
       precedence is also used by boto, aws-sdk, etc.

1.2 Installation

Important: If you previously used the pipsi version of Onica SSO, it MUST be uninstalled before using the stan-
dalone version. It can be uninstalled using pipsi uninstall onica-sso

Note:   If not using the system standard shell or profile, the sso */ sso-* commands may not work.           See
FAQ/Troubleshooting for adding sso */sso-* aliases and tab completion support to a terminal profile.

1.2.1 macOS (pkg)

macOS download
    1. Copy and paste the following into a terminal and press enter:

       bash -c 'BUCKET="https://common-onica-sso-cli.s3.amazonaws.com"; \
               PKG=onica-sso-$(curl ${BUCKET}/stable.version).pkg; \
               mkdir -p /tmp/onica-sso; \
               curl -o /tmp/onica-sso/${PKG} ${BUCKET}/${PKG}; \
               sudo installer -allowUntrusted -verboseR -pkg /tmp/onica-sso/${PKG} -target␣
        ˓→/; \

               rm -rf /tmp/onica-sso'

    2. Close all existing terminal windows and reopen.

1.2.2 Windows (msi)

Windows download

Note: Windows 10 version 1903 or greater is required.

    1. Copy and paste the following into a PowerShell terminal and press enter:

       $LATESTSSO = (Invoke-RestMethod -URI https://common-onica-sso-cli.s3.amazonaws.com/
        ˓→stable.version).Trim()

       (New-Object System.Net.WebClient).DownloadFile("https://common-onica-sso-cli.s3.
        ˓→amazonaws.com/onica-sso-$LATESTSSO.msi", "$HOME\Downloads\onica-sso-$LATESTSSO.msi

        ˓→")

       msiexec /i "$HOME\Downloads\onica-sso-$LATESTSSO.msi" /qb

2                                                                                 Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

   2. Close all existing terminal/PowerShell windows and reopen.
            If you see a “execution of scripts is disabled on this system” error, See the PowerShell note in the FAQ
   3. (Optional) Enable Windows Subsystem for Linux Support:
            First, ensure onica-sso is working properly in PowerShell (e.g. sso list accounts displays a list
            of available accounts). Then execute the following in your Ubuntu WSL terminal:

            sudo apt update && sudo apt install dos2unix
            if ! grep 'onica-sso.exe shell-init' ~/.bashrc > /dev/null 2>&1; then echo
             ˓→'eval "$(onica-sso.exe shell-init bash --wsl | dos2unix)"' >> ~/.bashrc;␣

             ˓→fi

            source ~/.bashrc

1.2.3 Debian / Ubuntu (deb)

Linux download

Note: It is recommended to use sudo apt install ./onica-sso... when installing from the .deb installer.
Installing from the Software Install GUI may not setup Tab Completion and/or sso aliases.

   1. Copy and paste the following into a terminal and press enter:

      bash -c 'BUCKET="https://common-onica-sso-cli.s3.amazonaws.com"; \
              DEB=onica-sso-$(curl ${BUCKET}/stable.version).deb; \
              mkdir -p /tmp/onica-sso; \
              curl -o /tmp/onica-sso/${DEB} "$BUCKET/${DEB}"; \
              sudo apt install /tmp/onica-sso/${DEB} -y; \
              rm -rf /tmp/onica-sso'

   2. Close all existing terminal windows and reopen.

1.2.4 pipsi / pip

While it is still possible to install Onica SSO with pipsi or pip, it is highly recommended not to do so. If you encounter
any issues with a pipsi/pip install of Onica SSO, please use one of the install methods provided above before requesting
assistance.
Information on how to perform an pipsi install and upgrade it can be found on the Legacy Install Methods page.

1.3 Upgrading

Follow the install steps for macOS (pkg), Windows (msi), Debian / Ubuntu (deb).

1.3. Upgrading                                                                                                          3

Onica SSO Documentation, Release 6.3.1.dev21

1.4 Commands

Common Options

These are options that are available on all commands.

--verbose            Print verbose logs to the terminal.
-h, --help           Show the command's help message and exit.

Tab Completion

Note: For full tab completion support the sso * command aliases must be used. The sso-* aliased commands do
support all tab completion functionality.

Tab completion is supported for bash and zsh. All command names and options can be autocompleted. Option values
that provide a choice can be autocompleted. Some commands even support completion of argument values (noted in
the documentation for the command).
This should be automatically configured on install for macOS (bash & zsh) and Debian/Ubuntu (bash). To manually
setup tab completion, see the table below for the correct entries.

Important:   In the Entry, you must replace ${version} with the correctly formatted Onica SSO version
(${major}-${minor}-${patch}). If the output of sso --version is 6.0.0, ${version} should be replaced
with 6-0-0.

    Operating     Shell File             Entry
    System
    De-           bash ~/.bashrc    source /usr/share/ onica-sso/completions/
    bian/Ubuntu                     bash_completion.sh
    De-           zsh ~/.zshrc      source /usr/share/ onica-sso/completions/ zsh_completion.
    bian/Ubuntu                     sh
    macOS         bash ~/.          source /usr/local/bin/ onica-sso-${version}/ onica_sso/
                       bash_profile completions/ bash_completion.sh
    macOS         zsh ~/.zshrc      source /usr/local/bin/ onica-sso-${version}/ onica_sso/
                                    completions/ zsh_completion.sh

1.4.1 --version

Display the version of Onica SSO and client type.
This cannot be used from a subcommand.
The client type relates to how the client was installed. It can be either standalone or pipsi as those are the only two
install methods outlined in the documentation. This is helpful when debugging errors or determining how to install
updates.

4                                                                               Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

Example

$ sso --version

Onica SSO (onica-sso) version 0.0.0
Client type: standalone

1.4.2 docs

1.4.3 console | sso-console

1.4.4 create lab account | sso-create-lab

Important: Creation of individual lab accounts has been suspended indefinably. Running this command will result
in an error.

1.4. Commands                                                                                                5

Onica SSO Documentation, Release 6.3.1.dev21

1.4.5 create lab dns | sso-enable-dns

1.4.6 create project-lab account | sso-create-project-lab

1.4.7 create sso-role

1.4.8 create user mfa-device

1.4.9 delete user mfa-device

1.4.10 get account alias | sso-account

1.4.11 get account info | sso-get-account-info

1.4.12 get mfa code | sso-mfa

1.4.13 get user keypair

1.4.14 get user name

1.4.15 init | sso-init

1.4.16 list

1.4.17 list accounts | sso-list

1.4.18 login | sso-login

1.4.19 multi-login

1.4.20 relogin | sso-relogin

1.4.21 rotate access-key | sso-rotate-key

1.4.22 rotate mfa-device | sso-rotate-mfa

1.4.23 share account | sso-share-account

1.4.24 shell-init

1.4.25 unshare account | sso-unshare-account

1.4.26 update

1.4.27 yubikey *

Exposes the embedded ykman CLI so you don’t have to install it to manage your YubiKey.
Full documentation can be found on YubiKey’s support site.

6                                                                           Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

Usage

sso yubikey [OPTIONS] COMMAND [ARGS]...

Options

Note: Subcommands of yubikey do not include the Common Options.

-v, --version
-d, --device SERIAL
-l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                Enable logging at given verbosity level.
--log-file FILE                 Write logs to the given FILE instead of
                                standard error; ignored unless --log-level
                                is also set.
-r, --reader NAME               Use an external smart card reader.
                                Conflicts with --device and list.
-h, --help                      Show this message and exit.

Commands

config    Enable/Disable applications.
fido      Manage FIDO applications.
info      Show general information.
list      List connected YubiKeys.
mode      Manage connection modes (USB Interfaces).
oath      Manage OATH Application.
openpgp   Manage OpenPGP Application.
otp       Manage OTP Application.
piv       Manage PIV Application.

Example

sso yubikey list --serials
sso yubikey --device 0123456 info

1.5 How To Documents

1.5.1 Adding An Account to Onica SSO

Customer Instructions

A PDF walkthrough of the stack deployment w/ screenshots is available on Box: How to Add AWS Account to SSO

1.5. How To Documents                                                                                         7

Onica SSO Documentation, Release 6.3.1.dev21

Internal Instructions

After the CFN stack has been deployed, SSO admins can add the necessary DynamoDB entry following the “Within
the sturdy-internal Account” instructions in the Add AWS Account to SSO document on Confluence.

1.5.2 YubiKey Setup

Transitioning from Smartphone TOTP

Prerequisites

    • Onica SSO installed and configured
    • smartphone registered as the current MFA device
    • YubiKey series 5 or newer

Process

    1. Insert the YubiKey into an available USB port.
    2. Open a terminal.
    3. Execute sso rotate mfa-device. This should prompt you to enter a TOTP code.
    4. Your TOTP MFA device will automatically be transferred to the YubiKey with no user interaction required.
    5. You will be prompted to Touch your YubiKey.... After doing so, the YubiKey will be register to you for
       FIDO2 authentication.

Transitioning from Legacy YubiKey Support

If you were an early adopter to using YubiKeys, you will still need to rotate your MFA to update how its stored on the
key and add support for FIDO2.

Prerequisites

    • Onica SSO installed and configured
    • YubiKey series 5 or newer that is already register with legacy YubiKey support

Process

    1. Insert the YubiKey into an available USB port.
    2. Open a terminal.
    3. Execute sso rotate mfa-device. This should prompt you to Touch your YubiKey... to retrieve a TOTP
       code.
    4. You will be prompted to Touch your YubiKey... again. After doing so, the YubiKey will be register to you
       for FIDO2 authentication and TOTP will be updated.

8                                                                              Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

1.5.3 Setup a New Workstation

Important: This guide applies to existing users of Onica SSO only and requires a valid MFA device that is already
registered.

While this guide is targeted at setting up a new workstation, the same steps can be applied to setup Onica SSO on a
secondary workstation.

Prerequisite

    • secure intermediary storage location for credentials (e.g. LastPass)
    • a valid, working MFA device associated with the credentials

Process

Origin Workstation

The initial workstation setup with Onica SSO that init | sso-init was first run on will be refereed to as the Origin
Workstation.
   1. Run the get user keypair command.

$ sso get user keypair
onica-sso: AWS credentials for user:
{
    "aws_access_key_id": "REDACTED",
    "aws_secret_access_key": "REDACTED"
}

   2. Store the output aws_access_key_id & aws_secret_access_key in a secure, encrypted location for trans-
      portation.

Destination Workstation

The new (or secondary) workstation to setup Onica SSO on.
   1. Install Onica SSO on the Destination Workstation.
   2. Retrieve the credentials that were output on the Origin Workstation.
   3. Run the init | sso-init command with the --store-only option. This will verify the credentials and your MFA
      device before storing them on your workstation.

$ sso init --store-only
onica-sso: This process will validate & store your existing IAM credentials in the␣
 ˓→workstation keychain.

onica-sso: This will not setup your MFA (you'll need your current working MFA to␣
 ˓→validate your credentials).

onica-sso: This option should NOT be used during initial account provisioning.
Proceed? [y/N]: y
Please enter your IAM access key: REDACTED
                                                                                                (continues on next page)

1.5. How To Documents                                                                                                 9

Onica SSO Documentation, Release 6.3.1.dev21

                                                                                               (continued from previous page)
Please enter your IAM secret access key:
onica-sso: Storing access key "REDACTED" to keyring...
onica-sso: Successfully stored access key in keyring!
onica-sso: Successfully completed initialization!

 Attention: If you think your credentials could have been compromised during any step in the process or they were
 not stored in a secure, encrypted location for transportation you can get a new set of credentials after they have been
 stored on the Destination Workstation.
 This can be done with the rotate access-key | sso-rotate-key command.

1.5.4 Credential Storage / Rotation

     1. Close/reopen terminal windows (to enable shell-init configuration performed in Setup)
     2. Execute sso init to store your SSO credentials in the system keychain and setup your MFA.
           • On subsequent (i.e. non-initial-setup) installs, add the --store-only option to skip MFA setup and SSO
             credential rotation.

1.5.5 Extract Keys

To extract your AWS Access Key and Secret Key run the “get user keypair” command.

1.6 FAQ/Troubleshooting

1.6.1 Lost Device

Note: Please report the loss of any MFA device or laptop immediately so that proper actions can be taken to revoke
access from those devices.

YubiKey

     1. Report the device as lost.
     2. Request a new YubiKey from your direct manager.
     3. Download the Google Authenticator app on your smartphone.
     4. Post a request on the Onica SSO Yammer Community for someone to deactivate your MFA device. This must
        be accompanied by proof of identity.
     5. After MFA has been reset, use sso rotate mfa-device to register your smartphone as an MFA device. This
        is only valid for up to 14 days.
     6. Once your new YubiKey has arrived, insert it into your computer and use sso rotate mfa-device again to
        register the new device.

10                                                                                Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

Smartphone

 Warning: This only applies if you are currently using smartphone TOTP for MFA. This option is deprecated and
 should only be used when waiting for a replacement YubiKey.

   1. Report the device as lost.
   2. Download the Google Authenticator app on your new smartphone.
   3. Post a request on the Onica SSO Yammer Community for someone to deactivate your MFA device. This must
      be accompanied by proof of identity.
   4. After MFA has been reset, use sso rotate mfa-device to register your smartphone as an MFA device.

1.6.2 Install / Update Errors

MSI Install Fails

   1. Uninstall any previous installs of onica-sso and try to install again.
   2. With PowerShell, run Start-Process notepad $PROFILE and remove any lines containing onica-sso
      shell-init then try to install again.
   3. If both of the above fail, use the following command from the directory containing the installer to gen-
      erate a log file to provide with your support request - msiexec /i onica-sso-installer.msi /l*v
      onica-sso-installer.logs

1.6.3 Runtime Errors

OS Independent

sso /sso- commands are not found

This can occur if you are not using the systems standard shell/profile. The install process modifies the global or user
profile depending on OS to add these aliases and enable tab completion. Add the following, OS and shell appropri-
ate, line to your non-standard profile and reload your shell. For more information about using shell-init, refer to the
command’s documentation.
macOS / Debian / Linux:

eval "$(onica-sso shell-init bash)"

Windows:

onica-sso shell-init powershell | iex

1.6. FAQ/Troubleshooting                                                                                            11

Onica SSO Documentation, Release 6.3.1.dev21

ykman.descriptor.FailedOpeningDeviceException

This error occurs when a Yubikey can’t be communicated with properly. It can be caused by many different issues.
Some of which can be specific to the system it’s connected to.

Example

$ sso login 
onica-sso: Please touch your YubiKey...
Traceback (most recent call last):
  File "onica_sso/cli.py", line 102, in main
  File "site-packages/click/core.py", line 717, in main
  File "onica_sso/resources/sso_click.py", line 33, in invoke
  File "site-packages/click/core.py", line 1137, in invoke
  File "site-packages/click/core.py", line 956, in invoke
  File "site-packages/click/core.py", line 555, in invoke
  File "site-packages/click/decorators.py", line 17, in new_func
  File "onica_sso/commands/login.py", line 349, in login
  File "onica_sso/context.py", line 333, in create_credential_payload
  File "onica_sso/context.py", line 233, in get_mfa_code
  File "onica_sso/resources/sso_yubikey.py", line 358, in get_oath_code
  File "onica_sso/resources/sso_yubikey.py", line 232, in oath
  File "site-packages/ykman/descriptor.py", line 116, in open_device
ykman.descriptor.FailedOpeningDeviceException

Possible Solutions

Note: Due to the nature of this error, there is no single cause for it. This also means that there is no single solution
that will fix the issue for everyone.

     • close all terminals, open a new terminal, and try again.
     • Ensure the Yubikey is connected directly to a USB port, not using a dongle.
     • Try a different USB port.
     • Unplug the Yubikey, plug it back in, wait for the lights on it to stop flashing, and try again.
     • Reboot.
     • There is an issue currently open in the library being used (Yubico/yubikey-manager#35) where some
       users/Yubico have identified a workaround that has worked in some cases.
     • Some users have had success disabling then enabling modes of the Yubikey using the following commands
       (optionally, ykman can be installed and used in place of the copy built into Onica SSO).

       $   sso   yubikey   mode f
       $   sso   yubikey   --log-level DEBUG oath list
       $   sso   yubikey   mode o+f+c
       $   sso   yubikey   config usb --enable-all

12                                                                                  Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

    • For macOS, some users have had success giving their terminal application Input Monitoring permissions in
      security settings and restarting the terminal. Others users have never had this enabled and have not encountered
      this error so it may have no effect.

Important: A Yubikey working for other authentication (e.g. Active Directory or LastPass) does not mean that it will
or should work with Onica SSO. This form of authentication uses an interface that mimics a keyboard typing when
touching the Yubikey and requires no communication from the system to the Yubikey itself.
The interfaces used by Onica SSO are for more complex authentication standards that require bidirectional communi-
cation between the Yubikey and the system it’s connected to.

PowerShell

execution of scripts is disabled on this system

Getting a execution of scripts is disabled on this system error on Windows when opening PowerShell?
As an Administrator, execute Set-ExecutionPolicy RemoteSigned

onica-sso : The term ‘onica-sso’ is not recognized. . .

onica-sso :      The term 'onica-sso' is not recognized as the name of a... when opening a Power-
Shell window:
   1. If using the standalone version, ensure that it is in-fact installed.
   2. Check the output of Write-Host $env:PATH to ensure that the install location is added. See if pipsi section for
      how to modify the environment variable or if using the standalone version, re-running the installer MSI should
      fix this.
   3. If onica-sso was uninstalled, run Start-Process notepad $PROFILE and remove any lines containing
      onica-sso shell-init.

Python

Could not find platform independent libraries. . .

Seeing errors like Could not find platform independent libraries  and/or Could not
find platform dependent libraries     and/or   Consider setting $PYTHONHOME to
[:] and/or Fatal Python error: initfsencoding: unable to load the
file system codec and/or ModuleNotFoundError: No module named 'encodings'?
This typically indicates that the Python environment backing your onica-sso and/or keyring installation is now broken
(e.g. a new Python version installed by a homebrew update). Fix it by uninstalling (pipsi uninstall keyring;
pipsi uninstall onica-sso) and then re-install (setup step 3 above).

1.6. FAQ/Troubleshooting                                                                                           13

Onica SSO Documentation, Release 6.3.1.dev21

1.6.4 What is the difference between sso and onica-sso

onica-sso is the name of the application. sso is the alias used to properly execute all actions/commands made available
via the onica-sso application. All actions/commands made available via the onica-sso application are available through
the sso alias.
The sso alias is needed to allow the output of some commands to make modification to the shell/terminal session being
used to run it. Without this, many actions/commands of the onica-sso application are handicapped or rendered unusable.
For this reason, onica-sso  should never be used directly other than with the shell-init command.

1.6.5 Unexpected Behavior

YubiKey is not Detected

This can be caused by a few different things depending on OS and some that are not OS dependent. The first step taken
should be to restart the computer.

Debian / Ubuntu

     1. ensure that pcscd is installed
     2. try restarting the pcscd socket with systemctl restart pcscd.socket

1.6.6 Providing Proof of Identity

To validate your identity, please include two of the following with any request that requires proof.
Each list item counts as one proof even if multiple from the same list item are provided. This is due to the level of
authentication required to provide each item and the likelihood of each item to be compromised at the same time.
      • Yammer post, Teams message, or email
      • Video call
      • Video recording where the request is stated, the date is shown, and a form of government or company issued
        identification is shown. This can be sent in a Teams message to the Engineer that acknowledges the Yammer
        post.
      • Present the request in person

1.7 Lab Accounts

Important: Creation of individual lab accounts has been suspended indefinably.

Note: Lab account can still be created but, it requires written approval from the head of a business unit.

14                                                                               Chapter 1. What is Onica SSO?

Onica SSO Documentation, Release 6.3.1.dev21

1.7.1 What’s a Lab Account?

A lab account is an AWS account used internally for development, training, or demonstration purposes. A lab account
should never contain production workload or any data that you can’t lose. While these accounts are “stable” (i.e. they
won’t just disappear), they also aren’t permanent.

1.7.2 What’s an Individual Lab Account?

Important: Creation of individual lab accounts has been suspended indefinably.

A individual lab account is assigned to an Onica employee, without association to a specific project. An individual
lab account can be created by each employee on their own, as soon as they have access to the SSO tool. A brand-new
account is created for each employee upon request. Each employee can only have one individual lab account. Individual
lab accounts are only destroyed upon termination of employment. Usage on individual lab accounts is visible to each
employee’s manager and business unit leader. It is incumbent on managers to track AWS usage across the individual
accounts for their teams. Employees do not need to seek reimbursement or complete expense reports for this usage; it’s
completely automated. All usage is charged to the appropriate BU’s COGS, based on the employee’s business unit.

1.7.3 What’s a Project Lab Account?

A project lab account is assigned to a single project, without association to a specific employee. A project lab account
can only be created by specially entitled individuals (specifically, project managers, business unit leaders, practice
leaders). Each project account must be tied to a Financial Force project. Project lab accounts are terminated upon
completion of the project. The usage on project lab accounts is reported to and monitored by the individual who
created the account (typically should be the project manager, for this reason). While the usage charges on project lab
accounts is automatically paid, the resulting expenses are not automatically billed to customers. Project managers must
determine if the usage is billable, and if it is, arrange to have the charges invoiced. All uninvoiced usage is charged to
project COGS.

1.7.4 When Should I Use an Individual vs Project Lab Account?

An Individual Account should be used for training, exploring a new service, or other types of professional devel-
opment. No persistent workloads should be deployed to individual accounts (i.e not the place to host your website).
Individual accounts that exceed $100/month of usage will be reviewed.
A Project Lab Account is more flexible and should be used for all development associated with a project (unless the
customer has provided an account for such purposes). Project accounts that exceed $500/month will be reviewed.

1.7.5 Who can Access Each Lab Account?

The person who created the account is the only person who can initially access the account. That person can then share
the account w/ additional users via the SSO command line. Both individual and project accounts can be shared, but
the account owner is responsible to monitor excessive spend on any account they share. If you share a project account
with another user who also has access to create/manage project accounts, they can also further share/un-share.
SSO admins can access all lab accounts for administrative purposes. Additionally, there are two roles deployed to each
account - one is for SSO and the other is for monitoring of usage w/ automated tools such as Cloud Custodian and other
tools (removing either will result in deletion of the account).

1.7. Lab Accounts                                                                                                      15

Onica SSO Documentation, Release 6.3.1.dev21

1.7.6 How do I Login to Lab Accounts?

You must use the SSO command line to create, manage, and login to lab accounts. The SSO command line supports
access to the AWS console after a command-line login.

16                                                                       Chapter 1. What is Onica SSO?

CHAPTER

                                                                                                         TWO

                                                                              DEVELOPERS GUIDE

The content covered in this section is intended for developers of Onica SSO. Those that support Onica SSO may also
find some of the commands in this section useful.
    • Development Environment
    • Commands
    • Contribution Requirements
    • Release Process

2.1 Development Environment

Important: The development environment requires a dedicated set of credentials to use.

The development environment is deployed across platcorp-payer (Route 53, IAM, server, ses) and platcorp-lab (Dy-
namoDB Tables). These accounts can be used to test new server and client features that should not be run in the
production environment.

2.1.1 Usage

Note: To initialize credentials for the dev environment, use sso init --dev. This requires dedicated credentials.

The client can be directed to use the dev environment by supplying the -D, --dev flag with any command or setting
the ONICA_SSO_DEV environment variable to any value.
This will use the onica-sso-dev credentials in your keyring. There is also a message printed to your terminal for
each command executed in the dev environment for visibility.

                                                                                                               17

Onica SSO Documentation, Release 6.3.1.dev21

2.1.2 Python Virtual Environment

This project uses pipenv to create Python virtual environment. This must be installed on your system before setting
up your dev environment.
With pipenv installed, run make sync to setup your development environment. This will create all the requred virtual
environment to work on Onica SSO. The virtual environment will install Onica SSO as editable meaning as you make
changes to the code of your local clone, it will be reflected in all the virtual environments.

pre-commit

pre-commit is configured for this project to help developers follow the coding style. If you used make sync to setup
your environment, it is already setup for you. If not, you can run pipenv run pre-commit install to install the
pre-commit hooks.
You can also run pipenv run pre-commit run --all-files at any time to manually trigger these hooks.

2.2 Commands

Developer Options

These are options that are available on all commands but, are hidden from the help menu. Their intended use is for
development or debugging complex errors.

--debug              Print all debug logs to the terminal. These logs WILL
                     include credentials and secrets that should not be shared.
-D, --dev            Run command against the dev environment.

The --debug option displays boto3, botocore, and Onica SSO debug logs. This will contain secrets that should not be
shared so use with caution. If requesting a user to send debug logs, be sure to also instruct them to rotate their access
key and potentially MFA device (if debugging a command that creates a new MFA device) afterward.

Environment Variables

The --debug, --dev, and --verbose options can be enabled for the entirety of the shell session by exporting select
environment variables.

                                        Environment Variable        Option
                                        ONICA_SSO_DEBUG             --debug
                                        ONICA_SSO_DEV               --dev
                                        ONICA_SSO_VERBOSE           --verbose

18                                                                                  Chapter 2. Developers Guide

Onica SSO Documentation, Release 6.3.1.dev21

2.2.1 delete user access-key

2.2.2 delete user keypair

2.2.3 list accounts

Developer Options

--no-output           Intended to only be used when invoked from another
                      command to suppress output.

The --no-output option is passed to the command when invoked from one of the commands that utilize the locally
cached account list.
See list accounts | sso-list for full documentation.

2.2.4 update

Developer Options

--update-endpoint          Endpoint that returns the stable version.

--update-endpoint can be added to the command entry to subscribe to a different update stream or check a different
endpoint for updates during development.
See update for full documentation.

2.3 Contribution Requirements

2.3.1 Branch Requirements

Branches must start with one of the following prefixes (e.g. /). This is due to how
labels are applied to PRs. If the branch does not meet the requirement, any PRs from it will be blocked from being
merged.
bug | bugfix | fix | hotfix The branch contains a fix for a big.
feature | feat The branch contains a new feature or enhancement to an existing feature.
docs | documentation The branch only contains updates to documentation.
maintain | maint | maintenance The branch does not contain changes to the project itself to is aimed at maintaining
     the repo, CI/CD, or testing infrastructure. (e.g. README, GitHub action, integration test infrastructure)
release Reserved for maintainers to prepare for the release of a new version.

2.3. Contribution Requirements                                                                                  19

Onica SSO Documentation, Release 6.3.1.dev21

2.3.2 Documentation Requirements

Docstrings

In general, we loosely follow the Google Python Style Guide for Comments and Docstrings.
We use the napoleon extension for Sphinx to parse docstrings. Napoleon provides an Example Google Style Python
Docstring that can be referenced.

reStructuredText Formatting

In general, we loosely follow the Python Style Guide for documentation.

Note: Not all documentation pages follow this yet. If the page you are updating deviates from this format, adapt to
the format of the page.

Headings

Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at
least as long as the text.
     1. # with overline, for h1 (generally only one per file, at the top of the file)
     2. * with overline, for h2
     3. =, for h3
     4. -, for h4
     5. ^, for h5
     6. ", for h6
h1 and h2 should have two blank lines separating them from sections with headings of the same level or higher.
A ‘’rubric” directive can be used to create a non-indexed heading.

Example

#########
Heading 1
#########

*********
Heading 2
*********

Heading 3
=========

Heading 4
---------
                                                                                                    (continues on next page)

20                                                                                      Chapter 2. Developers Guide

Onica SSO Documentation, Release 6.3.1.dev21

                                                                                              (continued from previous page)

Heading 5
^^^^^^^^^

Heading 6
"""""""""

.. rubric:: Non-indexed Heading

*********
Heading 2
*********

Heading 3
=========

2.3.3 PR Requirements

In order for a PR to be merged it must be passing all checks and be approved by at least one maintainer. Some of the
checks can be run locally using make lint and make test.
To be considered for approval, the PR must meet the following requirements.
    • Title must be a brief explanation of what was done in the PR (think commit message).
    • A summary of was done.
    • Explain why this change is needed.
    • Detail the changes that were made (think CHANGELOG).
    • Screenshot if applicable.
    • Include tests for any new features or changes to existing features. (unit tests and integration tests depending on
      the nature of the change)
    • Documentation was updated for any new feature or changes to existing features.

2.4 Release Process

   1. Create a branch for the release (e.g. release/vx.x.x).
   2. Make any last minute changes as needed.
   3. Push the release branch to GitHub.
   4. Open a PR and label it with release.
   5. Wait for all check to pass and artifacts to be built.
   6. Validate functionality of the artifacts (installers).
   7. Once the PR as been approved, merge it into master.
   8. Create a tag for the release on the master branch either manually or through the releases interface when publish-
      ing the release.

2.4. Release Process                                                                                                    21

Onica SSO Documentation, Release 6.3.1.dev21

     9. Wait for all checks on the master branch to complete, mainly the Release Drafter.
 10. In the releases section of the GitHub repo, edit the release draft that was created by the Release Drafter action.
     • Select or create the appropriate tag for the new version (e.g. v1.2.3).
     • Update the title to match the tag.
     • Modify the description of the release as needed.
     • Mark the release as a pre-release if applicable (alpha, beta, release candidate, etc).
 11. Publish the release.
An action will be triggered to build the final installers, upload them to S3, and update the URL shortener DDB table.

22                                                                                    Chapter 2. Developers Guide

CHAPTER

                         THREE

             INDICES AND TABLES

• genindex
• modindex
• search

                              23