REST/SOAP Harmonization proposal for Identity-based Web-Services

ovenforksqueeSecurity

Nov 3, 2013 (3 years and 5 months ago)

49 views


Kantara Initiative
Draft
R
eport

www.kantarainitiative.org



1


1


2


3


4

REST/SOAP Harmonization proposal

for
5

Identity
-
based Web
-
Services

6


7

Version:




0.
4

8

Date:



201
2
-
10
-
16

9

Editor:



Gaël Gourmelen, Orange

10

Contributors:

11

Fulup

Ar Foll, Oracle

12

Ingo Friese, Deutsche Telekom AG

13

Jonas

Högberg, Ericsson
Keith Uber, Ubisecure Solutions, Inc.

14


15

Status:

This document is a
Kantara Initiative
Draft
Report

that

has been
approved by
16

the
Telecommunications Identity

WG/DG (see section 3.9 and
4 of the
Kantara Initiative
17

Operating Procedures)

18


19

Abstract:

20

The aim of this document is
to
propose a solution in order to
provid
e

an easy and
21

consistent way for both Web Service Clients and Web Service Providers to respectively
22

invoke or expose Identity
-
based APIs through both REST and SOAP flavors
, taking into
23

account both legacy aspects and growing adoption of the OAuth standard.

24


25


26

Filename:

kantara
-
draft
-
report
-
tiwg
-
REST
-
SOAP
-
harmonization
-
proposal
-
0.
4

27



28

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



2

Notice:

29

T
h
i
s

do
c
u
me
n
t

h
a
s

b
e
e
n

p
r
e
p
a
r
e
d

b
y

P
a
r
t
i
c
i
p
a
n
t
s

o
f

K
a
n
t
a
ra

I
n
iti
a
t
i
v
e
.

P
e
r
m
i
s
s
i
o
n

i
s

30

h
e
r
e
b
y

g
r
a
n
t
e
d

t
o

u
s
e

t
h
e

d
o
c
u
me
n
t

s
o
l
e
l
y

f
o
r

t
h
e

p
u
r
po
s
e

o
f

i
m
p
l
eme
n
t
i
n
g

t
h
e

31

S
p
e
c
i
f
i
c
a
t
i
o
n
.

N
o r
i
g
h
t
s

a
r
e

g
r
a
n
t
e
d

t
o

p
r
e
p
a
r
e

d
e
r
i
v
a
t
i
v
e

w
o
r
k
s

o
f

t
h
i
s

S
p
ec
i
f
i
c
a
t
i
o
n
.

32

E
n
t
it
i
e
s

s
e
e
k
i
n
g

p
e
r
m
i
s
s
i
o
n

t
o

r
e
p
r
o
d
u
c
e

p
o
r
t
i
on
s

o
f

t
h
i
s

d
o
c
u
m
e
n
t

f
o
r

o
t
h
e
r

u
s
e
s

m
u
s
t

33

c
o
n
t
a
c
t

K
a
n
t
a
ra

I
n
i
ti
a
t
i
v
e

t
o

d
e
t
e
r
m
i
n
e

w
h
e
t
h
e
r

a
n

a
p
p
r
o
p
r
i
a
t
e

l
i
c
e
n
s
e

f
o
r

s
u
c
h

u
s
e

i
s

34

a
v
a
il
a
b
l
e
.

35


36


I
m
p
l
e
m
e
n
t
a
t
i
o
n

o
r

u
s
e

o
f

c
e
r
t
a
i
n

e
l
eme
n
t
s

o
f

t
h
i
s

do
c
u
me
n
t

m
a
y

r
e
q
u
i
re

l
i
ce
n
s
e
s

und
e
r

37

t
h
i
r
d

p
a
r
t
y

i
n
t
e
l
l
e
c
t
u
a
l

p
r
o
p
e
r
t
y

r
i
g
h
t
s
,

i
n
c
l
u
d
i
n
g

w
i
t
ho
u
t

l
i
m
i
t
a
t
i
o
n
,

p
a
t
e
n
t

r
i
g
h
t
s
.
T
h
e

38

P
a
r
t
i
c
i
p
a
n
t
s

o
f

a
n
d

a
n
y

o
t
h
e
r

c
o
n
t
r
i
b
u
t
o
r
s

t
o

t
h
e

S
p
e
c
i
f
i
c
a
t
i
o
n

a
r
e

n
o
t

a
n
d

s
h
a
l
l

n
o
t

b
e

h
e
l
d

39

r
e
s
pon
s
i
b
l
e

i
n

a
n
y

m
a
n
n
e
r

f
o
r

i
d
e
n
t
i
f
y
i
n
g

o
r

f
a
il
i
n
g

t
o

i
d
e
n
t
i
fy

a
n
y

o
r

a
l
l

s
u
c
h

t
h
i
r
d

p
a
r
t
y

40

i
n
t
e
l
l
e
c
t
u
a
l

p
r
o
p
e
r
t
y

r
i
g
h
t
s
.
T
h
i
s

S
p
e
c
i
f
i
c
a
t
i
o
n

i
s

p
r
o
v
i
d
e
d

"
A
S

I
S
,
"

a
n
d

n
o

P
a
r
t
i
c
i
p
a
n
t

i
n

41

t
h
e

K
a
n
t
a
ra

I
n
iti
a
t
i
v
e

m
a
k
e
s

a
n
y

w
a
rr
a
n
t
y

o
f

a
n
y

k
i
n
d
,

e
x
p
r
e
ss
e
d

o
r

i
m
p
l
i
e
d
,

i
n
c
l
u
d
i
n
g

a
n
y

42

i
m
p
l
i
e
d

w
a
rr
a
n
t
i
e
s

o
f

m
e
r
c
h
a
n
t
a
b
i
li
t
y
,

n
o
n
-
i
n
fr
i
ng
em
e
n
t

o
f

t
h
i
r
d

p
a
r
t
y

i
n
t
e
l
l
e
c
t
u
a
l

p
r
o
p
e
r
t
y

43

r
i
g
h
t
s
,
a
n
d

f
i
t
n
e
s
s

f
o
r

a

p
a
r
t
i
c
u
l
a
r

p
u
r
po
s
e
.

I
m
p
l
em
e
n
t
e
r
s

o
f

t
h
i
s

S
p
ec
i
f
i
c
a
t
i
o
n

a
re

a
d
v
i
s
e
d

44

t
o

r
e
v
i
e
w

t
h
e

K
a
n
t
a
ra

I
n
iti
a
ti
v
e

s

w
e
b
s
i
t
e

(
h
tt
p
:
/
/
www
.
k
a
n
t
a
r
a
i
n
i
t
i
a
t
i
v
e
.
o
r
g
)

f
o
r

45

i
n
f
o
r
m
a
t
i
o
n

c
o
n
c
e
r
n
i
n
g

a
n
y

N
ece
s
s
a
ry

C
l
a
i
m
s

D
i
s
c
l
o
s
u
r
e

N
o
t
i
ce
s

t
h
a
t

h
a
v
e

b
e
e
n

r
e
ce
i
v
e
d

46

b
y

t
h
e

K
a
n
t
a
ra

I
n
iti
a
t
i
v
e

B
o
a
r
d

o
f

T
r
u
s
t
e
e
s
.

47


48

T
h
e

c
o
n
t
e
n
t

o
f

t
h
i
s

d
o
c
u
m
e
n
t

i
s

c
o
py
r
i
g
h
t

o
f

K
a
n
t
a
ra

I
n
i
ti
a
t
i
v
e
.

©

2
01
2

K
a
n
t
a
ra

I
n
i
ti
a
t
i
v
e
.

49

50

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



3

Contents

51


52

1

INTRODUCTION

................................
................................
................................
..........
4

53

2

PROPOSAL

................................
................................
................................
....................
6

54

2.1

Principles
................................
................................
................................
.....................
6

55

2.2

WS
-
Security OAuth Access Token profile

................................
................................
.
7

56

2.3

Use of the ID
-
WSF Basic SOAP Binding
................................
................................
...
7

57

3

REFERENCES

................................
................................
................................
...............
9

58

3.1

Informative
................................
................................
................................
................
10

59


60

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



4

1

INTRODUCTION

61

REST (Representational State

Transfer) and SOAP (Simple Object Access Protocol) are
62

two different approaches for the implementation of Web Services.

63

REST is Resource
-
oriented whereas SOAP is Activity
-
oriented. The type of application
64

and the service it offers determines if REST or SO
AP is more suitable ;
though one can
65

still argue that we can use SOAP or REST indifferently for these two kinds of services
66

(with a bit of tweaking)
.

67

To acknowledge the fact that both approaches can still make sense, here are some criteria
68

that clearly dis
tinguish in which case REST or SOAP is still more appropriate:

69

REST

may be appropriate when



The Web Services are completely
stateless.



A caching infrastructure can be
leveraged for performance, and the
service is to a large extent static.



The interface can be exposed through
standard
CRUD operations (Create,
Read, Update, and Delete).



The Web Service Client and the Web
Service Provider have a mutual
understanding of the context and
content being passed along.



Client applications are browser
-
based
implementations (e.g. based on AJAX).

SOAP

may be appropriate when



The Web Services are stateful and
dynamic.



A formal contract must be established
to describe the interface that the Web
Service offers (WSDL).



Advanced security patterns (including
b
ut not limited to e
nd
-
to
-
end message
-
level security
) are required.



The architecture must address complex
nonfunctional requirements such as
Transaction, Security, Addressing,
Trust, Coordination and so on
. With
REST, developers must build this
plumbing int
o the application layer
themselves.



Operations (actions) are specific to the
service and go beyond basic CRUD
operations.



The architecture needs to handle
asynchronous processing and
invocation.


70

Even if REST is more and more used mainly as it is simpler to implement, the
71

characteristics of SOAP (extreme definition and data type declaration with XML
72

Schemas


type, value ranges, etc
) correspond to what we are used to in telecom
73

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



5

standards

(e.g.: OMA

Parlay X APIs, OMA SUPM, 3GPP GUP, …)
. That explains why
74

some Telco APIs are still specified in either or both flavors.

75

L
egacy aspects
will also lead to situations where telecommunication operators will
76

expose both REST and SOAP APIs

(e.g.: some Orange AP
Is opened to partners such as
77

Billing are
still
SOAP APIs whereas others such as User Profile are REST APIs)
.

78


79

In the case of Identity
-
based Web Services, the support of both REST and SOAP APIs
80

brings however more complexity for
both
Web Service Provider
s
and Web Service
81

Clients

if
they

need to support different Identity
-
based Web Services frameworks to
82

handle common functions related to identity management, security, authorization... These
83

functions are required to ensure that the access to the exposed res
ources is well
-
84

authorized for the requesting Web Service Client, acting on behalf of an end
-
user.

85

In the SOAP area,
frameworks such as
Liberty ID
-
WSF provide protocols and core
86

components (ID
-
WSF Discovery Service and Interaction Service notably) to handle

all
87

these aspects in conjunction with a Federation Framework.

88

In the REST area, the OAuth specifications handle these aspects through the delivery of
89

an Access Token delivered to an authenticated Web Service Client

upon approval by the
90

end
-
user.

91


92

As OAuth

is today more and more adopted in the REST area
1

(more than ID
-
WSF in the
93

SOAP area), the aim of this document is to describe how it can also be used to secure the
94

access to SOAP APIs and thus providing an easy and consistent way for
both Web
95

Service Clients and
Web Service Providers to
respectively invoke or
expose Identity
-
96

based APIs through both REST and SOAP flavors.

97


98




1

Important actors like
Facebook, Google,
Microsoft, Twitter, and Yahoo already deployed OAuth
-
compliant APIs.

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



6

2

PROPOSAL

99


100

2.1

Principles

101

The proposal is here to
rely on OAuth

mechanisms

to allow the user to control the access
102

to hi
s/her exposed resources and grant authorizations to requesting services (Web Service
103

Clients) in both REST and SOAP contexts
2
.

104

Concretely, a WS Consumer/Client has to implement the protocol flows defined in
105

[OAuth2]

(
or [OpenIDConnect]

or [OAuth2S
aml
2]
)

to

obtain an «OAuth Access Token».

106

These tokens represent an authorization issued to the WS Consumer/Client with specific
107

scopes
(
potentially
multiple APIs
exposed by the telecommunication operator
in our
108

context)
and durations of access, granted by the
resource owner (user), and enforced by
109

the resource server and authorization server.

110


111


112




2

Note that a proposal
also
exists to extend the
usage of the
OAuth
framework

for
non
-
HTTP
-
based
protocols
:
http://tools.ietf.org/id/draft
-
mills
-
kitten
-
sasl
-
oauth
-
04.txt
. This

can be seen as complementary to
the approach proposed in our document for REST and SOAP APIs in order to
provide

even
further
harmonization
between HTTP
-
based and non
-
HTTP
-
based protocols
.

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



7


113

This token is then conveyed in both REST (as specified in [OAuth2]) and SOAP calls.
114

For SOAP calls,
the proposal is to convey
the OAuth Access token in a <wsse:Securit
y>
115

SOAP header as profiled in the following chapter (only OAuth2 Bearer Access tokens are
116

considered at this stage)
. This would be the minimal step

in order to
be able to
reuse
117

standard XML Signature mechanisms to securely
bind the OAuth Access Token to th
e
118

SOAP message.

A further step would be to support the ID
-
WSF Basic SOAP Binding

119

[LIB
-
Basic
-
SOAP]

to benefit from additional messaging
-
specific f
eatures
.

120


121

2.2

WS
-
Security OAuth Access Token profile

122

The <wsse:BinarySecurityToken> element is introduced in the

WSS: SOAP Message
123

Security


[WSS] document as a way of conveying any encoded binary security token in a
124

<wsse:Security> SOAP header.

125

The use of this element to convey OAuth Bearer Access tokens mainly requires the
126

definition of a new value ("
#OAuth2
-
Bearer
"



standard value and associated

127

namespace to be defined

in relevant standard organization
, for example OASIS
) for its
128

ValueType attribute in order to clearly distinguish OAuth Bearer Access tokens from
129

other types of binary tokens.

130

<wsse:Security mustUnd
erstand="1">


<wsu:Timestamp wsu:Id="ts">


<wsu:Created>2011
-
05
-
17T04:49:17Z</wsu:Created >


</wsu:Timestamp>


<wsse:BinarySecurityToken ValueType="#OAuth2
-
Bearer"

EncodingType="wsse:Base64Binary">
7Fjfp0ZBr1KtDRbnfVdmIw
<
/wss
e:BinarySecurityToken>

</wsse:Security>


131

Depending on agreements between Web Service Client and Web Service Provider, the
132

exchanged SOAP messages can be integrity protected by implementing the signature
133

mechanisms defined in [WSS].

134


135

2.3

Use of the ID
-
WSF
Basic SOAP Binding


136

The ID
-
WSF Basic SOAP Binding
[LIB
-
Basic
-
SOAP]
provides a profile that is intended
137

to be a basic, scaled
-
down version of the Liberty ID
-
WSF 2.0 SOAP Binding
138

Specification and Security Mechanisms 2.0.

139

As specified in [LIB
-
Basic
-
SOAP], t
h
e following header blocks MUST be included in
140

the SOAP header:

141

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



8



<wsa:MessageID>

142



<wsa:RelatesTo> (mandatory on response)

143



<wsa:Action>

144



<sbf:Framework>

145



<wsse:Security>

146

The following headers MAY be included in the SOAP header:

147



<wsa:To>

148

[LIB
-
Basic
-
SOAP]

can be used as a basis to define Identity
-
based SOAP Web Service
s

149

except that, in our context,
it MUST also support the WS
-
Security OAuth Access
150

Token

profile

defined above.

151

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



9

3

CONCLUSION

152

This document
propose
s

a
simple
solution in order to provide an easy
and consistent way
153

for both Web Service Clients and Web Service Providers to respectively invoke or
154

expose Identity
-
based APIs through both REST and SOAP flavors
. It

enables APIs
155

provider
s

to rely on OAuth to secure the access to their APIs in
a

uniform wa
y with
156

minimal impacts on existing SOAP APIs (legacy aspects)
.

157


158

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



10

4

REFERENCES

159

4.1

Informative

160

[OAuth2]

Hammer
-
Lahav, E., Recordon, D., and D. Hardt, "The
OAuth 2.0 Authorization Protocol", draft
-
ietf
-
oauth
-
v2
-
2
3

(work in progress), J
anuary

201
2
.

[OpenIDConnect]

Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,”
aecem扥r ㈰ㄱO

[lAuth㉓aml㉝

M潲tim潲eⰠC⸬•pAMi ㈮〠Oearer Asserti潮 mr潦iles f潲
lAuth ㈮〢Ⱐ摲aft
J
ietf
J
潡畴h
J
samlO
J
扥arer
J
〸MEw潲欠in

灲潧
ress)ⰠAugust ㈰ㄱO

[tpp]

“Web Services Security: SOAP Message Security 1.1”,
lApfp⁓tan摡r搬dㄠ1e扲uary ㈰〶O

[ifB
J
Basic
J
plAm]

“Liberty ID
J
tpc
Basic
SOAP Binding Specification”,
versi潮
1
⸰Ⱐ.i扥rty Alliance mr潪ect


ㄶ1


162

163

REST/SOAP Harmonization proposal

Version:
0
.
4

for Identity
-
based Web
-
Services


Kantara Initiative
Draft
Report

www.kantarainitiative.org



11

Revision History

164


165

0.1

Initial
draft

0.2

Integration of comments received from the Kantara Initiative
Telecommunication Identity Work Group

0.3

Additional comments from the Kantara Initiative Telecommunication
Identity Work Group

0.4

Approval by the Kantara Initiative Telecommunicati
on Identity Work
Group


166


167


168


169


170


171


172


173


174


175


176