osiam / shell

A Shell for Osiam

OSIAM - Open Source Identity and Access Management

Active development of this project has stopped.

OSIAM is a secure identity management solution providing REST based services for authentication and authorization. We achieve this by implementing two important open standards:

• OAuth 2.0
• SCIM 2.0

OSIAM is published under the MIT licence, giving you the greatest freedom possible to utilize OSIAM in you project or product. Watch our blog to stay informed about releases and upcoming changes.

Use cases

• Single app with OSIAM as free backing store for users and groups and local auth service.
• Distributed app with OSIAM as central identity store and auth service.
• Publish your app's API with OSIAM as auth service for 3rd-parties and allow safe access to your user's data.

Quick Start

Download the latest version of OSIAM:

curl -L https://dl.bintray.com/osiam/downloads/osiam/3.0/osiam-3.0.war -o osiam.war

Make the .war file executable:

chmod +x osiam.war

Start OSIAM:

./osiam.war

After some seconds, OSIAM should be fully running. You can now retrieve your first access token:

curl -H "Authorization: Basic ZXhhbXBsZS1jbGllbnQ6c2VjcmV0" -X POST -d "grant_type=client_credentials&scope=ADMIN" http://localhost:8080/oauth/token

You can now start to setup OSIAM, by changing the administrator's password and add your own OAuth client. Please see the Installation and Configuration Manual for details.

Documentation

Learn how to install and configure OSIAM for production in the documentation.

Components

• osiam handles the authentication and authorization based on OAuth 2.0 and holds the SCIM based user data
• addon-self-administration provides account management self-service as a web application
• addon-administration lets you administer users and groups via a web application

Easy customization

Every visual aspect of OSIAM's components can be easily customized by supplying your own templates, stylesheets and scripts to make OSIAM integrate seamlessly with your application. Read the customization guide to learn more.

Snapshots

To use the latest snapshot of OSIAM just download it from JFrog OSS: https://oss.jfrog.org/repo/org/osiam/osiam/latest-SNAPSHOT/

Scroll down to the bottom of the page and select the latest WAR file.

Issue Tracker

Please report issues, bugs and feature requests via [the issue tracker] (https://github.com/osiam/osiam/issues).

Get involved

Help is very appreciated. Please read the contributors guide to learn how to get started.

shell's Issues

Persist Session Information

It would be nice to be able to persist connect and login information on file. This would permit a more convenient use of the shell for a once set up connection.

Better Tab Completion

Tab-completion is not ideal at the moment. For example, when I don't know what arguments a command takes, I am forced to use ?help command. It would be much nicer to imitate the behavior of zsh or bash.

For example

osiam-shell/localhost/@admin> search-users <TAB> <TAB>

should tell me which arguments search-users accepts.

add a distribution artifact

as previously started to be discussed here: osiam/distribution#12

summary (this is my point of view): we should release distribution archives of the shell including at least a start script or other supporting files. this distribution could then be included in the OSIAM main distribution.

Should we support the shell?

CLI Flags

The connect and login commands could be substituted by command-line flags. This might make the shell easier and faster to use. Furthermore, the user could define aliases for different connections.

More Helpful Error when Arguments are Wrong

This input

osiam-shell/localhost/@admin> search-users
There's no command "search-users" taking 0 arguments

should trigger something like (without forcing me to type ?help search-users)

osiam-shell/localhost/@admin> ?help search-users
Kommando: search-users
Kürzel:  su
Parameter:  (filter)
Beschreibung: Search for existing users by a given filter.
Anzahl der Parameter: 1
filter    String    The filter string.

Kommando: search-users
Kürzel:  su
Parameter:  (filter, index, limit, orderBy, asc)
Beschreibung: Search for existing users by a given Query.
Anzahl der Parameter: 5
filter    String    The filter string.
index    Long    The index (1-based) of the first resource.
limit    Integer    The number of returned users per page.
orderBy    String    Sort the users by the given attribute.
asc    Boolean    Should the users sorted ascending?

Improve Error Messages

Currently, most "wrong" user input triggers a stack-trace. This is not a sign of a good user interface. It would be way better to catch common cases and tell the user what is wrong.

This can be reproduced by

osiam-shell/localhost/@admin> search-users foo
de.raysha.lib.jsimpleshell.exception.CLIException: org.osiam.client.exception.ConflictException: no viable alternative at input 'foo'
    at de.raysha.lib.jsimpleshell.ShellCommand.invoke(ShellCommand.java:77)
...

HowTo is Missing

The README.md should contain (at least) a minimal amount of instructions on how to use the shell.

review fat jar generation

as previously started to be discussed here: osiam/distribution#12

summary (this is my point of view): currently the maven-assembly-plugin is used to build a fat jar of the shell. imho the maven-shade-plugin is better suited for this job and should replace the maven-assembly-plugin.

Migrate to Gradle

As discussed in #3, we might benefit from migrating the project to gradle.

Note that the init plugin provides some automation for this.