This document discusses best practices for building an API security ecosystem, including using a gateway pattern to decouple clients from APIs, various methods for direct authentication of internal users like HTTP basic authentication and OAuth, auditing and monitoring APIs, and externalizing authorization using standards like XACML. It also covers cross-domain access, distributed authorization with resource servers, and user-managed access models.

1. Best
Prac*ces
in
Building
an
API
Security
Ecosystem
Prabath Siriwardena, Director of Security, WSO2
Twitter : @prabath

2. Gateway Pattern

3. Gateway Pattern - Benefits
• Decouple
clients
from
the
actual
API
implementation
• No
point-­‐to-­‐point
to
connection
• Centralized
security
enforcing
• Centralized
auditing
&
monitoring
• Version
controlling

4. Direct Authentication – Internal Users
• HTTP
Basic
Authentication
• HTTP
Digest
Authentication
• TLS
Mutual
Authentication
• OAuth
1.o
:
Two
Legged
OAuth
• OAuth
2.o
:
Client
Credentials
• NTLM
/
Kerberos

5. HTTP Basic Authentication
curl -I
-u $GitHubUserName:GitHubPassword
-X POST -H 'Content-Type: application/x-www-form-urlencoded’
-d '{"name": "my_github_repo"}'
https://api.github.com/user/repos
§ Creating
a
GitHub
repository

6. HTTP Digest Authentication
curl -k –-digest –u userName:password -v https://localhost:8443/recipe
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Digest realm="cute-
cupcakes.com", qop="auth”,
nonce="1390781967182:c2db4ebb26207f6ed38bb08e
effc7422",
opaque="F5288F4526B8EAFFC4AC79F04CA8A6ED"
Authorization: Digest username="prabath", realm="cute-
cupcakes.com",
nonce="1390781967182:c2db4ebb26207f6ed38bb08eeffc7422
", uri="/recipe", cnonce="MTM5MDc4", nc=00000001,
qop="auth",
response="f5bfb64ba8596d1b9ad1514702f5a062",
opaque="F5288F4526B8EAFFC4AC79F04CA8A6ED"

7. HTTP Basic vs. Digest Authentication

8. TLS Mutual Authentication
§ Gateway
itself
does
the
certificate
validation
§ Fine-­‐grained
access
validations
can
be
done
by
the
authorization
server.
curl -k --cert client.pem https://localhost:8443/recipe

9. OAuth 1.0 : Two Legged OAuth
POST /student?name=pavithra HTTP/1.1
Host: server.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="simple",
oauth_consumer_key="dsdsddDdsdsds ",
oauth_token=" ",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1474343201",
oauth_nonce="rerwerweJHKjhkdsjhkhj",
oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

10. OAuth 2.0 : Client Credentials
curl -v -X POST
--basic -u 588997174524690:d5cc4d8e01c9bd7ac14b4d5e91006b5b ]
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8”
-d "client_id=588997174524690&grant_type=client_credentials"
https://graph.facebook.com/oauth/access_token

11. Kerberos / NTLM
§ Can
be
implemented
as
OAuth
2.0
grant
types

12. Auditing / Monitoring

13. Chained APIs

14. Decoupling Authorization Server from
Resource Server

15. Decoupling Authorization Server from
Resource Server
POST /introspection HTTP/1.1
Accept: application/x-www-form-urlencoded
Host: server.example.com
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
token=X3241Affw.4233-99JXJ&resource_id=…
{
"active": true,
"client_id":"s6BhdRkqt3",
"scope": "read write dolphin",
"sub": "2309fj32kl",
"aud": http://example.org/protected-resource/*
}

16. Externalizing Authorization

17. XACML

18. OAuth & XACML
§ A given access token has a scope associated with it and it
governs the access token’s capabilities
§ 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
fine-grained access control, this can be represented in an XACML
policy.
§ token=gfgew789hkhjkew87
resource_id=GET https://graph.facebook.com/prabathsiriwardena/activities

19. 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="http://www.w3.org/2001/XMLSchema#string">32324343434</AttributeValue>
</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="http://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="http://www.w3.org/2001/XMLSchema#string">user_activities</AttributeValue>
</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="http://www.w3.org/2001/XMLSchema#string">
https://graph.facebook.com/prabathsiriwardena/activities</AttributeValue>
</Attribute>
</Attributes>
</Request>

20. XACML Policy
<Policy>
<Target>
<AnyOf>
<AllOf>
<Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<AttributeValue
DataType="http://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="http://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>

21. Cross-Domain API Access

22. Cross-Domain API Access
curl -X POST
-u "QlthIzYUOK5DS0BXW8Cy8uFJjKAa:XFfgPmTbMaQ5eScc0rSnAW9ZIgwa”
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
-d "grant_type=urn:ietf:params:oauth:grant-type:saml2
bearer&assertion=PHNhbWxwOl...[omitted for brevity]...ZT4"
https://localhost:9443/oauth2/token

23. Centralized Authorization with Distributed Resource Servers

24. User Managed Access
• PAT
(Protection
API
Token)
:
Token
issued
to
the
Resource
Server
to
access
the
Protection
API
(Authorization
Server)
with
the
approval
of
the
Resource
Owner.
• AAT
(Authorization
API
Token)
:
Token
issued
to
the
Client
to
access
the
Authorization
API
(Authorization
Server)..
• RPT
(Requesting
Party
Token)
:
Token
issued
to
the
Client
to
access
the
Protected
Resource
on
behalf
of
the
Requesting
Party
by
the
Authorization
Server.

25. Contact us !