Global Federated Identity and

oklahomaflockΑσφάλεια

3 Νοε 2013 (πριν από 3 χρόνια και 9 μήνες)

221 εμφανίσεις


1





Global Federated Identity and

Privilege Management
(GFIPM)

Web Services


Developer Documentation

Java/Metro

Implementation

June

1
2
, 2012






Copyri ght (c) 2012, Georgi a Tech Research Insti tute. Al l Ri ghts Reserved.

2





3


1

INTRODUCTION
................................
................................
................................
................................
................................
......

5

1.1

P
URPOSE AND
S
COPE

................................
................................
................................
................................
.........................

5

1.2

I
NTE
NDED
A
UDIENCE

................................
................................
................................
................................
.........................

5

1.3

T
ERMINOLOGY
,

D
EFINITIONS
,

A
CRONYMS
,

A
BBREVIATIONS

................................
................................
................................

5

2

GFIPM
-
WS S2S SIP MODELS DE
SCRIPTION

................................
................................
................................
......................

5

2.1

R
EQUIREMENTS

................................
................................
................................
................................
................................
.

5

2.2

A
RCHITECTURE
O
VERVIEW

................................
................................
................................
................................
.................

6

2.2.1

Development Approach

................................
................................
................................
................................
..........

6

2.2.2

Components
................................
................................
................................
................................
..............................

6

2.2.3

Build environment

................................
................................
................................
................................
...................

7

2.3

M
ESSAGE
E
XCHANGES

................................
................................
................................
................................
.......................

8

2.4

S
ERVICE
C
ONTRACT
................................
................................
................................
................................
............................

9

2.4.1

In
formation Exchange Data Model

................................
................................
................................
....................
10

2.4.2

Servi ce Contract WSDL
................................
................................
................................
................................
..........
11

2.4.3

Servi ce Level Agreement (SLA Securi ty Polici es)
................................
................................
...............................
12

2.4.3.1

SOAP Version

................................
................................
................................
................................
..................

13

2.4.3.2

WS
-
Poli cy Version

................................
................................
................................
................................
...........

13

2.4.3.3

WS
-
Securi tyPolicy Version

................................
................................
................................
..............................

13

2.4.3.4

WS
-
Addressing
................................
................................
................................
................................
................

13

2.4.3.
5

MTOM

................................
................................
................................
................................
.............................

13

2.4.3.6

WS
-
I Basic Profile

................................
................................
................................
................................
............

13

2.4.3.7

WS
-
I Basic Secure Profile

................................
................................
................................
................................

13

2.4.3.8

SAML 2.0 Token

................................
................................
................................
................................
..............

14

2.4.3.
9

WS
-
ReliableMessaging
................................
................................
................................
................................
....

14

2.5

I
NTEGRATION
P
OINTS
................................
................................
................................
................................
.......................
15

2.6

GFIPM

S
ECURITY
M
ODEL

................................
................................
................................
................................
...............
16

2.6.1

GFIPM User Assertions
................................
................................
................................
................................
..........
16

2.6.2

GFIPM Enti ty Assertions

................................
................................
................................
................................
.......
16

2.6.3

GFIPM Cryptographi c Trust Fabric
................................
................................
................................
......................
17

2.6.4

Model Certifi cates

................................
................................
................................
................................
.................
17

2.6.
4.1

Updating certifi cates
................................
................................
................................
................................
.......

18

2.6.4.1.1

Trust Keystores
................................
................................
................................
................................
...........

18

2.6.4.1.2

Pri vate Keystores

................................
................................
................................
................................
.......

18

3

GFIPM
-
WS S2S PROFILE SAMPL
E IMPLEMENTATION (GW
SS2SPSI)

................................
................................
.........
19

3.1

S
AMPLE
I
MPLEMENTATION
C
OMPONENTS

................................
................................
................................
........................
19

3.1.1

GFIPM CTF Library

................................
................................
................................
................................
.................
19

3.1.
1.1

CTF Li brary API

................................
................................
................................
................................
................

19

3.1.1.2

CTF Scripts
................................
................................
................................
................................
.......................

20

3.1.1.3

CTF Command Li ne Utility

................................
................................
................................
..............................

21

3.1.2

GFIPM Web Servi ces Auxiliary Library

................................
................................
................................
...............
22

3.1.3

Information Exchange Servi ce Contract Impl ementation Library

................................
................................
.
24

3.1.4

GFIPM WS S2S Consumer
-
Provider (Model 1) Implementation

................................
................................
....
25

3.1.4.1

WSC Implementation (Model 1)

................................
................................
................................
.....................

25

3.1.4.2

WSP Implementati
on (Model 1)

................................
................................
................................
.....................

26


4

3.1.4.2.1

WSP SLA Implementation

................................
................................
................................
..........................

26

3.1.4.2.2

Certi fi cate Validati on

................................
................................
................................
................................
.

27

3.1.4.2.3

WSP Servi ce Implementation
................................
................................
................................
.....................

28

3.1.5

GFIPM WS S2S User
-
Consumer
-
Provider (Model 2/Model 8) Implementation

................................
..........
29

3.1.5.1

IDP/ADS STS Implementation (Model 8)

................................
................................
................................
........

29

3.1.5.1.1

Token Generati on

................................
................................
................................
................................
......

30

3.1.5.1.2

Attribute Generation
................................
................................
................................
................................
..

31

3.1.5.1.3

IDP SLA Implementation

................................
................................
................................
............................

32

3.1.5.1.4

ADS SLA Implementation

................................
................................
................................
...........................

33

3.1.5.1.5

ADS Certi ficate Validation

................................
................................
................................
..........................

33

3.1.5.2

WSC Implementation (Model 2)

................................
................................
................................
.....................

34

3.1.5.2.1

WSC Servi ce Implementation

................................
................................
................................
....................

34

3.1.5.2.2

WSC Client Implementation
................................
................................
................................
.......................

36

3.1.5.3

WSP Implementati on (Model 2)

................................
................................
................................
.....................

39

3.1.5.3.1

WSP SLA Implementation

................................
................................
................................
..........................

40

3.1.5.3.2

Certi fi cate Valida
ti on

................................
................................
................................
................................
.

41

3.1.5.3.3

SAML Assertion Validation
................................
................................
................................
.........................

42

3.1.5.3.4

WSP Servi ce Implementation
................................
................................
................................
.....................

43

3.1.5.4

GFIPM Client (Model 2)

................................
................................
................................
................................
..

45

3.2

D
EBUGGING

................................
................................
................................
................................
................................
....
47

3.2.1

Message Logging

................................
................................
................................
................................
...................
47

3.2.2

Applications Logging

................................
................................
................................
................................
.............
48

4

REFERENCES

................................
................................
................................
................................
................................
..........
49

5

APPENDIXES
................................
................................
................................
................................
................................
..........
52

5.1

A
TTACHMENT
A
:

GFIPM

SAML

U
SER
A
SSERTION
S
AMPLE

................................
................................
..............................
52

5.2

A
TTACHMENT
B:

GFIPM

SAML

M
ETADATA
E
NTITY
A
SSERTION
S
AMPLE

................................
................................
.........
53

5.3

A
TTACHMENT
C:

GFIPM

CTF

L
IBRARY
API

................................
................................
................................
.....................
54

5.4

A
TTACHMENT
D:

S
AMPLE
SLA

S
ECURITY
P
OLICY FOR
IDP

STS
................................
................................
..........................
56

5.5

A
TTACHMENT
E:

S
AMPLE
SLA

S
ECURITY
P
OLICY FOR
ADS

STS

................................
................................
.........................
59

5.6

A
TTACHMENT
F:

S
AMPLE
SLA

S
ECURITY
P
OLI
CY FOR
WSP

M
ODEL
1

................................
................................
................
60

5.7

A
TTACHMENT
G:

S
AMPLE
SLA

S
ECURITY
P
OLICY FOR
WSP

M
ODEL
2

................................
................................
...............
61

5.8

A
TTACHMENT
H:

S
AMPLE
SLA

S
ECURITY
P
OLICY FOR
M
ESSAGE
E
NCRYPTION AND
S
IGNATURE
................................
...........
63

5.9

A
TTACHMENT
I:

S
AMPLE
SLA

P
OLICY FOR
WS
-
R
ELIABLE
M
ESSAGING
1.1

................................
................................
.........
63

5.10

A
TT
ACHMENT
J:

S
AMPLE
SLA

P
OLICY FOR
A
LGORITHM
S
UITE

................................
................................
...........................
63




5

1

Introduction

1.1

Purpose and Scope

The
Global Federated Identity and Privilege Management (
GFIPM
)

program has
published a number of
technical documents to support implementation of Web Services.
This document provides an example
of how
to develop
w
eb services conforming to the

GFIPM
Web Services System
-
to
-
System Profile,
version 1.0

(
S2S
)

using
Oracle
Java techno
logies and
the
Metro [METRO]

w
eb service
s

stack.
The
purpose of this document is to support

the understanding and interpretation

of the conformance
criteria
of the
profile

using the
GFIPM WS S2S Profile

Sample Implementation (G
WS
S
2
S
PSI
)

project

accompanying this document
.

GWSS2SPSI

is

designed according to the
Global

Reference Architecture
(
GRA
) and Service Oriented Architecture (
SOA
)

development guidelines [
GRAGIDES
]
and
S2S

[
GFIPMS2SP
]
conformance requirements.
The d
escribed methods and code

samples
are

only one
approach; there might be other, equally valid approaches.
The
sample
implementation
project
code is
available for use by
implementers
as a template for their own development or as an example that can
be used for reference purpos
es.


1.2

I
ntended
A
udience

This document is intended for software developers

and

system architects. It is expected that
the
developer

has programming
experience with
Java
. It is expected that the developer

has basic
understanding of the Public Key Infrastructure (PK
I),
and
has working
knowledge of
SOAP
-
based
Web
Services.

In addition the
developer
should be familiar with
the
Apache
Maven
[
MAVEN
]
software
project management tool.

Finally, t
he
developer

is expected to be familiar with
the
GRA [
GRA
] and S2S
[
GFIPMS2SP
].

1.3

Terminology,
D
efinitions,
A
cronyms,
A
bbreviations

This document contains language that uses technical terms related to federations, identity
management, web services, and other related technologies.

To minimize confusion for readers, it is
important t
hat each technical term have a precise definition.

Accordingly, technical terms in this
document are to be interpreted as described in [GFIPM
TERMS
]
. In addition, technical terms specific to
this system to system web services implementation are described
in
S2S
[
GFIPMS2SP
]
.

2

GFIPM
-
WS
S2S
SIP
Model
s

Description

The
GWSS2SPSI project includes implementation for the following SIPs:



GFIPM
-
WS Consumer
-
Provider Service Interaction Profile [
GFIPMS2SP

8.1]



GFIPM
-
WS User
-
Consumer
-
Provider Service Interaction
profile [
GFIPMS2SP

8.2]



GFIPM
-
WS SAML Assertion Delegate Service Interaction Profile [
GFIPMS2SP

8.8]

2.1

Requirements

The f
ollowing software is required for

GWSS2SPSI
:

Java (Java SE 7) [JAVA]

Glassfish (3.1.2) [GLASSFISH]

Metro Web Services stack (2.2)
[METRO]

Maven (2.2.1) [MAVEN]


6

2.2

Architecture

Overview

2.2.1

Development Approach

The s
tandard information exchange specification is developed
,
published and distributed in the form of
a
GRA

S
ervice
S
pecification
P
ackage (GRA SSP)
, which includes WSDL, XML Schemas
, and other
business
artifacts.
For the purposes of this project
, a

simple document exchange

contract

was developed in
accordance with GRA SOA development guidelines

and best practices
.

2.2.2

Components

The following diagrams depict major components for each corresponding
service interaction
model.


Figure
1
:

GFIPM WS Consumer
-
Provider SIP (Model 1)


Figure
2
:

GFIPM WS User
-
Consumer
-
Provider SIP (Model 2) / Assertion Delegate Service SIP (Model 8)

The following notations used in the
diagrams
:

WSC


Peb Service 䍯nVu浥r

STS


Securi瑹 Token Service


7

WSP


Peb Service ProviTer

RST


RequeV琠Securi瑹
Token

IMP



ITen瑩瑹 ProviTer

RSTR


RequeV琠Securi瑹 Token ReVponVe

AMS


AVVer瑩on MelegaWe Service

SIP


Service In瑥rac瑩on Profile

䍬ien琠


䍯浭mnT line applica瑩on

GFIPM 䍔F


GFIPM 䍲Xp瑯grapUic TruV琠Fabric

TUe T
e瑡ileT Vequence

of V瑥pV

for
W
Ue
MoTel 1

Va浰le i浰le浥n瑡瑩on

iV TeVcribeT in

S2S Sec瑩on
8.1
.

TUe T
e瑡ileT Vequence

of V瑥pV

for
瑨e
MoTel 2 Va浰le i浰le浥n瑡瑩on involveV Veveral aTTi瑩onal V瑥pV
no琠fullX covereT bX
S2S Sec瑩onV

8.2

anT

8.8. ATTi瑩onal V瑥pV (1
-
5
, 10
) involve
ob瑡ining iniWial SAML
token from user’
s
IDP

STS and are
outside of the scope of the

S2S.

1.

The
command line application
(Client)

on behalf of the user

connects to the WSC service

to
retrieve the security requirements for the service. The WSC’s
requires a S
AML assertion

for
the user to be included with the message
.

2.

The
Client is
statically configured

with
the
information about an
IDP
,

used
for
obtaining

of a
SAML assertion

for the user
.

3.

The Client sends a

Request
Security Token (RST)
message
to the
IDP
. The
request is
secured
with the
IDP

certificate
. User authentication is performed according to

the

IDP

policies.

4.

The
IDP

issues a SAML user assertion containing user attributes

and
returns a
Request
Security

Token Response

(RSTR)

message with the issued token
to the Client.

The SAML
user assertion includes GFIPM user attributes.

5.

The Client sends another request to the WSC service, this time with the SAML user assertion
from the
IDP

for authentication and secured with the WSC
service
certificate.

6.

The WSC
clien
t
sends a

Request Security Token (RST) message

to the
Assertion Delegate
Service (
ADS
)
. The message contains the SAML user assertion received
in step 4

by the WSC
service and is

included inside of


OnBehalfOf


element
.

The RST message

is
secured

with
the
ADS certificate.

The message

requests
the
ADS for

a re
-
issued token so the WSC

client

can access the WSP, acting
on behalf of

the user.

7.

The
ADS

issues a
new

SAML user assertion
that is signed with the ADS certificate
and then
send
s

a
Request Security

Toke
n Response

(RSTR)

message with the issued token to the WSC

client
.

8.

The WSC

client

sends a request to the WSP. The message
includes

the re
-
issued SAML
assertion and is secured with the WSC certificate.
The WSP validates the SAML assertion
according to the
security policy
.

9.

The WSP send
s

a response to the WSC.

10.

The WSC sends a response to the Client.

2.2.3

Build environment

The
GWSS2SPSI
is tightly integrated with the
Apache
Maven

[MAVEN]
build environment.

The sample
implementation is a multi
-
module project, and
contains several subprojects that can be independent
and reused in a production implementation.


For details on the sample implementation libraries and
components see

the

Sample Implementation
Components

chapter.


8

2.3

Message Exchanges


Figure
3
: Consumer
-
Provider SIP


Figure
4
:
User
-
Consumer
-
Provider SIP


9

2.4

Service Contract

The
Web Service Contract defines
a
data format
(data model),

what a service does (functionality), how
to access the service (technology),

and
where a service is located (instance)
.


The
GWSS2SPSI
described
in this document assumes a
contract
-
first
development
approach
.

T
he Web
S
ervice implementation i
s
developed using classes generated from the WSDL.


This approach is in contrast to the implementation
-
first approach, where the WSDL is automatically generated from the implementation code.

The WSDL
-
first approach is recommended by GRA reference architect
ure.

The
Figure 5

below reflects the structure
of the simple Web Service Contract used in the
GWSS2SPSI:


Figure
5
: Web Service Contract

Each deployable
service
component (WSC, WSP) of the GWSS2SPSI contains a service contract
that is
located under “
$COMPONENT_NAME/src/wsdl


directory

and has the following files:



src/wsdl/CommercialVehicleCollisionExchangeSchema.xsd



src/wsdl/CommercialVehicleCollisionMessageSchema.xsd



src/wsdl/CommercialVehicleCollisionWebserviceImpl.wsdl



src/ws
dl/CommercialVehicleCollisionWebserviceIntf.wsdl


10

2.4.1

Information Exchange
Data
Model

The
Web Service Contract WSDL

uses XML Schema
[XSD2004]

to define document exchange types

for
the
Information Exchange Data Model

(IEDM)
.

The GWSS2SPSI project includes simplified IEDM
that can
be used for reference purpos
es and should be substituted with the production information data
exchange.

The
information exchange
s
chemas

are split into two parts
:



Exchange
contract message

schema

(
CommercialVehicleCollisionMessageSchema.xsd
)



Exchange
message
data
model

schema

(
CommercialVehicleCollisionExchangeSchema.xsd
)


Figure
6
: Exchange Contract Message Schema (CommercialVehicleCollisionMessageSchema.xsd)


11


Figure
7
:
Exchange Message Data
Model

Schema (CommercialVehicleCollisionExchangeSchema.xsd)

2.4.2

Service Contract
WSDL

The Service Contract WSDL includes t
ypes,
m
essages,
p
ort
t
ypes,
b
indings,
and service endpoint
locations.

The
Service Contra
ct WSDL is split into two

functional

sections:



Service Interface WSDL (
CommercialVehicleCollisionWebserviceImpl
.w
s
dl)



Service Implementation WSDL (
Commerci
alVehicleCollisionWebserviceIntf.wsdl)

The
Service Interface WSDL
imports
the
Information Exchange
Data Model

described in the previous
section.
Based on the imported
data model
types t
he Service Interface WSDL

defines
messages,
operations, and ports as shown on the
F
igure

8
below.


12


Figure
8
: Service Contract WSDL M
essages,
O
perations, and
P
orts

The
Service Interface WSDL also includes service bindings and
the associated
GFIPM Service Level
Agreement

(SLA)

as shown on the code snippet below

(some of the content is not shown for the sake of
brevity)
.

The
SLA
is
described in det
ail in the
Service Level A
greement (SLA Security Policies)

section
.


Figure
9
:
Service Bindings and Service Level Agreement

2.4.3

Service Level A
greement (SLA Security Policies)

The
Service Level Agreement defines service access policies for
message
authentication,

authorization,

integrity, non
-
repudiation, and confidentiality
required to connect to the service. This section
addresses

conformance requirements outlined in
S2S
.

While the WSDL file is not the complete documentation for a real service, which would require an
additional documentation

(such as business
-
level documents)

to describe

the

service behavior,

the
WSDL file contains

a formal, machine
-
interpretable

specification of the service interface and includes
an
SLA expressed using WS
-
Policy and WS
-
SecurityPolicy

[SPEOAIS]
.

The WSDL

for each model

meets S2S
functional requirements and GRA RS WS
-
SIP service interface conformanc
e targets.


13

2.4.3.1

SOAP Version

The WSDL uses SOAP 1.1

and

includes

XML Namespace and corresponding prefix

declaration
:

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

2.4.3.2

WS
-
Policy Version

The WSDL uses WS
-
Policy 1.2

and includes
XML Namespace and corresponding p
refix

declaration:

xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"

2.4.3.3

WS
-
SecurityPolicy Version

The WSDL uses WS
-
Security
Policy 1.2

[WS
-
SECURITYPOLICY]

and includes
XML Namespace and
corresponding prefix

declaration
:

xmlns:sp="http://docs.oasis
-
ope
n.org/ws
-
sx/ws
-
securitypolicy/200702"

2.4.3.4

WS
-
Addressing

The WSDL uses WS
-
Addressing 1.0
-

WSDL Binding

[
WSAWSDL
]

and includes XML Namespace and
corresponding prefix declaration:


xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
.

The addressing policy
is specified using the WS
-
Policy 1.2 and the “
UsingAddressing
” assertion element
as follows: “
<wsaw:UsingAddressing wsp:Optional="false"/>


2.4.3.5

MTOM

The WSDL uses
WS
-
MTOMPolicy 1.0 [MTOM] and includes XML Namespace and corresponding prefix
declaration

xmlns:w
soma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"
.

The server policy to accept MTOM message format is specified using

wsoma:OptimizedMimeSerialization
” policy assertion.

2.4.3.6

WS
-
I Basic Profile

The WSDL
meets all
applicable conf
ormance target
outlined in WS
-
I Basic Profile 1.2 [
WSIBP12
]
.


2.4.3.7

WS
-
I Basic Secure Profile

The GFIPM WS S2S normative conformance requirements

[8.1.2, 8.2.2, 8.8.2]

in accordance with WS
-
I
Basic Security Profile 1.1 Section 9, “XML
-
Signature”
demand
that the
following parts of the message
s

are properly signed and encrypted (if necessary): SOAP Body and SOAP Attachments, Timestamp, WS
-
Addressing headers, WS
-
Security Token for User’s SAML Assertion (if present).
The policy uses

sp:SignedParts
” and “
sp:EncryptedParts
” elements

to
indicate which parts of the SOAP messages are to
be signed

and encrypted
as shown in the
Attachment H: Sample SLA Security Policy for Message
Encryption and Signature
.



14

To address GFIPM WS S2S normative conformance requirement to include a timestamp
,
the
policy uses
the

sp:IncludeTimestamp
” element.
An explicit assertion is not needed for signing the timestamp
becau
se if the timestamp is

included

it will be
signed

by default
.


The policy uses

the


sp:AsymmetricBinding


security policy assertion to implement SOAP message
protection using asymmetric key algorithms. Using asymmetric binding policy for SOAP message
protection allows selection

of the particular parts of a message to protect (for ex: individual headers,
body), while transport layer security (

sp:TransportBinding


security policy assertion) can operate only
on the whole message. An asymmetric binding policy must be applied to an

endpoint policy subject.


There are interoperability issues between Metro and .Net when using the “sp:AsymmetricBinding”
security policy assertion. To avoid these interoperability issues, the “sp:TransportBinding” security policy
assertion ca
n be used
.
When “
sp:TransportBinding


security policy assertion is used

sp:EncryptedParts

and “
sp:Sign
edParts
” security policy assertions are ignored.

The “
sp:TransportBinding
” security policy
assertion
must

be used with “
RequireClientCertificate
” attribute set t
o “
true
”.

The policy uses “
sp:OnlySignEntireHeadersAndBody
” security policy assertion to
apply

the
signature
only
to an entire body or to entire headers, not to sub
-
elements of the body or sub
-
elements of a header
.

The policy uses “
sp:RequireSignatureConf
irmation
” security policy assertion to
require

the
request
message signatures to be confirmed as part of the response

message
as specified by S2S normative
conformance requirements.
To confirm the request message signatures at run
-
time t
he
service
include
s
and signs, in the response, all the signatures included in the request.

The policy uses
the

sp:Basic256Sha256
” element

within
the

sp:AlgorithmSuite
” security policy
assertion to require the
algorithm suite that uses SHA
-
256 for the signature digest and 256
-
bit Basic as
the message encryption algorithm.

The

signatureAlgorithm


attribute for
the

sp:AlgorithmSuite

security policy assertion

is set to ”
SHA256withRSA
” to require the use of
the SHA
-
256 based signature
algori
thm.

2.4.3.8

SAML 2.0 Token

The policy uses SAML 2.0 Token Profile 1.1
[WSS11
-
SAML1120
-
PROFILE]

and includes

sp:WssSamlV20Token11
” element within the “
sp:Signed
Encrypted
SupportingTokens
” security policy
assertion.

2.4.3.9

WS
-
ReliableMessaging

The
policy

uses WS
-
Reliable
Messaging [WS
-
RM] 1.1 and
the WSDL
includes XML Namespace and
corresponding prefix declaration
:


xmlns:wsrmp="http://docs.oasis
-
open.org/ws
-
rx/wsrmp/200702
”.


The
service
requirement to initiate reliable messaging is specified by the use of the

wsrmp:RMA
ssertion
” policy assertion as

shown in the
Attachment
I
: Sample SLA Policy for WS
-
ReliableMessaging 1.1
.


15

2.5

Integration Points

The sample implementation (GWSS2SPSI) exposes various integration points that developers can use to
further extend and modify the implementation with additional functionality and new features.
The
Table
1
below reflects the available integration points an
d the section within this document where each
integration point is described.

SIP

Integration Point

Section(s)

Consumer
-
Provider

Service Contract

3.1.3

Information Exchange
Se
rvice Contract
Implementation Library


Trust Fabric

3.1.1

GFIPM
CTF

Library


WSC Authorization

3.1.4.2

WSP Implementation

(Model 1)

User
-
Consumer
-
Provider

Service Contract

3.1.3

Information Exchange
Se
rvice Contract
Implementation Library


Trust Fabric

3.1.1

GFIPM
CTF

Library


SAML Token and GFIPM
Attribute Generation

3.1.5.1

IDP
/ADS
STS

Implementation

(Model 8)


SAML Token
V
alidation

3.1.5.3.3

SAML Assertion Validation


WSC and User
Authorization

3.1.5.3.4

WSP Service Implementation

Table
1
:
Implementer
Integration Points




16

2.6

GFIPM

Security
Model

2.6.1

GFIPM User Assertions

GFIPM user assertions are based on the GFIPM Metadata

[GFIPMMETA]
specification version 2.0.

A user
assertion consists of a SAML assertion with SAML metadata tags for describing message characteristics
and GFIPM user attributes for describing a user’s properties such as name, phone, email, and privileges.

The
T
able

2

be
low outlines
some
sample
information in the SAML GFIPM user assertion

used in
GWSS2SPSI
(not all tags or attributes are shown).


Metadata Tag

Value

Description

gfi pm:2.0:user:Empl oyerName

Dundl er
Mi ffl i n

Organi zati on name.

gfipm:2.0:user:SwornLawEnforc
ementOfficerIndicator

false

An
IDP

may assert that a user is a SLEO if certain
conditions, as defined by the GFIPM Metadata Spec, are
met (such as being authorized to make an arrest, etc).

Table
2
: GFIP
M User Assertions Examples

A sample SAML assertion containing GFIPM user attributes can be found in
Attachment A:
GFIPM SAML
User Assertion Sample
.

2.6.2

GFIPM Entity Asser
tions

GFIPM entity a
ssertion
s are based on the GFIPM Metadata
specification version 2.0
.

A GFIPM entity
a
ssertion

is an entry in the GFIPM
Crypto
graphic
Trust Fabric

(CTF)

document that represents an entity
such as an
IDP
, SP, WSC, WSP, A
D
S,
A
S,
or

TIB in the federation
.

Each Entity entry in the CTF

includes

the

X.509
public
certificate data

and

several

informational attributes about each entity
.


Each
E
ntity could
also contain

corresponding

Web Service Endpoint

URL
,
Delegate Service Endpoint

URL
,
Metada
ta
Exchange Endpoint

URL
,
and
WSDL
URL
.

The
T
able
3
below outlines
some
sample information in the
GFIPM
CTF

for

the
Entity used in
the
GWSS2SPSI
.

N
ot all
entity
information is included

in the table
.

XPath

Sample Value
(s)

Description

md:Entities
Descriptor


/
md:EntityDescriptor




/@entityID

curewspm1

cureidpm2

An

Entity Id

md:Entities
Descriptor


/
md:EntityDescriptor



/md:RoleDescriptor




/@xsi:type

gfipmws:GFIPMWebServiceProviderType

gfipmws:GFIPMAssertionDelegateServiceType

A

role of an
E
ntity

(ex: WSP,
ADS)

md:Entities
Descriptor


/
md:EntityDescriptor



/md:RoleDescriptor




/gfipmws:WebServiceEndpoint

https://curewspm1:8181/m1wsp/services/cvc

A web service endpoint

for
WSP

md:Entities
Descriptor


/
md:EntityDescriptor



/md:RoleDescriptor



/gfipmws:DelegatedTokenServiceEndpoint

http
s
://cureidpm2:8
1
8
1
/m2sts/services/sts

A web service endpoint fo
r
ADS STS


XPath Prefixes Notations:


xmlns:md=”urn:oasis:names:tc:SAML:2.0:metadata”


xmlns:gfipmws=”http://gfipm.net/standards/metadata/2.0/webservices”


xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
instance"

Table
3
: GFIPM Entity Assertions Examples


17

A Sample GFIPM entity assertion
for WSP and WSC
used in
GFIPM CTF

can be found in

Attachment B:
GFIPM SAML
Metadata
Entity Assertion Sample
.

2.6.3

GFIPM

Cryptographic

Trust
Fabric

The
GFIPM Cryptographic Trust Fabric (
CTF
)

is

a
n XML

document signed by the Federation Manager
Organizatio
n
,

containing trusted information about each
IDP
, SP, WSC, WSP, AS,
ADS
, and TIB in the
federation. It includes X.509 certificate data for each software entity, as well as a GFIPM Entity
Assertion providing various informational attributes about each entity. The
CTF

is the cryptographic
trust anchor for all federation trans
actions.


Figure
10
: Conceptual view of the Trust Fabric

The
GWSS2SPSI supplies a library that allows
dynamic query of the GFIPM CTF
. For detailed API see
chapter

GFIPM
CTF

Library
.


2.6.4

Model Certificates

This chapter covers trusted public and private certificates used in the GWSS2SPSI, Truststores
,

and
Keystores locations for those certificates.

Each entity used i
n
the
GWSS2SPSI contains an entry in the sample
CTF
.


The
T
able
4 below
shows the
E
ntity
Id’
s

and

corresponding
roles
.

The
GWSS2SPSI is distributed with trusted and private
J
ava
keystores, where certificate aliases correlate to the GFIPM CTF entity
Id
.

Model

GFIPM
Role

Entity Id

1

WSC

curewscm1

WSP

curewspm1

2

8

WSC

curewscm2

WSP

curewspm2

ADS STS

cureidpm2

Table
4
: Entity Roles and Certificate Aliases

Each deployable component (WSC, WSP,
IDP
/ADS
) of the GWSS2SPSI contains
configured private and
trusted keystores
that
are

located
in the


$COMPONENT_NAME/src/
main/resources/META
-
INF”

directory:


18



The
Maven build automatically includes keystores
in
distributable WAR files under

WE
B
-
INF/classes/META
-
INF
” directory
,

making it available
in the application’s runtime environment
.

2.6.4.1

Updating certificates

2.6.4.1.1

Trust
K
eystores

When
a

new GFIPM CTF is released
,

it is necessary to
remove
retired
trusted certificates from the
deprecated
GFIPM
CTF and
update
keystore with new
trust
ed

certificates. The new certificates
can

be
easily extracted from
the
GFIPM CTF using supplied

CTF Command Line Utility
.

The u
tility
can

also
be
used to remove old certificates and install new certificates in trusted keystores (*
-
cacerts.jks).
The
GFIPM
CTF

Library

includes a set of sample
scripts designed to populate trusted certificates into the Java
keystore.

To
manage private keys and public certificates
,

developers
also
have other
tools at their disposal:



Java “keytool” [KEYTOOL]



KeyStore Explorer [KSEXPL]



KeyTool IUI [KTIUI].


2.6.4.1.2

Privat
e
K
eystores

The
GFIPM
CTF

Library

includes a set of sample scripts designed to populate private keys into the Java
keystore.


The library includes a Java class (“src/m
ain/java/ImportKey.java”) that allows import of the
DER
-
encoded format keys generated by OpenSSL
[
OPENSSL
]

into the private Java keystore
.


Consumer
-
Provider SIP Model 1

m1wsc/src/main/resources/META
-
INF/curewscm1
-
cacerts.jks

m1wsc/src/main/resources/META
-
INF/curewscm1
-
keystore.jks

m1wsp/src/main/resources/META
-
INF/curewspm1
-
cacerts.jks

m1wsp/src/main/resources/META
-
INF/curewspm1
-
keystore.jks

User
-
Consumer
-
Provider SIP Model 2

m2client/src/main/resources/META
-
INF/cure
-
clien
t
-
cacerts.jks

m2client/src/main/resources/META
-
INF/cure
-
client
-
keystore.jks

m2sts/src/main/resources/META
-
INF/cureidpm2
-
cacerts.jks

m2sts/src/main/resources/META
-
INF/cureidpm2
-
keystore.jks

m2wsc/src/main/resources/META
-
INF/curewscm2
-
cacerts.jks

m2wsc/src/main/resources/META
-
INF/curewscm2
-
keystore.jks

m2wsp/src/main/resources/META
-
INF/curewspm2
-
cacerts.jks

m2wsp/src/main/resources/META
-
INF/curewspm2
-
keystore.jks


19

3

GFIPM
-
WS
S2S Profile
Sample Implementation

(GWSS2SPSI)

3.1

Sample Implementation
Components

The
GFIPM Web
Services S2S
Consumer
-
Provider SIP (Model 1) sample implementation
distribution
contains the following modules:

1.

trustfabric


GFIPM Cryptographic Trust Fabric

Library

2.

wscontract



Information Exchange Service Contract Implementation Library

3.

m1wsc


GFIPM Web Services
Model 2 Web Service Consumer

(WSC)

4.

m1wsp


GFIPM Web Services Model 2 Web Service Provider

(WSP)

The
GFIPM Web
Services S2S User
-
Consumer
-
Provider SIP (Model 2
/Model 8
)
sample implementation
distribution contains the following modules:

1.

trustfabric


GFIPM
CTF

Library

2.

wscontract



Information Exchange Service Contract Implementation Library

3.

m2sts


GFIPM Web Services Model 2 Security Token Service

(STS) for
the
Identity Provider

(
IDP
)
and
the
Assertion Delegate Service (ADS)

4.

m2lib


GFIPM
Web Services a
uxiliary
l
ibrary

5.

m2wsc


GFIPM Web Services Model 2 Web Service Consumer

(WSC)

6.

m2wsp


GFIPM Web Services Model 2 Web Service Provider

(WSP)

7.

m2client


GFIPM Model 2 Web Service Client

Library

modules (trustfabric,

ws
contract
,

m2lib
) are
reused by other mo
dules (WSC, WSP,
IDP
/ADS STS)

by using
the
maven dependency mechanism.

3.1.1

GFIPM
CTF

Library

The
GFIPM
Cryptographic
Trust Fabric

(CTF)

Library consists of two functionally independent projects:
GFIPM
CTF library

API and GFIPM
CTF
Command Line Utility.

3.1.1.1

CTF Li
brary API

The
GFIPM
CTF library API allows dynamic querying
of the
GFIPM CTF

from

within
a
web application.
For detailed CTF library API see
Attachment C: GFIPM CTF Library API
.

The
GFIPM
CTF library API comes with
sample

GFIPM CTF

xml file
:

src/main/resources/net/gfipm/trustfabric/gfipm
-
trust
-
fabric
-
model2
-
sample
-
signed.xml

The
GFIPM CTF library Trust Fabric obj
ect could be
also
initialized using
an
external trust fabric as shown
on the examples below.


20



The
Trust Fabric

object

is thread
-
safe.
A s
tatic instance could be initialized through Singleton
Facto
ry
Pattern [
GO4
] using TrustFabricFactory.


The developer must install “
trustfabric
” artifact into the local Maven repository (“mvn install”).
To add
the
GFIPM CTF library Trust Fabric API to your application
,

include Maven dependency in your POM file
as follows
:


3.1.1.2

CTF Scripts

The GFIPM CTF library contains sample scripts that allow fast population of the trusted and private
keystores with public certificates and private keys. The sample scripts are located
under “
src/bin”
directory.

Scripts that populate trusted keystores (*
-
cacerts.jks) from supplied public certificates
:



src/bin/create_cacerts_stores_metro_m1.sh



src/bin/create_cacerts_stores_metro_m2.sh

Scripts that populate private keystores (*
-
keystore
.jks) from supplied
openssl generated key pairs:



src/bin/create_private_s
tores_metro_m1.sh



src/bin/create_private_stores_metro_m2.sh

The GFIPM CTF library also includes

the

“ImportKey.java” class in the default package under
“src/main/java”

directory. The “ImportKey” was developed to help
import
the
DER
-
encoded format
keys

into

the private
Java
keystore.

//Using default CTF “https://ref.gfipm.net/gfipm
-
signed
-
ref
-
metadata.xml”

TrustFabric tf = new TrustFabric();

//Using sample CTF included in the library API

TrustFabric tf = new TrustFabric("net/gfipm/trustfabric/gfipm
-
trust
-
fabric
-
model2
-
sample
-
signed.xml");

//Using CTF included in your application classpath

TrustFabric tf = new TrustFabric("classpath:net/gfipm/trustfabric/your
-
gfipm
-
trust
-
fabric.xml");

//Usi
ng other externally available CTF via http or https URL

TrustFabric tf = new TrustFabric("https://yourdomain.net/your
-
gfipm
-
signed
-
ref
-
metadata.xml ");

//Usting TrustFabricFactory and static singleton Trust Fabric

TrustFabric tf = TrustFabricFactory.getInstance("net/gfipm/trustfabric/gfipm
-
trust
-
fabric
-
model2
-
sample
-
signed.xml");



<dependency>


<groupId>net.gfipm</groupId>


<artifactId>trustfabric</artifactId>


<version>1.0
-
SNAPSHOT</version>



</dependency>


21

3.1.1.3

CTF Command Line Utility

The
GFIPM

CTF Command Line Utility is designed to extract
certificates for
the
GFIPM Entities from the
GFIPM CTF document and populate
trusted Java
keystore
; save certificates as a file;
remove old
certificates and update trusted Java keystore with new certificates from the CTF document.

Utility also
provides user with options to
validate the CTF document.


The
utility could be invoked
through maven. Maven con
figuration file (pom.xml) already includes
several run configurations to get started. For example, to extract all certificates
from the CTF
and
populate
Java keystore (

gfipm
-
trust
-
fabric.jks

) use the following Maven configuration:


trustfabric options: (options are processed in the order shown)


-
help


Print this
help and then exits.


-
verbose yes | no


Set verbose output (default is yes).


-
trustdoc <URL> | nief | ref | sample


Load GFIPM trust document from URL, or NIEF Fed url, or Reference Fed url, or special Sample
URL.


Default is https://ref.
gfipm.net/gfipm
-
signed
-
ref
-
metadata.xml


-
validatetrustdoc


Validate loaded GFIPM trust document.


-
password prompt | <password> | none


Prompt user for key store password or use the one given or no password. Otherwise use default
password (changeit).


-
keepEntityId


Keep an EntityId as Alias in the keystore or as a file name when extracting all certificates from
the GFIPM trust
doc.


-
keystore <filename>


Load Java key store from <filename>. If no file is found one will be created.


-
delete <entityid> | <alias>


Delete entry with entity id or alias name from key store.


-
deleteall


Delete all GFIPM entries from ke
y store. Does not delete non
-
GFIPM entries.


-
add <entityid> | cisaidp | cisasp


Retrieve entity with entityid from trust doc and adds it to key store. (cisaidp, cisasp is for
debugging)


-
addall


Extract all certificates from GFIPM trust doc an
d adds non
-
duplicates to Java key store.


-
writeall <directory>


Extract all certificates from GFIPM trust doc and writes non
-
duplicates to files in dirctory.


-
view nondup | dup | cisa | attr1


Print non
-
duplicate or all duplicate entity ids in
trust doc to terminal. cisa and attr1 are for
debugging only.


-
print alias | cert | rawcert | all


Print contents of key store: all alias names, all base64 certs, all text certs, or everything.


22


To extract all certificates
from the CTF and
save
each Entity certificate
to
the separate file in the
“certificates” directory use the following Maven configuration:



The configuration could be invoked through Maven commands: “mvn clean install exec:exec
”.

3.1.2

GFIPM

Web Services
Auxiliary
Library

The
GFIPM

Web Services auxiliary library

(m2lib)
contains common code,
provides a set of auxiliary
utilities
, hotfixes, and
the
SAML V2.0 Condition for Delegation Restriction
implementation

[
SAMLDelegation2009]
.

Th
e l
ibrary is used in

WSC, WSP,
and
in
IDP
/ADS STS
projects
of the
GWSS2SPSI.


A
SAML V2.0 Condition for
the
Delegation Restriction
implementation
uses JAXB

[JAXB]

and
hooks up
directly
to
the
default JAXB Context used by
the
Metro
framework. The
explanation of the
implementation details of the Delegation Restriction JAXB library is beyond the scope of this document.

The
WSC, WSP, and
IDP
/ADS STS

applications
initialize
this
library
by
including

the following code within
the
application

initializat
ion servlet
:


The c
ode
snippet
below shows how to
use
the
SAML V2.0 Condition for Delegation Restriction
implementation

library
:


<argument>
-
ke
ystore</argument>


<argument>gfipm
-
trust
-
fabric.jks</argument>


<argument>
-
addall</argument>


<argument>
-
validatetrustdoc</argument>


<argument>
-
trustdoc</argument>


<argument>
https://ref.gfipm.net/gfipm
-
signed
-
ref
-
metadata.xml
</argument>


<argument>
-
writeall</argument>


<argument>certificates</argument>


<argument
>
-
validatetrustdoc</argument>


<argument>
-
trustdoc</argument>


<argument>
https://ref.gfipm.net/gfipm
-
signed
-
ref
-
metadata.xml

</argument>


static {


DelegateUtil.initDelegateJAXBContext();


}


23


Note that
the
sample code doesn’t include validation for

null


values, and other important production
code
checks.

This l
ibrary
can

also be used
for

stand
-
alone
JAXB
processing of the DOM objects. For example to obtain
the
Delegate object from
the
W3C DOM Element
,

it is possible to use
the
fromElement

method within
gov.niem.ws.util.jaxb.delegate.Delegate

class
. The signature of the
fromElement
method is shown in the
code snippet below:


For detailed usage of the Delegate JAXB library
,

see
the
sample code in

the

m2wsp
\
src
\
main
\
java
\
gov
\
niem
\
ws
\
sample
\
cvc
\
service
\
GFIPMCertificateValidatorWSP

class
.

To add
the
GFIPM library to
the

application
,

include
its
Maven dependency in
the

POM file
as follows
:


This library is a part of multi
-
module maven
project (
gfipm
-
ws
-
m2
) and will be installed in the repository
automatically.

Element domSamlAssertion =
SAMLUtil.createSAMLAssertion(xmlStreamerReader);

com.sun.xml.wss.saml
.
Assertion assertion = AssertionUtil.fromElement(domSamlAssertion);


Conditions conditions = assertion.getConditions();

for (Object condition : conditions.getConditions()) {


if(condit
ion instanceof DelegationRestrictionType){


List<DelegateType> delegateTypesList = ((DelegationRestrictionType)condition).getDelegate();


for (DelegateType delegateType : delegateTypesList) {


NameIDType nameIDType = delegateType.g
etNameID();


//other GFIPM Entity ID validation code goes here


}//for delegateType


}//if instanceof DelegationRestrictionType

}//for condition


/**


* Constructs an <code>Delegate</code> element from an existing XML block.


*


* @param DelegateElement A



* <code>org.w3c.dom.Element</code> representing DOM tree for


* <code>Delegate</code> object.


* @exception SAMLException if it could not process the


* <code>org.w3c.dom.Element</code> properly, implying that there


* is an error in the sender or in the element definition.


*/


public static DelegateType fromElement(org.w3c.dom.Element element)


<dependency>


<groupId>edu.gatech.gtri.gfipm.model2</groupId>


<artifactId>m2lib</artifactId>


<version>1.0
-
SNAPSHOT</version>


</dependency>


24


3.1.3

Information Exchange
Se
rvice Contract
Implementation Library

The
Information Exchange Service Contract Implementation Library

provides developers with reusable
JAXB

[JAXB]

and JAX
-
WS
[JAXWS]
service contract
interface and
implementation classes.

The project
uses the
wsimport

[
WSIMPORT
] goal of the “
jaxws
-
maven
-
plugin


to generate
JAX
-
WS portable artifacts,
such

as: Service Endpoint Interface

(
SEI)
, and
JAXB generated value types (mapped
J
ava classes from
schema types)
.
The
Module Service Contract WSDL files do not contain SLA
security policy content.

The f
ollowing customizations are used
:



JAXB Content Objects (src/jaxws/schema
-
bindings.xml )

o

places all
CommercialVehicleCollisionMessageSchema.xsd

schema based classes
in the

gov.niem.ws.sample.cvc.jaxb.msg

package

o

places all
Comm
ercialVehicleCollisionExchangeSchema.xsd

schema based classed
in the

gov.niem.ws.sample.cvc.jaxb.iepd

package



Service Endpoint Interface (SEI)

(src/jaxws/wsdl
-
bindings.xml)

o

places all
SEI
generated classes
in the

gov.niem.ws.sample.cvc.jaxws

package



Library Packaging (
src/jaxws/jaxwsjar.xml
)



JAXBContext auxiliary loader file (
src
\
main
\
resources
\
gov
\
niem
\
ws
\
sample
\
cvc
\
jaxb
\
jaxb.index
)

The d
iagram below reflects
the
relationship between
library artifacts and
the
Service Contract.



Figure
11
: Service Contract Implementation Library

To add
the
GFIPM Service Contract Information Exchange Implementation library to your application
,

include
the appropriate
Maven dependency in your POM file
as follows
:


25


3.1.4

GFIPM WS S2S Consumer
-
Provider (Model 1) Implementation

This section covers
the
implementation of the components that are specific to the GFIPM WS S2S
Consumer
-
Provider Service Interaction Profile (Model 1)

implementation.

3.1.4.1

WSC Implementation

(Model 1)

The WSC in the GFIPM WS S2S Consumer
-
Provider SIP is a simple command line client application. The
WSC uses

the

Information Exchange
Se
rvice Contract
Implementation Library

to create a connection to
the WSP service. To determine the SLA policy for the WSP, the WSC retrieves the WSDL from the WSP,
sets
the
proper Service Endpoint for WSP service (listed in the GFIPM CTF), and then invokes the WSP
service.

The WSC is configured through the Client
-
Side WSIT [WSIT] configuration file “
wsit
-
client.xml


located
under “
src
\
main
\
resources
\
META
-
INF
\
” directory. T
he Client
-
Side WSIT configuration file imports a
separate configuration file for the WSP as shown on the code snippet below:


The configuration for the connection to the WSP (“
src
\
main
\
resources
\
META
-
INF
\
CommercialVehicleCollisio
nWebserviceIntf.xml
”) includes settings for the WSC private certificate
that should be used for the connection to the WSP and specifies WSP public certificate as follows:



<dependency>


<groupId>edu.gatech.gtri.gfipm.model2</groupId>


<artifactId>m2contract</artifactId>


<!
--

classifiers used with Maven Assembly Plugin to specify subset of above artifact needed
--
>


<classifier>lib
-
jaxws</classifier>


<
version>1.0
-
SNAPSHOT</version>


</dependency>

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" name="mainclientconfig">


<import
location="CommercialVehicleCollisionWebserviceImpl.xml"
namespace="urn:examples.com:techniques:iepd:commercialVehicleCollision:ws:2.0"/>

</definitions>


<wsp:Policy wsu:Id="CalculatorServicePortBindingPolicy">


<wsp:ExactlyO
ne>


<wsp:All>


<!
--

WSP Server identity
--
>


<scl:TrustStore wspp:visibility="private" peeralias="curewspm1"


storepass="changeit" type="JKS" location="curewscm1
-
cacerts.jks"/>



<!
--

WSC Client identity
--
>


<scl:KeyStore wspp:visibility="private" alias="curewscm1"


storepass="changeit" type="JKS" location="curewscm1
-
keystore.jks"/>


</wsp:All>


</wsp:Ex
actlyOne>


</wsp:Policy>


26

Caching of the WSDL files to prevent extra WSDL queries is possible through the use of the

src
\
main
\
resources
\
META
-
INF
\
jax
-
ws
-
catalog.xml”

configuration file.

The WSC (“
gov.niem.ws.sample.cvc.client.CommercialVehicleCollisionC
lient
”) initializes the service
connection to WSP (cvcPort), sets proper Service Endpoint, and invokes a service call as shown on the
code snippet below:


For the details on the WSC execution and running tests see the Readme.txt installation instructions file
in the GWSS2SPSI distribution package.

3.1.4.2

WSP Implementation

(Model 1)

The WSP is responsible
for accepting a request from a WSC listed in the GFIPM CTF. The WSP must
conform to GFIPM WS S2S Consumer
-
Provider (Model 1) SIP requirements.

The WSP is deployed under the following URL:
https://
curewspm1:8181/m1wsp/services/cvc


The WSP exposes the
Service Contract

described earlier, and is using the
Information Exchange
Se
rvice
Contract
Implementation Library
. The WSP Service Contract is stated in the following files:


The WSP includes a preconfigured trust keystore and private keystore:


3.1.4.2.1

WSP SLA Implementation

The WSP uses an SLA security policy stipulated in the “
CommercialVehicleCollisionWebserviceIntf.wsdl
”.
The SLA for

a WSP is subject to the GFIPM WS S2S Consumer
-
Provider SIP specification requirements

CommercialVehicleCollisionPortType cvcPort;


CommercialVehicleCollisionWebService cvsWebService;


MTOMFeature mtomFeature = new MTOMFeature(true);


cvsWebService = new CommercialVehicleCollisionWebService(new URL(wsdlUrl),


new QName("urn:examples.com:tech
niques:iepd:commercialVehicleCollision:ws:2.0",


"CommercialVehicleCollisionWebService"));


cvcPort = cvsWebService.getCommercialVehicleCollisionPort(new MTOMFeature(true));


Map<String, Object> requestContext = ((BindingProvi
der) cvcPort).getRequestContext();


requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, sepUrl);


GetDocumentResponseType getDocumentResponseType =



cvcPort.getDocument(getDocumentRequestType);




src/wsdl/CommercialVehicleCollisionExchangeSchema.xsd


src/wsdl/CommercialVehicleColli
sionMessageSchema.xsd


src/wsdl/CommercialVehicleCollisionWebserviceImpl.wsdl


src/wsdl/CommercialVehicleCollisionWebserviceIntf.wsdl


src/main/resources/META
-
INF/curewspm1
-
cacerts.jks


src/main/resources/META
-
INF/curewspm1
-
keystore.jks


27

and is included in the
Attachment F: Sample SLA Security Policy for WSP Model 1
. The WSP SLA uses
mutual

certificates for authentication,

message integrity
,

and confidentiality protection.

3.1.4.2.2

Certificate Validation

The WSP provides a certificate validator configured through the service WSDL
(
CommercialVehicleCollisionWebserviceIntf.w
sdl
) as follows:


The custom certificate validator
class,

gov.niem.ws.sample.cvc.service.GFIPMCertificateValidator

,

provides X
.
509 certificate validation.
The certificate validator
uses the “
src
\
main
\
resources
\
gfipm
-
security
-
env.pro
perties
” properties file to initialize and use

a keystore
that is
shipped with the
application.
Furthermore
,
the
GFIPMCertificateValidator

class

provides

certificate validation according
to the GFIPM WS S2S Consumer
-
Provider SIP normative conformance requirements in the S2S section
8.1.2.
T
he
code snippet below shows
how to validate

the certificate against the GFIPM CTF

and
how to
obtain an access control
decision

based on the WSC Entity attributes listed in the GFIPM CTF.

Note that the code in this snippet is hard
-
coding an access control policy. In production environment, it
is recommended that the access control decision making be abstracted out into
a separate Policy
Decision Point (PDP) component using an access control framework such as the XACML framework. See
the Global Privacy Policy Technical Framework
[
GPPTF] for more information about integrating with an
access control framework.

The access c
on
trol decision

could
also
be
obtained

in the actual WSP service implementation

as show
n

in the chapter

3.1.4.2.3

on

WSP Service Implementation
.



<sc:ValidatorConfiguration wspp:visibility="private" revocationEnabled="false">


<sc:Validator name="certificateValidator"



c
lassname="gov.niem.ws.sample.cvc.service.GFIPMCertificateValidato
r"/>


</sc:ValidatorConfiguration>


28


3.1.4.2.3

WSP Service Implementation

The WSP service is implemented by the
CommercialVehicleCollisionWebServiceImpl

class located in the

src
/
main
/
java
/
gov
/
niem
/
ws
/
sample
/
cvc
/
service
” directory.

The service implementation class provides a sample code
for
obta
ining
the
access control decision

based
on the invoked method and credentials

of the WSC that attemp
t
s to access the functionality
.

Note that
the code is hard
-
coding an access control policy. In production environment, it is recommended that
the access c
ontrol decision making be abstracted out into a separate Policy Decision Point (PDP)
component using an access control framework such as the XACML framework. See the Global Privacy
Policy Technical Framework
[
GPPTF] for more information about integrating
with an access control
framework.


The “
GFIPMAuthorizationProvider
” class provides

a

sample implementation
for obtaining the access
control decision

based on the WSC attributes
in the GFIPM CTF
and is implemented as follows:


private static TrustFabric tf =
TrustFabricFactory.getInstance();


private boolean isAuthorized(X509Certificate certificate) {


String entityId = tf.getEntityId(certificate);


if (entityId == null) {


log.log(Level.WARNING, "Certificate used by the peer is not in the GFIPM Trust Fabric: " +
certificate.getSubjectDN());


return false;


}


//GFIPM Entity (entityId) should belong to WSC only


//Add access control decisions based on the GFIPM CTF entityAttributes


if (tf.isWebServiceConsumer(entityId)) {


String ownerAgencyCountryCode = tf.getGfipmEntityAttribu
te(entityId,
"gfipm:2.0:entity:OwnerAgencyCountryCode");


//As an example current WSP SLA currently allows only country codes US and VQ


if (!(("VQ".compareToIgnoreCase(ownerAgencyCountryCode) != 0) ||
("US".compareToIgnoreCase(ownerA
gencyCountryCode) != 0))) {


log.log(Level.WARNING, "WSP: WSC Entity connecting to this WSP should have
OwnerAgencyCountryCode as VQ or US. Retrieved agency ID from TF is: " +
ownerAgencyCountryCode);


return false;



}


} else {


log.log(Level.WARNING, "Entity connecting to this WSP should be listed as WSC in the GFIPM
Trust Fabric, entity id :" + entityId);


return false;


}


return true;


}//isAuthoriz
ed

GFIPMAuthorizationProvider.isAuthorized(GFIPMAuthorizationProvider.ge
tCurrentMethodName(),
wsContext
);



29


The class also provides business logic operations that are not subject to GFIPM WS S2S requirements.

3.1.5

GFIPM WS S2S User
-
Consumer
-
Provider (Model 2/Model 8) Implementa
tion

This section covers implementation of the components that are specific to the GFIPM WS S2S User
-
Consumer
-
Provider Service Interaction Profile (Model 2/Model 8) implementation.

3.1.5.1

IDP
/ADS
STS

Implementation

(Model 8)

In the sample implementation users are

authenticated through Identity Provider Security Token Service
(
IDP

STS).
The
IDP

STS issues SAML

2.0 Assertion

to authenticated users
. The Assertion

uses

GFIPM
Metadata attributes
.
The sample i
mplementation also includes
an
Assertion Delegate Service
(A
DS

STS)

that issues SAML 2.0 Assertion tokens based on the original
SAML
token obtained by the user from
IDP

STS

during authentication phase
.
The n
ew SAML
token

include
s

all
GFIPM
attributes

from the original
SAML token

and add
s

SAML Delegation information
as described in GFIPM WS S2S User
-
Consumer
-
Provider SIP 8.8
.
The re
-
i
ssued
SAML
token
is

used
by the
WSC
to submit
request
s

to
the
WSP.

An
IDP

STS
and
an
ADS STS share the same code for
the
SAML token
generation.
While the ID
P STS
provides the GFIPM attribute generation, the ADS STS copies attributes from the presented SAML
Assertion token. The IDP STS and ADS STS
expose different SLA policies and have different
authentication mechanisms. Message validation also differs depen
ding on functional requirements of

private static TrustFabric tf =
TrustFabricFactory.getInstance();


public static boolean isAuthorized(String methodName,WebServiceContext wsContext) {


boolean isAuthorized = false;


try {


if (SubjectAccessor.getRequesterSubject(wsContext) != null) {


for (Iterator<Object> it =
SubjectAccessor.getRequesterSubject(wsContext).getPublicCredentials().iterator(); it.ha
sNext();) {


Object publicCredentialsObject = it.next();


if (publicCredentialsObject instanceof X509Certificate) {


X509Certificate subjectX509Certificate = (X509Certificate) publicCredentialsOb
ject;


//Delegate ID is determined from Entity Certificate.


String wscId = tf.getEntityId(subjectX509Certificate);


//Provide authorization decision for the WSC to execute method



if (tf.isWebServiceConsumer(wscId) &&
"gov.niem.ws.sample.cvc.service.CommercialVehicleCollisionWebServiceImpl.getDocument".equal
s(methodName)) {


//In this example any WSC from the CTF is authorized to execute
this method


isAuthorized = true;


}}}}


} catch (XWSSecurityException ex) {


logger.log(Level.SEVERE, "Unable to get UserPrincipal", ex);


} catch (Exception e) {


logge
r.log(Level.SEVERE, "Unknown exception", e);


}


return isAuthorized;


}


30

the
IDP

or the ADS.

The

IDP

and
the ADS

endpoint
s

implement
the
WS
-
Trust 1.3 specification based on
the S2S baseline requirements for GRA conformance.

To support

the

GlassFish JSR
-
196 deployment and
HTTPS (HTTP over TLS
1.x)
,
IDP
/ADS STS certificates
are installed in
the
default Glassfish’s domain trust store (
/var/opt/glassfish/domain1/config/cacerts.jks
)
and private keystore (
/var/opt/glassfish/domain1/config/keystore.jks
).

For the details on STS
deployment s
ee
the
installation documentation Readme.txt.

3.1.5.1.1

Token Generation

The
SAML Token generation is performed by
the

gov
.
niem
.
ws
.
sample
.
cvc
.
sts
.
GFIPMSTSTokenProvider

class
, which
is located
in the


src
/
main
/
java
/
gov
/
niem
/
ws
/
sample
/
cvc
/
sts
” directory.
This c
lass extend
s

com.sun.xml.ws.security.trust.impl.DefaultSAMLTokenProvider
” class and implements
the

com.sun.xml.ws.api.security.trust.STSTokenProvider
” interface.
This c
lass overrides
the

generateToken
” method in “
DefaultSAMLTokenProvider
”.


The
STS Token Provider is configured through
the

com.sun.xml.ws.api.security.trust.STSTokenProvider

file located
in the


src
/
main
/
resources
/
META
-
INF
/
services
” directory
.


For
the
token type
"
http://docs.oasis
-
open.org/wss/oasis
-
wss
-
saml
-
token
-
profile
-
1.1#SAM
LV2.0
"
,

the
Token Provider
implementation
manually sets subject confirmation method to

urn:oasis:names:tc:SAML:2.0:cm:sender
-
vouches
”.

The f
ollowing code snippet
shows how to check

whether

an

OnBehalfOf r
equest was submitted to the
STS

and

how to retrieve
the
OnBehalfOf
token.
The c
ode also shows how to obtain
the
WSC
intermediary entity ID (or
Delegate Id
)

from
the
GFIPM CTF based on the
certificate from the
requestor
.


private static TrustFabric tf = TrustFabricFactory.getInstance();

public void generateToken(IssuedTokenContext ctx) throws WSTrustException {


Boolean isOnBehalfOf =
Boolean.parseBoolean(ctx.getOthe
rProperties().get("OnBehalfOf"));


//delegateId is an entity which is requesting token