Clisso (pronounced /ˈklIsoʊ/) allows you to retrieve temporary credentials for cloud platforms
by authenticating with an identity provider (IdP).
The following identity providers are currently supported:
The following cloud platforms are currently supported:
Clisso uses the SAML standard to authenticate users.
The easiest way to use Clisso is to download a pre-compiled binary for your platform. To do so, perform the following:
- Go to the latest release on the releases page.
- Download the ZIP file corresponding to your platform and architecture.
- Unzip the binary.
- Rename the binary using
mv clisso-<platform>-<arch> clisso. - Move the binary to a place under your path.
Clisso supports macOS, Linux and Windows.
To install Clisso using Homebrew, run the following commands:
brew tap allcloud-io/tools
brew install clisso
To update Clisso to the latest release, run the following command:
brew upgrade clisso
- Go
1.12or above - Git
- Make
To build Clisso from source, do the following:
# Get the source
git clone github.com/allcloud-io/clisso
# Build the binary
cd clisso
go build
# Install the binary in $GOPATH/bin
go install
# Clean up
go clean
A self-signed certificate may be created and used to sign the binary when building Clisso from source on a MacOS machine with Gatekeeper enabled. After installing Clisso, sign the binary:
codesign -f -s "Your Certificate Name" $GOPATH/bin/clisso
Clisso stores configuration in a file called .clisso.yaml under the user's home directory. You
may specify a different config file using the -c flag.
NOTE: It is recommended to use the
clissocommand to manage the config file, however you may also edit the file manually. The file is in YAML format. You may find a sample config file here.
Clisso has the following commands:
$ ./clisso
Usage:
clisso [command]
Available Commands:
apps Manage apps
completion Generate the autocompletion script for the specified shell
get Get temporary credentials for an app
help Help about any command
providers Manage providers
status Show active (non-expired) credentials
Flags:
-c, --config string config file (default is $HOME/.clisso.yaml)
-h, --help help for clisso
--log-level string set log level to trace, debug, info, warn, error, fatal or panic (default "info")
-v, --version version for clisso
Use "clisso [command] --help" for more information about a command.
In order to use Clisso you will have to configure at least one provider and one app. A provider represents an identity provider against which Clisso authenticates. An app represents an account on a cloud platform such as AWS, for which Clisso retrieves credentials.
To list the existing providers on Clisso, use the following command:
clisso providers ls
Following is a sample output:
okta-prod
onelogin-dev
onelogin-prod
To list the existing apps on Clisso, use the following command:
clisso apps ls
Following is a sample output:
dev-account
* prod-account
The app marked with an asterisk is selected.
To create a OneLogin identity provider, use the following command:
clisso providers create onelogin my-provider \
--client-id myid \
--client-secret mysecret \
--subdomain mycompany \
--username user@mycompany.com \
--region US \
--duration 14400 \
--arn arn:aws:iam::123456789012:role/Worker
The example above creates a OneLogin identity provider configuration for Clisso, with the name
my-provider.
The --client-id and --client-secret flags are OneLogin API credentials. You may follow the
instructions here to obtain them. OneLogin requires using static credentials even for
attempting authentication, and for that reason Clisso needs them. Please be sure to select
Authentication Only when generating the credentials. Higher-level permissions aren't used by
Clisso and will only pose a security risk when stored at a client machine. You might have to open
a ticket with your OneLogin administrator to obtain these credentials as administrator privileges
are required.
The --subdomain flag is the subdomain of your OneLogin account. You can see it in the URL when
logging in to OneLogin. For example, if you log in to OneLogin using mycompany.onelogin.com, use
--subdomain mycompany.
The --username flag is optional, and allows Clisso to always use the given value as the OneLogin
username when retrieving credentials for apps which use this provider. Omitting this flag will make
Clisso prompt for a username every time.
The --duration flag is optional. If specified, sessions will be assumed with the provided
duration, in seconds, instead of the default of 3600 (1 hour). Valid values are between 3600 and
43200 seconds. The max session duration has be equal to or lower than what is configured on
the role in AWS. If a longer session time is requested than what is configured on the AWS role,
Clisso will fallback to a duration of 3600. The default duration specified for the provider can be
overridden on a per-app basis (see below).
The --arn flag is optional. If specified, it will not prompt for a choice of roles presented
from the list of available AWS accounts/roles. This makes it easy to run clisso get my-app
and get the correct account/role.
To create an Okta identity provider, use the following command:
clisso providers create okta my-provider \
--base-url https://mycompany.okta.com \
--username user@mycompany.com \
--duration 14400
The example above creates an Okta identity provider configuration for Clisso, with the name
my-provider.
The --base-url flag is your Okta base URL. You can see it in the URL when logging in to Okta.
Please specify a full URL in one of the following formats:
https://your-subdomain.okta.comif you have an enterprise Okta account.https://your-subdomain.oktapreview.comif you have a developer Okta account.
The --username flag is optional, and allows Clisso to always use the given value as the Okta
username when retrieving credentials for apps which use this provider. Omitting this flag will make
Clisso prompt for a username every time.
The --duration flag is optional. If specified, sessions will be assumed with the provided
duration, in seconds, instead of the default of 3600 (1 hour). Valid values are between 3600 and
43200 seconds. The max session duration has be equal to or lower than what is configured on
the role in AWS. If a longer session time is requested than what is configured on the AWS role,
Clisso will fallback to a duration of 3600. The default duration specified for the provider can be
overridden on a per-app basis (see below).
Deleting providers using the clisso command isn't currently supported. To delete a provider,
remove its configuration from the config file.
To create a OneLogin app, use the following command:
clisso apps create onelogin my-app \
--provider my-provider \
--app-id 12345 \
--duration 3600
The example above creates a OneLogin app configuration for Clisso, with the name my-app.
The --provider flag is the name of a provider which already exists in the config file.
The --app-id flag is the OneLogin app ID. This ID can be retrieved using the OneLogin admin
interface or the OneLogin API. Unfortunately, the OneLogin API doesn't allow obtaining app IDs
without storing sensitive, high-level permissions on the client machine. For that reason we have to
manually configure the app ID for every app.
NOTE: The ID seen in the browser URL when visiting a OneLogin app as a user is NOT the app ID. Only a OneLogin administrator can obtain an app ID.
The --duration flag is optional and defaults to the value set at the provider level. Valid values
are between 3600 and 43200 seconds. Can be used to raise or lower the session duration for an
individual app. The max session duration has be equal to or lower than what is configured on
the role in AWS. The default maximum is 3600 seconds. If the requested duration exceeds the
configured maximum Clisso will fallback to 3600 seconds.
To create an Okta app, use the following command:
clisso apps create okta my-app \
--provider my-provider \
--url https://mycompany.okta.com/home/amazon_aws/xxxxxxxxxxxxxxxxxxxx/137 \
--duration 3600
The example above creates an Okta app configuration for Clisso, with the name my-app.
The --provider flag is the name of a provider which already exists in the config file.
The --url flag is the app's embed link. This can be retrieved as an Okta user by examining
the URL of an app on the Okta web UI. The same can also be retrieved as an administrator by
clicking an app in the Applications view. The embed link is on the General tab.
NOTE: An Okta embed link must not contain an HTTP query, only the base URL. For AWS apps, the link should end with
/137.
The --duration flag is optional and defaults to the value set at the provider level. Valid values
are between 3600 and 43200 seconds. Can be used to raise or lower the session duration for an
individual app. The max session duration has be equal to or lower than what is configured on
the role in AWS. The default maximum is 3600 seconds. If the requested duration exceeds the
configured maximum Clisso will fallback to 3600 seconds.
For deleting apps, use the following command:
clisso apps delete my-app
Deletion of an app will remove its configuration from the config file. You can also do it manually by editing the config file.
To obtain temporary credentials for an app, use the following command:
clisso get my-app
The example above will obtain credentials for an app named my-app. Type your credentials for the
relevant identity provider. If multi-factor authentication is enabled on your account, you will be
asked in addition for a one-time password.
By default, Clisso will store the credentials in the shared credentials file of the AWS CLI
with the app's name as the profile name. You can use the temporary credentials by specifying
the profile name as an argument to the AWS CLI (--profile my-profile), by setting the
AWS_PROFILE environment variable or by configuring any AWS SDK to use the profile.
To save the credentials to a custom file, use the --output flag with a custom path. For example:
clisso get my-app --output /path/to/credentials
To print the credentials to the shell instead of storing them in a file, use the --output environment flag. This
will output shell commands which can be pasted in any shell to use the credentials.
To select a specific MFA device by name instead of choosing from a list, use the -m flag. The
configuration field global.mfa-device may also be set.
AWS CLI v2 introduced the credential_process feature which allows you to use an external command to obtain temporal credentials.
Clisso can be used as a credential_process command by setting the --output credential_process flag. For example:
clisso get my-app --output credential_process
You can use this by adding the following to your ~/.aws/credentials file:
[my-app]
credential_process = clisso get my-app --output credential_processIMPORTANT: If
clisso get my-app --output credential_processprompts for any input, thecredential_processwill not work as expected. Make sure to configure Clisso to not prompt for any input (Store the password in the key chain, use push MFA).
Alternatively you can run the following command to configure all Apps for use with credential_process:
clisso cp configureThe AWS SDK does not cache any credentials obtained using credential_process. This means that every time you use the profile, Clisso will be called to obtain new credentials. If you want to cache the credentials, you can use the --cache flag. For example:
[my-app]
credential_process = clisso get my-app --output credential_process --cacheAlternatively you can set it in the ~/.clisso.yaml file:
global:
cache:
enable: trueDifferent processes on your system might continue using AWS Profiles configured for use with Clisso. To temporarily disable the credential_process functionality, you can use the clisso cp submenu. For example:
clisso cp disable # to disable
clisso cp enable # to enable
clisso cp status # to check the statusIf you disable the credential_process functionality, all refreshes will be disabled. While cached credentials will still be used, new credentials will not be fetched. This can be useful if you lock your computer with an active, e.g., VSCode session with CodeCommit. If you wouldn't disable the credential_process functionality, the VSCode would constantly trigger new credential requests to refresh the remote CodeCommit repository.
If you want to check the status programmatically, you can use the exit code of the clisso cp status command. If the exit code is 0, the credential_process functionality is enabled. If the exit code is 1, the credential_process functionality is disabled.
WARNING: Storing the password without having MFA enabled is a security risk. It allows anyone to assume your roles who has access to your computer.
Storing a password for a provider is as simple as running:
clisso providers passwd my-provider
You can select an app by using the following command:
clisso apps select my-app
You can get credentials for the currently-selected app by simply running clisso get, without
specifying an app name. The currently-selected app will have an asterisk near its name when listing
apps using clisso apps ls.
AWS recommends using regional STS endpoints instead of the default Global endpoint when requesting a token.
To use a regional endpoint, specify the region via the global.aws-region field in the config file. A per app configuration using apps.<app>.aws-region is also possible.
YubiKey Autodetection is available for the OneLogin provider. To enable this feature set the global.autodetect-yubikey field to true. Clisso will look at attached USB devices and automatically select the YubiKey as an MFA device if it is available. Only one YubiKey may be connected for this feature to work.
- No support for Okta applications with MFA enabled at the application level.
- Yubikey Autodetection is only available with the prebuilt binaries on these platforms:
- MacOS (ARM/x86)
- Linux (x86)
- Windows (x86)
Clisso logs to stderr by default. To enable more detailed logging, set the --log-level flag to debug or trace. With trace log level, sensitive information will be logged.
If you run into issues, you can create a trace log by setting the --log-level flag to trace. This will create a file called .clisso.log your home directory. You can alter the location of the log file by setting the --log-file flag. The below example will create a trace log in the current directory in
a file called trace.log.
clisso --log-level trace --log-file trace.log get my-app
Alternatively, you can configure logging via the config file. The below example will create a trace log in your home directory in a file called clisso.log.
global:
log:
level: trace
file: ~/clisso.logWhen attaching the log file to an issue, please make sure to remove any sensitive information.
dbus: couldn't determine address of session bus This behavior has been observed on Ubuntu 20.04 WSL.
Simply running sudo systemd-machine-id-setup gets you past the initial missing machine id setup.
failed to unlock correct collection '/org/freedesktop/secrets/collection/login',
The name org.freedesktop.secrets was not provided by any .service files Check that you have a working
keychain setup. On headless systems like WSL this might not be easy to archive. Installing gnome-keyring
along with the proper DBus setup is required. During tests adding the below to the ~/.bashrc on Ubuntu 20.04 WSL
was enough.
if [ "$DBUS_SESSION_BUS_ADDRESS" = "" ]; then
exec dbus-run-session -- bash;
else
eval $(echo "$(/lib/cryptsetup/askpass 'Password: ')" | gnome-keyring-daemon --unlock);
fiTODO
This code is released under the Mozilla Public License 2.0 License. Please see LICENSE and NOTICE for more details.
Copyright © 2017-2023 AllCloud
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
