compared with
Current by Thor Henning Hetland
on Jun 23, 2016 17:30.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (12)

View Page History
{gliffy:name=AuthSequenceStandAlone|align=left|size=L|version=4}
TODO describe how an application developer or architect can integrate an application with Whydah.
h2. Quick set-up (Using Docker on development machine)

h3. Preparation
* [Install docker|https://docs.docker.com/installation/]
* Start Whydah, ready for Integration
{code}
sudo docker run -it -p 80:9999 -p 9990:9990 -p 9995:9995 -p 9996:9996 -p 9997:9997 -p 9998:9998 totto/whydah bin/bash
/usr/bin/supervisord &
ls -al /home/*/log/
{code}
* Add your application to the Whydah componnets (in Whydah 2.0: add it in securitytykenservice.TEST_LOCALHOST.properties)

# Install SSOLoginService in IAM_MODE=DEV on local machine
## Adjust properties to fit your neeed
# Install SecurityTokenService in IAM_MODE=DEV on local machine
## Adjust properties to fit your neeed
# Verify test installation manually or by using the Whydah-TestWebApp
h2. Client code example

h3. Integration
* [Integration tutorials]

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

{code}
// Execute a POST to authenticate my application
String myApplicationToken = Request.Post("https://sso.whydah.net/sso/logon")
.bodyForm(Form.form().add("applicationcredential", "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?> <applicationcredential>
<params> <applicationID>234</applicationID> <applicationSecret>applicationsecret</applicationSecret> </params>
</applicationcredential>").build())
.execute().returnContent().asBytes();

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

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

// Execute a POST to SecurityTokenService with userticket to get usertoken
String usertoken = Request.Post("https://sso.whydah.net/sso/user/"+myApplicationTokenID+"/get_usertoken_by_userticket/")
.bodyForm(Form.form().add("apptoken", myApplicationToken).add("userticket", userTicket).build())
.execute().returnContent().asBytes();

// Thats all you need to get a full userdatabase, SSO, Facebook/OAUTH support ++
{code}
(Example using Apache HTTP Components Fluent API and jOOX Fluent API)


h2. 1. Getting started - SecurityTokenService and parsing of UserToken
{section}
{column}
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.

*Prerequisties:*
Development environment Win or Linux with Java installed.

# Download SecurityTokenService.jar [Download|http://mvnrepo.cantara.no/content/repositories/releases/net/whydah/token/SecurityTokenService/]
# Download propertyfile [here|https://raw.githubusercontent.com/altran/Whydah-SecurityTokenService/master/securitytokenservice.DEV.properties] to same location
# In command prompt, run *java -DIAM_MODE=DEV -DIAM_CONFIG=securitytokenservice.DEV.properties -jar SecurityTokenService.jar*
# Point a browser at [http://localhost:9998/tokenservice/]
# Test the operations in the [GUI|https://wiki.altrancloud.com/download/attachments/37388812/STS-testweb.png] (test API driver)

*NOTE:*
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|https://raw.githubusercontent.com/altran/Whydah-SecurityTokenService/master/t_test@hotmail.com.token])

h3. Some tips on parsing the UserToken to check roles

*Xpath examples* (Hint: experiment [here|http://www.freeformatter.com/xpath-tester.html])
{code}

// 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\"");


# find my applicationtokeID from returned ApplicationToken
/token/params/applicationtokenID

# check UserToken if the user has the role Employee for the application with a given applicationID
/token/application[@ID="<myApplicationID>"]/role[@name="Employee"]
{code}

*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 [https://github.com/altran/Whydah-TestWebApp]
* Spring Security example [https://github.com/altran/Whydah-TestWebApp/tree/master/ImplementationExamples/spring-security]
* Django example [https://github.com/altran/Whydah-TestWebApp/tree/master/ImplementationExamples/Django]
* JavaScript example [https://github.com/altran/Whydah-TestWebApp/tree/master/ImplementationExamples/Javascript]
* SharePoint 2013 (.NET) example [https://github.com/altran/Whydah-TestWebApp/tree/master/ImplementationExamples/SharePoint]
{column}
{column}
{gliffy:name=Integration - simple standalone|align=left|size=L|version=5}
{column}
{section}

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

# Download SSOLoginwebApp.jar [Download|http://mvnrepo.cantara.no/content/repositories/releases/net/whydah/sso/SSOLoginWebApp/]
# Download propertyfile [here|https://raw.githubusercontent.com/altran/Whydah-SSOLoginWebApp/master/ssologinwebapp.TEST.properties] to same location.
# Adjust properties and insert reference to a proper logo for your app/company.
# In command prompt, run *java -DIAM_MODE=TEST -DIAM_CONFIG=ssologinwebapp.TEST.properties -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 :)
{column}
{column}
{gliffy:name=AuthSequenceStandAlone-WithLoginWebApp|align=left|size=L|version=1}
{column}
{section}

h2. 3. Store users and roles - Introduce UserIdentityBackend
{section}
{column}
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|http://mvnrepo.cantara.no/content/repositories/releases/net/whydah/identity/UserIdentityBackend/]
# Download propertyfile [here|https://raw.githubusercontent.com/altran/Whydah-UserIdentityBackend/master/useridentitybackend.DEV.properties] to same location.
# Adjust properties if needed.
## If you want to import test users, create a folder called testdata, [download these files|https://github.com/altran/Whydah-UserIdentityBackend/tree/master/src/main/resources/testdata] and adjust them if needed. Set *import.enabled=true*

# In command prompt, run *java -DIAM_MODE=DEV -DIAM_CONFIG=useridentitybackend.DEV.properties -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 securitytokenservice.DEV.properties to securitytokenservice.TEST.properties (Or download [securitytokenservice.TEST.properties|https://github.com/altran/Whydah-SecurityTokenService/blob/master/securitytokenservice.TEST.properties])
## Adjust TEST properties to point at the newly installed UIB om http://localhost:9995/uib/
## Start by running *java -DIAM_MODE=TEST -DIAM_CONFIG=securitytokenservice.TEST.properties -jar SecurityTokenService.jar*

{column}
{column}
{gliffy:name=AuthSequenceStandAlone|align=left|size=L|version=6}
{column}
{section}

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 - UAWA].
Whydah 2.1+ introduces administration of collaborating applications

h2. 5. 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.


-----

{include:Whydah development environment installation}