WHITE PAPER
Building an Ecosystem for API Security
January 2014
………………………………………………………………………………………………………….
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
2 WHITE PAPER
Table of Contents
1. Introduction 3 2. What is OAuth? 3 3. OAuth 1.0 vs. OAuth 2.0 - What's the Difference Between the Two? 3 4. Bearer Token Profile 4 5. OAuth 2.0 4 6. MAC Token Profile 6 7. SAML 2.0 Bearer Assertion Profile 8 8. JSON Web Token (JWT) Bearer Profile 9 9. Improvements 9 10. Token Introspection 10 11. Server Metadata 10 12. User-Managed Access 11 13. Token Revocation 12 14. Resource Owner Initiated Delegation 13 15. Token Chaining 13 16. OAuth 2.0 Vs. OpenID Connect 14 17. Fine-Grained Access Control 15 18. API Security Ecosystem 18
18.1. Key Manager 18 18.2 API Gateway 18 18.3 WSO2 Identity Server (WSO2 IS) 19 18.4 WSO2 API Manager 20 18.5 WSO2 Business Activity Monitor (WSO2 BAM) 20
19. Patterns 21 19.1. Accessing an API Secured with OAuth, on behalf of a User Logged into the System, with SAML2 Web SSO 21 19.2. Accessing an API Secured with OAuth on behalf of a User/System Authenticated to a SOAP Service with WS-Trust 22 19.3. Fine-Grained Access Control with XACML 23
20. References 24
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
3 WHITE PAPER
1. Introduction
Enterprise API adoption has gone beyond predictions. APIs have become the 'coolest' way
of exposing business functionalities to the outside world. Both your public and private APIs
need to be protected, monitored, and managed. This white paper focuses on API security.
There are many options available that could be very confusing. When should you select
one over another is a question that frequently comes up – and you need to cautiously
identify and isolate the tradeoffs.
Security is not an afterthought. It has to be an integral part of any development project. The
same applies to APIs as well. API security has evolved significantly in the past five years.
The growth of standards to date has been exponential. OAuth is the most widely adopted
standard, and is possibly now the de-facto standard for API security
2. What is OAuth?
The web community (e.g. Google, Yahoo, and Flicker) banded together to solve a
perplexing security challenge: How to authorize user access to resources and delegate
authorization decisions across trusted parties. OAuth is a security standard based on many
pre-OAuth vendor specific protocols such as Google AuthSub, Yahoo BBAuth, and Flicker
Auth.
3. OAuth 1.0 vs. OAuth 2.0 — What"s the Difference Between the Two?
OAuth 1.0 is a standard, built for identity delegation. OAuth 2.0 is a highly extensible
authorization framework. The best selling point in OAuth 2.0 is its extensibility by being an
authorization framework.
OAuth 1.0 is coupled with signature-based security. Although it has provisions to use
different signature algorithms, it's still signature based. One of the key negative comments
on OAuth 1.0 is the burden enforced on OAuth clients for signature calculation and
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
4 WHITE PAPER
validation. This is not a completely valid argument. This is where we need proper tools to
the rescue. Why does an application developer need to worry about signature handling?
Delegate that to a third-party library and stay calm. If you think OAuth 2.0 is better than
OAuth 1.0 because of the simplicity added through the OAuth 2.0 Bearer Token profile
(against the signature based tokens in 1.0) – you've been misled.
To re-iterate this point, the biggest advantage of OAuth 2.0 is its extensibility. The core
OAuth 2.0 specification is not tightly coupled with a token type. There are several OAuth
profiles discussed under the IETF OAuth working group at the moment. The Bearer token
profile is already a proposed IETF standard - RFC 6750.
4. Bearer Token Profile
The Bearer token profile is currently the most widely used for API Security. The access
token used under the Bearer token profile is a randomly generated string. Anyone who is in
possession of this token can use it to access a secured API. In fact, that is what its name
implies too. The protection of this token is facilitated through the underlying transport
channel via TLS. TLS only provides the security while in transit. It"s the responsibility of the
OAuth Token Issuer (or the Authorization Server) and the OAuth client to protect the
access token while being stored. In most cases, the access token needs to be encrypted.
Moreover, the token issuer needs to guarantee the randomness of the generated access
token, and it has to be long enough to exhaust any brute-force attacks.
5. OAuth 2.0
OAuth 2.0 has three major phases
(to be precise, Phase 1 and Phase 2 could overlap based on the grant type).
1. Requesting an Authorization Grant
2. Exchanging the Authorization Grant for an Access Token
3. Access the resource with the Access Token
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
5 WHITE PAPER
OAuth 2.0 core specification does not mandate any access token type. In addition, the
requester or the client cannot decide which token type it needs. It"s purely up to the
Authorization Server to decide which token type is to be returned in the Access Token
response, which is Phase 2.
The access token type provides the client the information required to successfully utilize
the access token to make a request to the protected resource (along with type-specific
attributes). The client must not use an access token if it does not understand the token
type.
Each access token type definition specifies the additional attributes (if any) sent to the
client together with the "access_token" response parameter. It also defines the HTTP
authentication method used to include the access token when making a request to the
protected resource.
For example, the following is what you get for the Access Token response irrespective of
which grant type you use (to be precise, if the grant type is client credentials, there won"t
be any refresh_token in the response).
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"mF_9.B5f-4.1JqM",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}
The above is for the Bearer and the following is for the MAC.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
6 WHITE PAPER
HTTP/1.1 200 OK
"Content-Type: application/json
"Cache-Control: no-store
"{ ""access_token":"SlAV32hkKG",
""token_type":"mac",
""expires_in":3600,
""refresh_token":"8xLOxBtZp8",
""mac_key":"adijq39jdlaska9asud",
""mac_algorithm":"hmac-sha-256"
}
6. MAC Token Profile
The MAC token profile is very much closer to what we have in OAuth 1.0.
The OAuth authorization server will issue a MAC key along with the signature algorithm to
be used and an access token that can be used as an identifier for the MAC key. Once the
client has access to the MAC key, it can use it to sign a normalized string derived from the
request to the resource server. Unlike in Bearer token, the MAC key will never be shared
between the client and the resource server. It"s only known to the authorization server and
the client. Once the resource server gets the signed message with MAC headers, it has to
validate the signature by talking to the authorization server. Under the MAC token profile,
TLS is only needed for the first step, the initial handshake where the client gets the MAC
key from the authorization server. Calls to the resource server need not be on TLS, as we
never expose the MAC key over the wire.
MAC access token response has two additional attributes. mac_key and the
mac_algorithm. To rephrase "each access token type definition specifies the additional
attributes (if any) sent to the client together with the "access_token" response parameter".
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
7 WHITE PAPER
The MAC token profile defines the HTTP MAC access authentication scheme, providing a
method for making authenticated HTTP requests with partial cryptographic verification of
the request, covering the HTTP method, request URI, and host. In the above response,
access_token is the MAC key identifier. Unlike in Bearer, the MAC token profile never
passes its top secret over the wire.
The access_token, or the MAC key identifier, is a string identifying the MAC key used to
calculate the request MAC. The string is usually opaque to the client. The server typically
assigns a specific scope and lifetime to each set of MAC credentials. The identifier may
denote a unique value used to retrieve the authorization information (e.g. from a database),
or self-contain the authorization information in a verifiable manner (i.e. a string consisting
of some data and a signature).
The mac_key is a shared symmetric secret used as the MAC algorithm key. The server will
not re-issue a previously issued MAC key and MAC key identifier combination.
Phase 3 will utilize the access token obtained in Phase 2 to access the protected resource.
Shown below is the Authorization HTTP header when the Bearer token is used.
Authorization: Bearer mF_9.B5f-4.1JqM
This adds very low overhead on the client side. It simply needs to pass the exact
access_token it got from the Authorization Server in Phase 2.
Under the MAC token profile, this is how it would look like.
Authorization: MAC id="h480djs93hd8"
ts="1336363200",
nonce="dj83hs9s",
mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
8 WHITE PAPER
id is the MAC key identifier or the access_token from Phase 2.
ts is the request timestamp. The value is a positive integer set by the client when making
each request to the number of seconds elapsed from a fixed point in time (e.g. January 1,
1970 00:00:00 GMT). This value is unique across all requests with the same timestamp
and MAC key identifier combination.
nonce is a unique string generated by the client. The value is unique across all requests
with the same timestamp and MAC key identifier combination.
The client uses the MAC algorithm and the MAC key to calculate the request mac.
Either we use Bearer or MAC - the end user or the resource owner is identified using the
access_token. Authorization, throttling, monitoring or any other quality of service
operations can be carried out against the access_token irrespective of which token profile
you use.
APIs are not just for internal employees. Customers and partners can access public APIs,
where we do not maintain credentials internally. In that case, we cannot directly
authenticate them. So, we would need to have a federated authentication setup for APIs,
where we would trust a given partner domain, but not individuals. The SAML 2.0 Bearer
Assertion Profile for OAuth 2.0 addresses this concern.
7. SAML 2.0 Bearer Assertion Profile
The SAML 2.0 Bearer Assertion Profile, which is built on top of OAuth 2.0 Assertion
Profile, defines the use of a SAML 2.0 Bearer Assertion as a way of requesting an OAuth
2.0 access token as well as a way of authenticating the client. Under OAuth 2.0, the way of
requesting an access token is known as a grant type. Apart from making the token type
decoupled from the core specification, it also makes the grant type decoupled too. The
grant type defines a protocol to get the authorized access token from the resource owner.
The OAuth 2.0 core specification defines four grant types - authorization code, implicit,
client credentials, and resource owner password. However, it is not limited to four. A grant
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
9 WHITE PAPER
type is another way of extending the OAuth 2.0 framework. OAuth 1.0 was coupled to a
single grant type, which is almost similar to the authorization code grant type in 2.0.
SAML2 Bearer Assertion Profile defines its own grant type (urn:ietf:params:oauth:grant-
type:saml2- bearer). Using this grant type a client can get either a MAC token or a Bearer
token from the OAuth authorization server.
A good use case for SAML2 grant type is a SAML2 Single Sign On (SSO) scenario. A
partner employee can login to a web application using SAML2 SSO (you have to trust the
partner's SAML2 IdP) and later the web application needs to access a secured API on
behalf of the logged in user. To do that, the web application can use the SAML2 assertion
already provided and exchange that to an OAuth access token via SAML2 grant type.
There you would need to have an OAuth Authorization Server running inside our domain -
which trusts the external SAML2 IdP.
Unlike the four other grant types defined in OAuth 2.0 core specification, the SAML2 grant
type needs the resource owner to define the allowed scope for a given client out-of-band.
8. JSON Web Token (JWT) Bearer Profile
JSON Web Token (JWT) Bearer Profile is almost the same as the SAML2 Assertion Profile.
Instead of SAML tokens, this uses JSON Web Tokens. JWT Bearer profile also introduces a
new grant type (urn:ietf:params:oauth:grant-type:jwt-bearer).
9. Improvements
The provision for extensibility made OAuth 2.0 very much superior to OAuth 1.0. That does
not mean it's perfect by any means.
To be the de facto standard for API security, OAuth 2.0 needs to operate in a highly
distributed manner and still be interoperable. We need to have clear boundaries and well-
defined interfaces between the client, the authorization server, and the resource server.
OAuth 2.0 specification breaks it into two major flows. The first is the process of getting
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
10 WHITE PAPER
the access token from the authorization server - which is based on a grant type. The
second is the process of using it in a request to the resource server. The way the resource
server talks to the authorization server to validate the token is not addressed in the core
specification. Hence, it has resulted in vendor specific APIs to creep between the resource
server and the authorization server. This kills interoperability. The resource server is
coupled with the authorization server and this results in vendor lock-in.
10. Token Introspection
The Internet draft OAuth Token Introspection, which is currently being discussed under the
IETF OAuth working group, defines a method for a client or a protected resource (resource
server) to query an OAuth authorization server to determine metadata about an OAuth
token. The resource server needs to send the access token and the resource id (which is
going to be accessed) to the authorization server's introspection endpoint. The
authorization server can check the validity of the token - evaluate any access control rules
around it - and send back the response to the resource server. In addition to the token
validity information, it will further return back the scopes, client_id and some other
metadata associated with the token.
Apart from having a well-defined interface between the OAuth authorization server and
the resource server, a given authorization server should also have the capability to issue
tokens of different types. To do this, the client should bring the required token type it needs
in the authorization request. But in the OAuth authorization request, there is no token type
defined. This limits the capability of the authorization server to handle multiple token types
simultaneously or it will require a form of out-of-band mechanism to associate token types
against clients.
11. Server Metadata
Both the authorization server and the resource server should have the ability to expose
their capabilities and requirements through a standard metadata endpoint.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
11 WHITE PAPER
The resource server should be able to expose its metadata by resource, which type of
token a given request expects, and the required scope likewise. Moreover, the
requirements could change based on the token type. If it is a MAC token, then the resource
server needs to declare which signature algorithm it expects. This could be possibly
supported via an OAuth extension to the WADL (Web Application Description Language).
Similarly, the authorization server also needs to expose its metadata. These could be the
supported token types, and grant types likewise.
The User-Managed Access (UMA) Profile of OAuth 2.0 introduces a standard endpoint to
share metadata at the authorization server level. The authorization server can publish its
token endpoint, supported token types, and supported grant types via this UMA
authorization server configuration data endpoint as a JSON document.
The UMA profile also mandates a set of UMA specific metadata to be published through
this endpoint. This couples the authorization server to UMA, which also addresses a bigger
problem than the need to discover authorization server metadata. It would be more ideal to
introduce the need to publish/discover authorization server metadata through an
independent OAuth profile and extend that in UMA to address more UMA specific
requirements.
12. User-Managed Access
The problem addressed by UMA is far beyond than just exposing Authorization Server
metadata. UMA is undoubtedly going to be one of the key ingredients in any ecosystem for
API security.
UMA defines how resource owners can control protected-resource access by clients
operated by arbitrary requesting parties, where the resources reside on any number of
resource servers, and where a centralized authorization server governs access based on
resource owner policy. UMA defines two standard interfaces for the Authorization Server.
One interface is between the Authorization Server and the Resource Server (protection
API), while the other is between the Authorization Server and Client (authorization API).
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
12 WHITE PAPER
To initiate the UMA flow, the resource owner has to introduce all his resource servers to
the centralized authorization server. With this, each resource server will get an
access_token from the authorization server - and that can be used by resource servers to
access the protection API exposed by the authorization server. The API consists of an
OAuth resource set registration endpoint as defined by OAuth Resource Registration draft
specification, an endpoint for registering client-requested permissions, and an OAuth token
introspection endpoint.
The Client or the Requesting party can be unknown to the resource owner. When it tries to
access a resource, the resource server will provide the necessary details - so, the
requesting party can talk to the authorization server via Authorization API and get a
Requesting Party Token (RPT). This API once again is OAuth protected, so the requesting
party should be known to the authorization server.
Once the client has the RPT, it can present it to the Resource Server and get access to the
protected resource. The Resource Server uses OAuth introspection endpoint of the
Authorization Server to validate the token.
This is a highly distributed, decoupled set up and can be further extended by incorporating
SAML2 grant type.
13. Token Revocation
Token revocation is also an important aspect in API security.
Most of the OAuth authorization servers currently utilize vendor specific APIs. This couples
the resource owner to a proprietary API, leading to vendor lock-in. This aspect is not yet
being addressed by the OAuth working group. The Token Revocation RFC 7009 addresses
a different concern. This proposes an endpoint for OAuth authorization servers, which
allows clients to notify the authorization server when a previously obtained refresh or
access token is no longer needed.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
13 WHITE PAPER
In most cases token revocation by the resource owner will be more prominent than token
revocation by the client as proposed in this draft. The challenge in developing a profile to
revoke access tokens/refresh tokens by the resource owner is the lack of token metadata at
the resource owner end. The resource owner does not have visibility to the access token. In
that case, the resource owner needs to talk to a standard end point at the authorization
server to discover the clients it had authorized before. As per the OAuth 2.0 core
specification, a client is known to the authorization server via the client-id attribute.
Passing this back to the resource owner is less meaningful as in most cases it's an arbitrary
string. This can be fixed by introducing a new attribute called "friendly-name".
14. Resource Owner Initiated Delegation
The model proposed in both OAuth 1.0 as well as in OAuth 2.0 is client initiated. The client
is the one who starts the OAuth flow, by first requesting an access token. How about the
other way around? Resource owner initiated OAuth delegation. For example I am a user of
an online photo-sharing site. There can be multiple clients like Facebook applications and
Twitter applications registered with it. Now, I want to pick some client applications from
the list and give them access to my photos under different scopes. Let's take another
example; I am an employee of Foo.com. I'll be going on vacation for two weeks, so I want to
delegate some of my access rights to Peter only for that period of time. Conceptually,
OAuth fits nicely here. But this is a use case that is initiated by the Resource Owner and is
not being addressed in the OAuth specification. This would require introducing a new
resource owner initiated grant type. The Owner Authorization Grant Type Profile Internet
draft for OAuth 2.0 addresses a similar concern by allowing the resource owner to directly
authorize a relying party or a client to access a resource.
15. Token Chaining
Delegated access control talks about performing actions on behalf of another user. This is
what OAuth addresses. Delegated "chained" access control takes one step beyond this.
The OASIS WS-Trust (a speciation built on top of WS-Security for SOAP) specification
addressed this concern from its 1.4 version on wards, by introducing the "Act-As"
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
14 WHITE PAPER
attribute. The resource owner delegates access to the client and the client uses the
authorized access token to invoke a service that resides in the resource server. This is
OAuth so far. In a real enterprise use case it's a common requirement that the resource or
the service needs to access another service or a set of services to cater to a given request.
In this scenario, the first service going to act as the client to the second service, and also it
needs to act on behalf of the original resource owner. Using the access token passed to it
as it is, is not the ideal solution. The Chain Grant Type Internet draft for OAuth 2.0 is an
effort to fix this. It defines a method by which an OAuth protected service or a resource can
use a received OAuth token from its client, in turn, to act as a client and access another
OAuth protected service. This specification still at its draft-1 would require maturing soon
to address these concerns in real enterprise API security scenarios.
16. OAuth 2.0 Vs. OpenID Connect
OpenID Connect is a profile built on top OAuth 2.0. OAuth talks about access delegation
while OpenID Connect talks about authentication. In other words, OpenID Connect builds
an identity layer on top of OAuth 2.0.
Authentication is the act of confirming the truth of an attribute of a datum or entity. If I say,
I am Peter - I need to prove that. I can prove that with something I know, something I have
or with something I am. Once proven who I claim to be, then the system can trust me.
Sometimes systems do not want to identify end users by just a name. A name could be
your unique form of identification, but there are other attributes too. In order to get past
border control, you would need to identify yourself by name, and provide a photo, as well
as do fingerprint, and retina checks. Those are validated real-time against data from the
visa office, which would have already issued a visa to you. That is proving your identity.
Proving your identity is authentication.
Authorization is about what you can do in the country. You could prove your identity at the
border control by name, photo, as well as fingerprint and retina scans, but it's your visa that
determines what you can do. To enter a country, you would need to have a valid visa. A
valid visa is not a part of your identity, but determines what you can do. Moreover, what
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
15 WHITE PAPER
you can do in the country depends on the type of visa too, e.g. what you do with a B1 or
B2 visa in the US differs from what you can do with an L1 or L2. That is authorization.
OAuth 2.0 is about authorization. Not about authentication.
With OAuth 2.0, the client does not know about the end user (only exception is resource
owner credentials grant type). It simply gets an access token to access a resource on behalf
of the user. With OpenID Connect, the client will get an ID Token along with the access
token. ID Token is a representation of the end user's identity.
What does it mean by securing an API with OpenID Connect? Or is it totally meaningless?
OpenID Connect is at the Application level or at the Client level - not at the API level or at
the Resource Server level. OpenID Connect helps, client or the application to find out who
the end user is, but for the API that is meaningless. The only thing the API expects is the
access token. If the resource owner, or the API wants to find out who the end user is, it has
to query the Authorization Server. The OAuth Token Introspection specification currently
does not support sending back the end user identity in the introspection response, but it
would be quite useful to have a user ID Token in the response (as in OpenID Connect) and
was proposed to the OAuth IETF working group.
17. Fine-Grained Access Control
OAuth is all about access delegation. The resource owner delegates a limited set of access
rights to a third party. In OAuth terminology, this is the "scope". A given access token has a
scope associated with it and it governs the access token's capabilities.
XACML (eXtensible Access Control Markup Language) is the de facto standard for fine-
grained access control. OAuth scope can be represented in XACML policies.
Say, for example, a user delegates access to his Facebook profile to a third party, under the
scope "user_ activities". This provides access to the user's list of activities as the activities'
connection. To achieve finegrained access control, this can be represented in an XACML
policy.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
16 WHITE PAPER
<Policy>
<Target>
<AnyOf>
<AllOf>
<Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<AttributeValue
DataType="https://www.w3.org/2001/XMLSchema#string">
user_activities</AttributeValue>
<AttributeDesignator MustBePresent="false"
Category="urn:oasis:names:tc:xacml:3.0:attribute-category:scope"
AttributeId="urn:oasis:names:tc:xacml:1.0:scope:scope-id"
DataType="https://www.w3.org/2001/XMLSchema#string"></AttributeDesignator>
</Match>
</AllOf>
</AnyOf>
</Target>
<Rule RuleId="permit_rule" Effect="Permit">
</Rule>
<Rule RuleId="deny_rule" Effect="Deny">
</Rule>
</Policy>
The above policy will be picked when the scope associated with the access token is equal
to user_activities. Authorization Server first needs to find all the scopes associated with the
given access token and build the XAML request accordingly.
Authorization Server first gets the following introspection request:
token=gfgew789hkhjkew87
resource_id=GET https://graph.facebook.com/prabathsiriwardena/activities
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
17 WHITE PAPER
Authorization Server now needs to find the scope and the client id associated with the
given token and build the XACML request.
<Request>
<Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:oauth-client">
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:client:client-id">
<AttributeValue
DataType="https://www.w3.org/2001/XMLSchema#string">32324343434</Attribut
eValue>
</Attribute>
<Attributes>
<Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action">
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id">
<AttributeValue
DataType="https://www.w3.org/2001/XMLSchema#string">GET</AttributeValue>
</Attribute>
</Attributes>
<Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:scope">
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:scope:scope-id">
<AttributeValue
DataType="https://www.w3.org/2001/XMLSchema#string">user_activities</Attribute
Value>
</Attribute>
</Attributes>
<Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource">
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id">
<AttributeValue
DataType="https://www.w3.org/2001/XMLSchema#string">
https://graph.facebook.com/prabathsiriwardena/activities</AttributeValue>
</Attribute>
</Attributes>
</Request>
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
18 WHITE PAPER
18. API Security Ecosystem
18.1 Key Manager
Key Manager, or the Authorization Server, is an essential ingredient in an API security
ecosystem. Following highlights some of the prominent expectations from a key manager.
1. Support for open standards ( OAuth, OpenID Connect, UMA, SAML 2.0, XACML)
2. Ability to Integrate with heterogeneous user stores - LDAP / Active Directory / JDBC
3. Tighten security - ability to protect token in transit as well as at rest
4. Fine-grained access control
5. Auditing and Reporting
6. High availability and failover
7. High Performance
18.2 API Gateway
API Gateway under the context of a security ecosystem, plays the role of a security
gateway. This intercepts all API calls to make sure only the legitimate calls pass through. In
most cases for the public facing APIs, the API Gateway will be deployed in the DMZ. The
API Gateway should maintain a secured connection with the Key Manager.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
19 WHITE PAPER
Figure 1
18.3 WSO2 Identity Server (WSO2 IS)
WSO2 IS is an open source Identity and Access Management server that supports OAuth
1.0/2.0, SAML2, OpenID, OpenID Connect, XACML, SCIM and many other identity
management features. Building an ecosystem for API security, WSO2 IS plays a key role as
the Authorization Server. It has support for following OAuth related standards/profiles.
1. OAuth 1.0
2. OAuth 2.0 Core Grant Types
3. OAuth 2.0 Bearer Token Profile
4. OAuth 2.0 SAML 2.0 Token Profile
5. OAuth 2.0 Token Revocation Profile
6. OpenID Connect
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
20 WHITE PAPER
18.4 WSO2 API Manager
WSO2 API Manager, comes with three components; API Publisher, API Store, and API
Gateway. This white paper will only focus on the API Gateway part of it. WSO2 API
Manager connects to the WSO2 IS over a high performance and secured communication
channel built on top of Thrift and TLS.
18.5. WSO2 Business Activity Monitor (WSO2 BAM)
WSO2 BAM can be used to monitor SOA metrics and key business indicators. It provides a
highly scalable, large scale monitoring and analytics solution, integrated with Apache
Hadoop and Apache Cassandra. WSO2 BAM can seamlessly integrated with WSO2 API
Gateway to collect statistics, and analyze and build dashboards on identified business
indicators.
Figure 2
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
21 WHITE PAPER
19. Patterns
19.1 Accessing an API Secured with OAuth, on Behalf of a User Logged into the System, with SAML2 Web SSO
Figure 3
1. User from domain Foo tries to access a web app deployed in the domain Bar. The web
app is secured with SAML2 Web SSO.
2. Web App finds that the user does not have an authenticated session. It finds out from
which domain the request was initiated and redirects the user to the SAML2 IdP in his
own domain.
3. User authenticates to the SAML2 IdP in his own domain.v
4. SAML2 IdP from domain Foo sends a SAML response back to the web app in domain
Bar.
5. Web app validates the SAML response. It has to trust the domain Foo SAML2 IdP. To
access backend APIs, on behalf of the logged in user, web app needs an OAuth access
token. Web app talks to the OAuth Authorization Server in its own domain, passing
the SAML token.
6. OAuth Authorization Server trusts the SAML2 IdP in domain Foo. Validates the SAML
token and sends back an access token.
7. Web app invokes the API with the access token.
8. API Gateway intercepts the request, finds the access token and calls OAuth
Authorization Server to validate it.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
22 WHITE PAPER
9. OAuth Authorization Server validates the token and sends back a JWT (JSON Web
Token), which includes end-user details, to the API Manager.
10. API Gateway adds the JWT as an HTTP header and invokes the backend business
API.
19.2 Accessing an API Secured with OAuth on Behalf of a User/System Authenticated to a SOAP Service with WS-Trust
Figure 4
1. User/System from domain Foo authenticates to the WS-Trust STS in his own domain.
2. STS returns back a SAML token to access the SOAP service in domain Bar.
3. User/System authenticates to the SOAP service in domain Bar with the SAML token.
4. SOAP service validates the SAML token. It has to trust the domain Foo STS. To access
backend APIs, on behalf of the logged in user, SOAP service needs an OAuth access
token. SOAP service talks to the OAuth Authorization Server in its own domain,
passing the SAML token.
5. OAuth Authorization Server trusts the STS in domain Foo. Validates the SAML token
and sends back an access token.
6. SOAP service invokes the API with the access token.
7. API Gateway intercepts the request, finds the access token and calls the OAuth
Authorization Server to validate it.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
23 WHITE PAPER
8. The OAuth Authorization Server validates the token and sends back a JWT (JSON
Web Token), which includes end-user details to the API Manager.
9. API Gateway adds the JWT as an HTTP header and invokes the backend business
API.
19.3 Fine-Grained Access Control with XACML
Figure 5
1. User/System accesses the API passing an access token.
2. API Gateway intercepts the request, finds the access token, and calls the OAuth
Authorization Server to validate it.
3. Authorization Server, finds the scopes and the client id associated with access token,
builds a XACML request can call XACML PDP.
4. XACML PDP evaluates the XACML requests against its policy set and returns back a
XACML response.
5. OAuth Authorization Server sends back a JWT (JSON Web Token), which includes
end-user details to the API Manager.
6. API Gateway adds the JWT as an HTTP header and invokes the backend business
API.
BUILDING AN ECOSYSTEM FOR API SECURITY ©2014 WSO2
24 WHITE PAPER
20. References
1. OAuth 1.0 https://tools.ietf.org/html/rfc5849
2. The OAuth 2.0 Authorization Framework https://tools.ietf.org/html/rfc6749
3. The OAuth 2.0 Authorization Framework: Bearer Token
Usage https://ietf.org/doc/rfc6750/
4. OAuth 2.0 Token Revocation https://ietf.org/doc/rfc7009/
5. OAuth 2.0 Message Authentication Code (MAC) Tokens https://ietf.org/doc/draft-ietf-
oauth-v2-http-mac/
6. SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants
https://ietf.org/doc/draft-ietf-oauth-saml2-bearer/
7. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization
Grants
https://ietf.org/doc/draft-ietf-oauth-jwt-bearer/
8. User-Managehttps://ietf.org/doc/draft-ietf-oauth-jwt-bearer/d Access (UMA) Profile of
OAuth 2.0 https://ietf.org/doc/draft-hardjono-oauth-umacore/
9. OAuth Token Introspection https://tools.ietf.org/html/draft-richer-oauth-introspection-
04
10. WSO2 API Manager https://wso2.com/products/api-manager/
11. WSO2 Identity Server https://wso2.com/products/identity-server/
12. WSO2 Business Activity Monitor https://wso2.com/products/business-activity-
monitor/
13. XACML 3.0 https://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html