View Source

h2. Client code example

// Execute a POST to authenticate my application
String myApplicationToken = Request.Post("")
.bodyForm(Form.form().add("applicationcredential", "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<applicationSecret>This is my application secret</applicationSecret>

// Find applicationtokenID from applicationToken
String myApplicationTokenID = $(myApplicationToken).xpath("/applicationtoken/params/applicationtokenID[1]");

// Redirect user til SSO login web with my URL as redirect
// Get userticket from redirect back URL param
//public String myWebApplication(@QueryParam("userticket") String userticket, HttpServletRequest request)

// Execute a POST to SecurityTokenService with userticket to get usertoken
String usertoken = Request.Post(""+myApplicationTokenID+"/get_usertoken_by_userticket/")
.bodyForm(Form.form().add("apptoken", myApplicationToken).add("userticket", userTicket).build())

// Get some token values
String userTokenID = $(usertoken).xpath("/usertoken/@id");
NodeList applicationRoleList = $(usertoken).xpath("/usertoken/application");
boolean hasEmployeeRoleInMyApp = $(usertoken).xpath("/usertoken/application[@ID=\"234\"]/role[@name=\"Employee\"");
(Example using Apache HTTP Components Fluent API and jOOX Fluent API)

h2. 1. Getting started - SecurityTokenService and parsing of UserToken
SecurityTokenService is created to give the application an [ApplicationToken] and a [UserToken].
The UserToken will contain the roles granted for the given user in the app.
It is where to start when you want to integrate your app.

Development environment Win or Linux with Java installed.

# Download SecurityTokenService.jar [Download|]
# Download propertyfile [here|] to same location
# In command prompt, run *java -DIAM_MODE=DEV -jar SecurityTokenService.jar*
# Point a browser at [http://localhost:9998/tokenservice/]
# Test the operations in the [GUI|] (test API driver)

In DEV mode, you can create and adjust test-data/users/usertokens by creating files in the same directory with naming convension t__<my_test_username>.token_ ( See [Example|])

h3. Some tips on parsing the UserToken to check roles

*Xpath examples* (Hint: experiment [here|])

# find my applicationtokeID from returned ApplicationToken

# check UserToken if the user has the role Employee for the application with a given applicationID

*Typical datastructures:*
[ApplicationCredential], [ApplicationToken], [UserCredential], [UserToken]

h3. Integration examples
We have provided a few integration examples for a set of different programming languages.
See links below.

* Java web-app example []
* Spring Security example []
* Django example []
* JavaScript example []
* SharePoint 2013 (.NET) example []
{gliffy:name=Integration - simple standalone|align=left|size=L|version=3}

h2. 2. Expand with a login GUI - Introduce SSOLoginWebApplication
SSOLoginWebApplication is created to present a basic configurable login GUI, reset password GUI and user registration.

# Download SSOLoginwebApp.jar [Download|]
# Download propertyfile [here|] to same location.
# Adjust properties and insert reference to a proper logo for your app/company.
# In command prompt, run *java -DIAM_MODE=TEST -jar SSOLoginwebApp.jar*
# Point your browser to see the login GUI: [http://localhost:9997/sso/]
# Configure your application to redirct to http://localhost:9997/sso/ if no valid UserToken is presented.
** PS: Make this a configurable property in your app, since you might want to change it in PROD-environment :)

h2. 3. Store users and roles - Introduce UserIdentityBackend
UserIdentityBackend is created to store user identities, store user roles and integrate with 3rd party IDP's.
It may run locally in DEV mode with embedded LDAP for user storage and HSSQL db for role storage.
It should be set up to provide default roles to users from different 3rd party identities.

# Download UserIdentityBackend.jar [Download|]
# Download propertyfile [here|] to same location.
# Adjust properties if needed.
## If you want to import test users, create a folder called testdata, [download these files|] and adjust them if needed. Set *import.enabled=true*

# In command prompt, run *java -DIAM_MODE=DEV -jar UserIdentityBacnend.jar*
# If you have SecurityTokenService running from point 1. above, you need to change it's mode from DEV to TEST for it to talk with UIB:
## Stop it by pressing CTRL+C in the command line window
## Copy to (Or download [|])
## Adjust TEST properties to point at the newly installed UIB om http://localhost:9995/uib/
## Start by running *java -DIAM_MODE=TEST -jar SecurityTokenService.jar*


h2. 4. User administration for administrators - Introduce UserAdminWebApp
You might want to have a look at the registered users and change them.
For that you might want to run [UserAdminWebApp].

h2. 4. User administration self service - Introduce UserAdminService
You might want to include some simple self service features in your application, like adding roles to certain users or self registration.
UserAdminService is created to allow for exactly that.
It is however still in an early release.