1
==========================================
2
Writing a Liberty Service Provider in Java
3
==========================================
5
:author: Nicolas Clapiès
6
:contact: nclapies@entrouvert.com
7
:date: $Date: 2006/10/28 15:17:45 $
8
:revision: $Revision: 1.2 $
9
:copyright: Copyright © 2006 Entr'ouvert
11
.. contents:: Table of Contents
12
.. section-numbering::
15
Lasso Java Binding Settings
16
===========================
18
Java binding of Lasso is implemented by the Java package lasso.jar. In order to
19
compile Java sources importing this package, you need to set environment
22
export CLASSPATH=$CLASSPATH:/path/to/lasso/jar/lasso.jar
24
Lasso Java package is linked to C Lasso library thanks to JNI interface
25
library. Under UNIXes like Linux, the library is named linjlasso.so. Under Mac
26
OS X, library is named libjlasso.dynlib. Windows systems need jlasso.dll. You
27
need to add library directory path to system library loader.
29
For UNIXes system with bash, command is like::
31
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lasso/jni/interface/
33
where /path/to/lasso/jni/interface/ is the Lasso JNI interface hosting
37
Liberty and Lasso profiles
38
==========================
40
Lasso provides the necessary functions to implement Liberty Alliance profiles,
41
as defined in the `Liberty ID-FF Bindings and Profiles Specification`_ :
43
- Single Sign-On and Federation
45
- Federation Termination Notification
51
Java applications first need to import Lasso package::
53
import com.entrouvert.lasso.*;
56
Service Provider keys and metadata files
57
========================================
62
Service Provider needs private and public keys to sign sent messages. It also
63
needs Identity Provider public key to verify received messages. Private and
64
public keys are loaded from PEM files by Lasso.
66
Liberty Metadata files
67
----------------------
69
Service Provider need to get Identity Provider metadata to know where to send
70
requests and how to process received requests from Identity Provider. Metadata
71
are xml document describing provider identifier, deployed urls where to send
72
requests and initiate profile and methods describing how to send or process
75
Service provider typically describe metadata like this::
79
providerID="http://sp.example.com/liberty/metadata"
80
xmlns="urn:liberty:metadata:2003-08">
81
<SPDescriptor protocolSupportEnumeration="urn:liberty:iff:2003-08">
82
<SoapEndpoint>http://sp.example.com/liberty/soap-endpoint</SoapEndpoint>
83
<SingleLogoutServiceURL>sp.example.com/liberty/single-logout</SingleLogoutServiceURL>
84
<AssertionConsumerServiceURL id="AssertionConsumerService1"isDefault="true">http://sp.example.com/liberty/assertion-consumer-service</AssertionConsumerServiceURL>
85
<FederationTerminationNotificationProtocolProfile>http://projectliberty.org/profiles/fedterm-idp-soap</FederationTerminationNotificationProtocolProfile>
86
<FederationTerminationNotificationProtocolProfile>http://projectliberty.org/profiles/fedterm-idp-http</FederationTerminationNotificationProtocolProfile>
87
<SingleLogoutProtocolProfile>http://projectliberty.org/profiles/slo-idp-soap</SingleLogoutProtocolProfile>
88
<SingleLogoutProtocolProfile>http://projectliberty.org/profiles/slo-idp-http</SingleLogoutProtocolProfile>
89
<SingleLogoutProtocolProfile>http://projectliberty.org/profiles/slo-sp-soap</SingleLogoutProtocolProfile>
90
<AuthnRequestsSigned>true</AuthnRequestsSigned>
93
<OrganizationName>Example Organization</OrganizationName>
97
Where sp.example.com is the domain name of Service Provider.
99
``http://sp.example.com/liberty/metadata`` is the Service Provider Liberty
102
``http://sp.example.com/liberty/soap-endpoint`` is the Service Provider SOAP
103
endpoint where Identity Provider send SOAP single logout or defederation
106
``http://sp.example.com/liberty/assertion-consumer-service`` is the Service
107
Provider assertion consumer url where Identity Provider must return single sign
108
on authentication response.
110
``http://sp.example.com/liberty/single-logout`` is the Service Provider single
111
logout url. Service Provider can initiate single logout from this url or
112
process HTTP single logout request from Identity Provider. `
114
Lasso Server and remote providers settings
115
==========================================
120
Every time needing to initiate a Liberty Profile or process a Liberty request,
121
Lasso needs to set a Lasso Profile object with a Lasso Server to set Service
122
Provider informations (private key and metadata) and identity Provider
123
informations (public key, certificate and metadata).
125
The Server object may be created as follows::
127
Server lassoServer = new Server("sp-metadata.xml",
128
"sp-privatekey.pem", null, null);
129
lassoServer.addProvider(lasso.PROVIDER_ROLE_IDP,
130
"idp-metadata.xml", "idp-publickey.pem", null);
132
- sp-metadata.xml is the Liberty metadata file of the service provider
133
- idp-metadata.xml is the Liberty metadata file for the identity provider
134
- sp-privatekey.pem is the service provider private key; used to sign documents
135
- idp-publickey.pem is the identity provider public key; used to verify
136
signature in documents sent by the identity provider
141
It can be useful to dumps Server object and save it for next use. LassoServer
142
objects can be serialised into a XML formatted string::
144
String lassoServerDump = lassoServer->dump();`
146
It is then really easy to get back properly constructed objects::
148
Server lassoServer = Server.newFromDump(lassoServerDump);
154
Initiating Single Sign On::
156
Login lassoLogin = new Login(lassoServer);
157
lassoLogin.initAuthnRequest(lassoServer.getProviderIds().getItem(0),
158
lasso.HTTP_METHOD_REDIRECT);
159
LibAuthnRequest authnRequest = (LibAuthnRequest) login.getRequest();
160
authnRequest.setNameIdPolicy(lasso.LIB_NAMEID_POLICY_TYPE_FEDERATED);
161
authnRequest.setProtocolProfile(lasso.LIB_PROTOCOL_PROFILE_BRWS_ARTIFACT);
162
lassoLogin.buildAuthnRequestMsg();
163
String msgUrl = lassoLogin.getMsgUrl();
165
Processing Single Sign On Identity Provider Artifact response from
166
AssertionConsumerServiceURL metadata URL::
168
lassoLogin.initRequest(queryString, lasso.HTTP_METHOD_REDIRECT);
169
lassoLogin.buildRequestMsg();
170
String soapEndpoint = lassoLogin.getMsgUrl();
171
String soapRequestMsg = lassoLogin.getMsgBody();
172
// If a lassoSessionDump or a lassoIdentityDump was saved, restore them.
173
lassoLogin.setSessionFromDump(lassoSessionDump);
174
lassoLogin.setIdentityFromDump(lassoIdentityDump);
176
lassoLogin.acceptSso();
177
} catch (RuntimeException e) {
179
String lassoSessionDump = lassoLogin.getSession().dump();
180
String lassoIdentityDump = lassoLogin.getIdentity().dump();
181
String nameIdentifier = lassoLogin.getNameIdentifier().getContent();
187
Initiate SOAP Single Logout from Service Provider
188
-------------------------------------------------------
190
Initiating single logout from SingleLogoutServiceURL metadata url::
192
Logout lassoLogout = new Logout(sp.server);
193
lassoLogout.setSessionFromDump(lassoSessionDump);
194
lassoLogout.setIdentityFromDump(lassoIdentityDump);
195
lassoLogout.initRequest(sp.server.getProviderIds().getItem(0),
196
lasso.HTTP_METHOD_SOAP);
197
lassoLogout.buildRequestMsg();
198
String soapEndpoint = lassoLogout.getMsgUrl();
199
String soapRequestMsg = lassoLogout.getMsgBody();
200
// Send SOAP request and get SOAP response ...
202
lassoLogout.processResponseMsg(soapResponseMsg);
203
} catch (RuntimeException e) {
207
// Everything is ok, remove lasso session dump from application storage
209
Process Single Logout HTTP request from Identity Provider
210
-------------------------------------------------------------
212
Process single logout from SoapEndpoint metadata url::
214
Logout lassoLogout = new Logout(lassoServer);
215
lassoLogout.processRequestMsg(logoutRequestMsg);
216
lassoLogout.setIdentityFromDump(lassoIdentityDump);
217
lassoLogout.setSessionFromDump(lassoSessionDump);
219
lassoLogout.validateRequest();
220
} catch (RuntimeException e) {
222
lassoLogout.buildResponseMsg();
223
String soapResponseMsg = lassoLogout.getMsgBody();
229
Processing SOAP defederation from SoapEndpoint metadata url::
231
if (lasso.getRequestTypeFromSoapMsg(soapRequestMsg) == lasso.REQUEST_TYPE_DEFEDERATION) {
232
Defederation lassoDefederation = new Defederation(lassoServer);
233
lassoDefederation.processNotificationMsg(soapRequestMsg);
234
lassoDefederation.setIdentityFromDump(lassoIdentityDump);
236
lassoDefederation.validateNotification();
240
// return 204 HTTP status code
243
Database Considerations
244
=======================
246
Lasso has been designed to let the service provider keep on using existing
247
databases. Typically there is already a table describing users; just add an
248
identity dump column to the existing table:
250
======= ======================================== ==============
251
User Id existing data (name, address...) Identity dump
252
======= ======================================== ==============
255
======= ======================================== ==============
257
Mapping between existing users and name identifiers sent by the identity
258
provider can be done with a simple table.
260
=============== =======
261
Name Identifier User Id
262
=============== =======
266
=============== =======
268
.. note:: A separate table is needed because one user Id could map
269
to several name identifiers; in case there are several identity
272
Sessions are also commonly stored in databases; just add a session dump column
273
to the existing session table:
275
========== ================= =============
276
Session Id misc session data Session dump
277
========== ================= =============
278
6744066 ... <Session> ...
279
3338824 ... <Session> ...
280
========== ================= =============
282
Likewise sessions should be mapped to name identifiers.
284
=============== ==========
285
Name Identifier Session Id
286
=============== ==========
288
=============== ==========
303
.. _Liberty ID-FF Bindings and Profiles Specification:
304
http://www.projectliberty.org/specs/draft-liberty-idff-bindings-profiles-1.2-errata-v1.0.pdf
306
.. _LassoLogin: /documentation/api-reference/lassologin.html
307
.. _LassoLogout: /documentation/api-reference/lassologout.html
308
.. _LassoIdentity: /documentation/api-reference/lassoidentity.html
309
.. _LassoServer: /documentation/api-reference/lassoserver.html
310
.. _LassoSession: /documentation/api-reference/lassosession.html
added
removed
docs/lasso-book/writing-a-java-sp.txt
