Skip to content

detailed_reference_installation

Jump to bottom Edit New page
David Moebius edited this page Jan 13, 2014 · 38 revisions

Installation and configuration

This document describes how to install and configure OSIAM.

If you are looking into rolling out a number of OSIAM installations our Puppet project is going to make things a lot easier.

For convenience reasons we will provide OSIAM in the near future also packaged as .deb or .rpm.

Chapters:

Requirements

This document takes the following prerequisites as basis:

Category Prerequisite Comment
Operating Systems Debian Wheezy, Ubuntu 12.04 and later, Fedora 18 and later Debian Wheezy recommended. Install with "Standard system utilities" and "SSH server".
Runtime Environment Java 1.7, OpenJDK 1.7.0_03 JRE apt-get install openjdk-7-jre
Application Server Tomcat 7.0.28 apt-get install tomcat7
Database PostgreSQL 9.1.9 apt-get install postgresql-9.1
All of the items are freshly installed. If you use a minimum Debian installation you may want to install additional packages thatare required for the described process: 
# apt-get install unzip sudo curl

If you have an existing and older installation, you are using different version or a different OS, AppServer or DB this document may not match your situation.

The operating system

For this document we are working with the user "osiam". In principle you can work with your own non priviledged user to follow the steps in this document.

Verify the application server and database server are up and running after the installation of the requirements above. When looking at the process list:

$ ps aux

You should be able to find some processes running under the postgres user and at least one running under the tomcat7 user:

tomcat7  18461  0.2  1.5 373412 65468 ?        Sl   10:52   0:16 /usr/lib/jvm/java-7-openjdk-i386/bin/java [..]
postgres 19926  0.0  0.1  47188  7480 ?        S    10:54   0:01 /usr/lib/postgresql/9.1/bin/postgres [..]
postgres 19928  0.0  0.0  47188  1528 ?        Ss   10:54   0:01 postgres: writer process
postgres 19929  0.0  0.0  47188  1284 ?        Ss   10:54   0:01 postgres: wal writer process
postgres 19930  0.0  0.0  47620  2372 ?        Ss   10:54   0:00 postgres: autovacuum launcher process
postgres 19931  0.0  0.0  17388  1344 ?        Ss   10:54   0:00 postgres: stats collector process

We recommend to choose the latest OSIAM release version.

Download the OSIAM .war files for auth-server and resource-server

$ wget http://maven-repo.evolvis.org/releases/org/osiam/osiam-auth-server/<VERSION>/osiam-auth-server-<VERSION>.war

$ wget http://maven-repo.evolvis.org/releases/org/osiam/osiam-resource-server/<VERSION>/osiam-resource-server-<VERSION>.war

and the OSIAM sources

$ wget http://maven-repo.evolvis.org/releases/org/osiam/osiam-auth-server/<VERSION>/osiam-auth-server-<VERSION>-sources.jar

$ wget http://maven-repo.evolvis.org/releases/org/osiam/osiam-resource-server/<VERSION>/osiam-resource-server-<VERSION>-sources.jar

and unpack the sources

$ unzip osiam-resource-server-<VERSION>-sources.jar

Database setup

First add the user osiam and the database osiam to the PostgreSQL database.

Start the database commandline:

$ sudo -u postgres psql

and run the following commands:

postgres=# CREATE USER osiam WITH PASSWORD '<YOURPASSWORD>';
postgres=# CREATE DATABASE osiam;
postgres=# GRANT ALL PRIVILEGES ON DATABASE osiam TO osiam;
postgres=# \q

to create the user and the database, granting the user full access to the database and finally quitting the database commandline.

Go to the directory where you unpacked the sources. Note: The following statements have to be executed as the osiam database user.

If you already have an old setup delete all tables by calling

$ psql -f ./sql/drop_all.sql -U osiam

Now initialize the database by calling

$ psql -f ./sql/init_ddl.sql -U osiam

Next you need to insert some basic data to the databse by calling

$ psql -f ./sql/init_data.sql -U osiam

If you want to setup a test environment where you have some basic data to play with, you can create some scopes, grants, a test client and a simple user by calling

$ psql -f ./sql/example_data.sql -U osiam

If your Linux user is not 'osiam' you may get an an error message like

psql: FATAL:  Peer authentication failed for user "osiam"

In that case you must change the local authentication method for postgreSQL in

/etc/postgresql/9.1/main/pg_hba.conf

Find the line

local   all             all                                     peer

and replace the "peer" with "md5". Afterwards restart the database and rerun the import commands from above:

$ /etc/init.d/postgresql restart

Default setup

The example_data.sql script sets some defaults in the database for the new OSIAM instance.

Username marissa
Password koala
Client ID example client
Client secret secret
Client redirect URI http://localhost:5000/oauth2
Client scopes GET POST PUT PATCH DELETE

The base64 encoded value for the default client's ID and secrect is ZXhhbXBsZS1jbGllbnQ6c2VjcmV0

Configuring Scim Extension

The previously executed init script will also add the tables to manage scim extensions. At the moment you can register an extension and all users will have this additional selfdefined fields. There are no pure scim core schema users anymore. The additional fields could be empty, so it will be optional for the users to fill them out with values.

To add some selfdefined fields your previously have to define an extension with an URN. This URN must be unique. Here is an example of such an insert for postgres:

INSERT INTO scim_extension VALUES (<UNIQUE_EXTENSION_ID>, <UNIQUE_URN>)

for example:

INSERT INTO scim_extension VALUES (39, 'urn:org.osiam.extensions:Test:1.0')

NOTE: You may leave the UNIQUE_EXTENSION_ID off and let your database generate a unique id.

For adding the fields, you have to reference the previously added extension. You need to execute an insert something like this for postgres:

INSERT INTO scim_extension_field VALUES(<UNIQUE_EXT_FIELD_ID>, <REQUIRED - currently only false>, <SELFDEFINED_FIELD_NAME>, <TYPE - currently only STRING>, <UNIQUE_EXTENSION_ID>)

for example:

INSERT INTO scim_extension_field VALUES(213, false, 'gender', 'STRING', 39)

NOTE: You may leave the UNIQUE_EXT_FIELD_ID off and let your database generate a unique id.

Configuring OSIAM

OSIAM needs to be instructed on how to connect to the database and some additional information. Create the file

/etc/osiam/osiam.properties

with content based on this example:

db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://localhost:5432/osiam
db.dialect=org.hibernate.dialect.PostgresPlusDialect
db.username=osiam
db.password=<YOUR_PASSWORD>
osiam.profiling=false
osiam.server.port=8080
osiam.server.host=localhost
osiam.server.http.scheme=http

Deployment into the application server

To deploy OSIAM in the previously installed Tomcat the downloaded .war files need to be renamed and moved into Tomcat's webapp directory:

$ sudo mv osiam-auth-server-<VERSION>.war /var/lib/tomcat7/webapps/osiam-auth-server.war
$ sudo mv osiam-resource-server-<VERSION>.war /var/lib/tomcat7/webapps/osiam-resource-server.war

Edit the file /etc/tomcat7/catalina.properties. Add to the parameter shared.loader the complete path of the directory where the file osiam.properties was put earlier, e.g.

shared.loader=/var/lib/tomcat7/shared/classes,/var/lib/tomcat7/shared/*.jar,/etc/osiam

Edit the file /etc/default/tomcat7 and change the size of the heap space allocated for Tomcat by modifying the following line

JAVA_OPTS="-Djava.awt.headless=true -Xmx128m -XX:+UseConcMarkSweepGC"

to

JAVA_OPTS="-Djava.awt.headless=true -Xms512m -Xmx1024m -XX:+UseConcMarkSweepGC"

And now restart Tomcat:

$ sudo /etc/init.d/tomcat7 restart

You should see the following output:

[ ok ] Stopping Tomcat servlet engine: tomcat7. 
[ ok ] Starting Tomcat servlet engine: tomcat7.

Next Steps

Testing OSIAM's availablility

Now you can check from the commandline if OSIAM started correctly using the following command:

$ curl http://localhost:8080/osiam-resource-server/ServiceProviderConfigs

Everything is fine when you see a JSON string as response that looks like this:

{"schemas":["urn:scim:schemas:core:1.0"],"patch":{"supported":true},"bulk":{"supported":false},"filter":{"supported":true,"maxResults":100},"changePassword":{"supported":false},"sort":{"supported":true},"etag":{"supported":false},"xmlDataFormat":{"supported":false},"authenticationSchemes":{"authenticationSchemes":[{"name":"Oauth2 Bearer","description":"OAuth2 Bearer access token is used for authorization.","specUrl":"http://tools.ietf.org/html/rfc6749","documentationUrl":"http://oauth.net/2/"}]}}r``

Customized Setup

Earlier you saw what the default client and user credentials are. Of course you should use your own client and user credentials.

Here is an example of how to replace to default setup:

You need an access token in order to send commands to the server. So this is how you get it.

$ curl -H "Authorization: Basic ZXhhbXBsZS1jbGllbnQ6c2VjcmV0" -X POST -d "grant_type=client_credentials&scope=GET POST PUT DELETE" http://localhost:8080/osiam-auth-server/oauth/token

You will get an answer like:

{"access_token":“<YOUR_ACCESS_TOKEN>","token_type":"bearer","expires_in":716,"scope":"DELETE GET POST PUT"}

Take the value from access_token (shown in the example as <YOUR_ACCESS_TOKEN>) and put it in an environment variable.

$ YOUR_ACCESS_TOKEN=<YOUR_ACCESS_TOKEN>

Add your client - see also Parameters for clients

curl -i -H "Accept:  application/json" -H "Content-type:  application/json" -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" -X POST localhost:8080/osiam-resource-server/Client -d '{"id": "<YOUR_CLIENT_ID>", "accessTokenValiditySeconds": "9999", "refreshTokenValiditySeconds": "9999", "redirectUri": "<YOUR_REDIRECT_URI>", "scope": ["POST", "PUT", "GET", "DELETE", "PATCH"], "validityInSeconds": "9999", "implicit": "false", "grants": ["authorization_code", "client_credentials", "refreshtoken"]}‘

The client's secret will be autogenerated and can only be read from the database directly at the moment.

=> select id, client_secret from osiam_client;

Delete default client

curl -i -H "Accept:  application/json" -H "Content-type:  application/json" -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" -X DELETE localhost:8080/osiam-resource-server/Client/example-client

Get the default user‘s ID

curl -i -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" -X GET ‘localhost:8080/osiam-resource-server/Users?access_token=$YOUR_ACCESSTOKEN&filter=userName%20eq%20"marissa“’

Extract the ID of the requested (default) user and use it in the following request to update the user with your preferred user credentials:

curl -i -H "Accept:  application/json" -H "Content-type:  application/json" -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" -X PUT localhost:8080/osiam-resource-server/Users/<DEFAULT_USERS_ID> -d '{"schemas":["urn:scim:schemas:core:1.0"], "externalId":"","userName":"<YOUR_USERNAME>","password":"<YOUR_USERS_PASSWORD>"}'

SSL in Tomcat

SCIM and OAuth 2.0 are standards that require SSL to be enabled. An exhaustive explanation how to setup SSL for HTTP connections in Tomcat 7 can be found here.

Next steps

Now you are ready to work with OSIAM, either using a connector or directly the API itself.

Add a custom footer
Add a custom sidebar

Clone this wiki locally