API Specifications Conference 2019

1. © Hitachi, Ltd. 2019. All rights reserved.
What API Specifications and Tools Help Engineers
to Construct a High-Security API System?
API Specifications Conference 2019
Hitachi, Ltd.
OSS Solution Center
Yoshiyuki Tabata

2. 1
© Hitachi, Ltd. 2019. All rights reserved.
About the speaker
Yoshiyuki Tabata :
OSS Solution Center, Hitachi, Ltd. @Yokohama, Japan
https://github.com/y-tabata
• Software engineer
• Building high-security banking API systems
• API Management & Identity Management
• 3scale, Keycloak
• Contributor of 3scale
• Developed “Edge Limiting policy”, “Keycloak Role
Check policy”, “OAuth MTLS policy”

3. © Hitachi, Ltd. 2019. All rights reserved.
Contents
2
1. Introduction: HIGH-SECURITY API System Overview
2. Standards and features surrounding high-security API
system
3. Other useful features help engineers to test the high-
security API system

4. 3
© Hitachi, Ltd. 2019. All rights reserved.
API System
API System Overview
API Gateway /
API Management
Product
For example...
• 3scale
• NGINX
Identity Management
Product
For example...
• Keycloak
API
Backend
Client
Application
API Request
Authorized
API Request
API Response
API Response
Authorize API Request in cooperation with
Identity Management Product

5. 4
© Hitachi, Ltd. 2019. All rights reserved.
API System
Testing API System
API Gateway /
API Management
Product
For example...
• 3scale
• NGINX
Identity Management
Product
For example...
• Keycloak
API
Backend
Client
Application
API Request
Authorized
API Request
API Response
API Response
Authorize API Request in cooperation with
Identity Management Product
Use Swagger UI as a
mock client!
Swagger UI is very useful
because it supports
OAuth 2.0 Authorization
Grant
Create a mock
server!
“Generate Server”
feature of Swagger UI is
one of the candidates

6. 5
© Hitachi, Ltd. 2019. All rights reserved.
HIGH-SECURITY API System
HIGH-SECURITY API System Overview
API Gateway /
API Management
Product
For example...
• 3scale
• NGINX
Identity Management
Product
For example...
• Keycloak
API
Backend
Client
Application
Authorized
API Request
API Response
API Response
Authorize API Request in cooperation with
Identity Management Product
API Request
with Challenge
and Client Cert
with Client Cert
in compliance with high-security
standards such as:
- PKCE
- OAuth MTLS

7. 6
© Hitachi, Ltd. 2019. All rights reserved.
HIGH-SECURITY API System
Testing HIGH-SECURITY API System
API Gateway /
API Management
Product
For example...
• 3scale
• NGINX
Identity Management
Product
For example...
• Keycloak
API
Backend
Client
Application
API Request
Authorized
API Request
API Response
API Response
Authorize API Request in cooperation with
Identity Management Product
with Challenge
and Client Cert
with Client Cert
CANNOT Use
Swagger UI as a
mock client!
Swagger UI does NOT
support high-security
features such as PKCE
and OAuth MTLS
Create a mock
server!
“Generate Server”
feature of Swagger UI is
one of the candidates
in compliance with high-security
standards such as:
- PKCE
- OAuth MTLS

8. 7
© Hitachi, Ltd. 2019. All rights reserved.
HIGH-SECURITY API System
Testing HIGH-SECURITY API System
API Gateway /
API Management
Product
For example...
• 3scale
• NGINX
Identity Management
Product
For example...
• Keycloak
API
Backend
Client
Application
API Request
Authorized
API Request
API Response
API Response
Authorize API Request in cooperation with
Identity Management Product
with Challenge
and Client Cert
with Client Cert
CANNOT Use
Swagger UI as a
mock client!
Swagger UI does NOT
support high-security
features such as PKCE
and OAuth MTLS
Create a mock
server!
“Generate Server”
feature of Swagger UI is
one of the candidates
I created a mock!
in compliance with high-security
standards such as:
- PKCE
- OAuth MTLS

9. © Hitachi, Ltd. 2019. All rights reserved.
Contents
8
1. Introduction: HIGH-SECURITY API System Overview
2. Standards and features surrounding high-security API
system
3. Other useful features help engineers to test the high-
security API system

10. 9
© Hitachi, Ltd. 2019. All rights reserved.
Standards for high-security API system
OAuth 2.0
OIDC,
PKCE
FAPI
OAuth 2.0 is the common standard to secure API.
Almost all API systems are in compliance with OAuth 2.0.
However, lots are left to implementers, insecure usage can
easily happen.
OIDC (OpenID Connect) standardizes user verification using
ID token.
PKCE (Proof Key for Code Exchange) standardizes how to
mitigate the authorization code interception attack.
FAPI (Financial-grade API) standardizes secure usage of
OAuth 2.0 and OIDC.
OAuth MTLS is said to be required by FAPI.
hardened
OAuth MTLS

11. 10
© Hitachi, Ltd. 2019. All rights reserved.
OAuth 2.0 Authorization Grant
OAuth 2.0 (RFC 6749) defines 4 types of authorization grants.
- Authorization code grant
- Resource owner password credentials grant
- Client credentials grant
- Implicit grant
Authorization code grant is the most suitable grant for high-security API system.
End-user
Identity
Management
Server
Application
API Gateway
Use
Authenticate user
(username, password)
Issue tokens
API request with token
End-user does NOT need to tell the password to the application.

12. 11
© Hitachi, Ltd. 2019. All rights reserved.
Authorization Code Grant
End-user Application
Identity
Management
Server
Browser
Use application
Redirect browser to the identity management server
Redirect browser to application and issue authorization code
Authenticate user
Request tokens using authorization code
Issue tokens
API Gateway
API request with token

13. 12
© Hitachi, Ltd. 2019. All rights reserved.
Issues of Authorization Code Grant
End-user Application
Identity
Management
Server
Browser
Use application
Redirect browser to the identity management server
Redirect browser to application and issue authorization code
Authenticate user
Request tokens using authorization code
Issue tokens
API Gateway
API request with token
Intercepting the authorization code,
the attacker can request tokens.
Intercepting the tokens, the attacker can call API.

14. 13
© Hitachi, Ltd. 2019. All rights reserved.
PKCE
End-user Application
Identity
Management
Server
Browser
Redirect browser to the identity management server and send code challenge
Redirect browser to application and issue authorization code
Authenticate user
Request tokens using authorization code and send code verifier
Issue tokens
PKCE mitigates the authorization code interception attack.
Code challenge is a hash value of
code verifier.
The server calculates code
challenge from code verifier and if
matches, issues tokens.

15. 14
© Hitachi, Ltd. 2019. All rights reserved.
PKCE implementation in our mock (1/2)
String url = session.getRealm().getAuthorizationEndpoint() + "?response_type=code" + "&redirect_uri="
+ session.getClientApplication().getRedirectUri() + "&client_id="
+ session.getClientApplication().getClientId() + "&scope=" + session.getClientApplication().getScope()
+ "&state=" + session.getState();
if (session.getClientApplication().isPkce()) {
url += "&code_challenge=" + session.getClientApplication().getCodeChallenge()
+ "&code_challenge_method=S256";
}
Implement PKCE just as defined at RFC 7636.
- Create code_verifier. (43 <= character length <= 128)
- Generate code_challenge from code_verifier.
# code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
- Attach code_challenge to URL which application redirects to the authorization
server.
code_challenge_method is allowed to be selected "S256" or "plain",
but "S256" is mandatory for security.

16. 15
© Hitachi, Ltd. 2019. All rights reserved.
PKCE implementation in our mock (2/2)
Form form = new Form();
form.param("grant_type", "authorization_code");
form.param("code", request.getParameter("code"));
form.param("redirect_uri", session.getClientApplication().getRedirectUri());
form.param("client_id", session.getClientApplication().getClientId());
form.param("client_secret", session.getClientApplication().getClientSecret());
if (session.getClientApplication().isPkce()) {
form.param("code_verifier", session.getClientApplication().getCodeVerifier());
}
Implement PKCE just as defined at RFC 7636.
- When requesting tokens, attach code_verifier to form parameter.
Regarding Swagger UI, PKCE implementation is discussed in Issue #5348 and
implemented in PR #5361, so I hope it is merged.

17. 16
© Hitachi, Ltd. 2019. All rights reserved.
OAuth MTLS
End-user Application
Identity
Management
Server
Browser
Redirect browser to the identity management server
Redirect browser to application and issue authorization code
Authenticate user
Request tokens using authorization code and send client cert
Issue tokens API Gateway
API request with token and send client cert
OAuth MTLS mitigates the token interception attack.
Register client cert
information of the
application in advance.
Check the client cert
and mitigate the
interception attack.
The token includes a hash value
of the client cert.
The gateway calculates the hash
value from the client cert and if
matches, allows calling API.

18. 17
© Hitachi, Ltd. 2019. All rights reserved.
OAuth MTLS implementation in our mock
SslConfigurator sslConfig = SslConfigurator.newInstance()
.trustStoreFile(“Trust Store File").trustStorePassword(“pass")
.keyStoreFile(“Key Store File").keyPassword(“pass");
sslContext = sslConfig.createSSLContext();
...
Client client;
if (isMtls) {
client = ClientBuilder.newBuilder().sslContext(sslContext).build();
} else {
client = ClientBuilder.newClient();
}
Including application server layer, it is necessary to set to be able to send client cert.
In the case of Jersey, setting SSLContext to ClientBuilder leads to
be able to send client cert.

19. 18
© Hitachi, Ltd. 2019. All rights reserved.
OAuth MTLS implementation for access control
Implement just as defined at "draft-ietf-oauth-mtls-17".
- Check the "cnf" claim in access token and the hash value of client cert are the same.
API System
API Gateway /
API Management
Product
Identity Management
Product
Mock
Server
Mock
Client
API Request
with Client Cert
{
...,
"cnf": {
"x5t#S256":
"xUcKf..."
},
...
}
Calculate the hash value:
# BASE64URL-ENCODE(SHA256(DER-ENCODED(X.509 cert)))
And compare with the "cnf" claim.
cf. PR #1101 of 3scale (APIcast), which I submitted.

20. © Hitachi, Ltd. 2019. All rights reserved.
Contents
19
1. Introduction: HIGH-SECURITY API System Overview
2. Standards and features surrounding high-security API
system
3. Other useful features help engineers to test the high-
security API system

21. 20
© Hitachi, Ltd. 2019. All rights reserved.
Common challenge for testing API system
API System
API Gateway /
API Management
Product
Identity Management
Product
Mock
Server
Mock
Client
Test API Request
403 !?
The issued token
is ok?
The logic of
access control is ok?
It's troublesome to confirm:
- whether it was expected behavior or not and
- where the problem is.
For example, we need to check each product's log each time.

22. 21
© Hitachi, Ltd. 2019. All rights reserved.
Useful feature 1: Decode tokens
Mock
Client
If we can decode token using the mock, we can check whether the issued token is ok
or not right there.
{"access_token":"eyJhb...“
, ...}
{
"jti": "937e192...",
"exp": 1568012060,
...
"iss": "https://server...",
...
"azp": "sample_client",
...
"cnf": {
"x5t#S256": "xUcKf..."
},
"scope": "openid sample_scope“
}
Identity Management
Product
Issue tokens
Decode!
With encoded, the token
is not readable.
With decoded, the token
is readable.
We can check:
- expiry time
- user/client information
- hashed client cert
- scope
etc.

23. 22
© Hitachi, Ltd. 2019. All rights reserved.
How to implement decoding tokens
var accessTokenRegex = /^([^ .]+).([^ .]+).([^ .]+)[ ]*$/i;
var accessTokenResult = accessTokenRegex.exec(accessToken);
var payload = accessTokenResult[2];
var decodedPayload = decodeURIComponent(escape(atob(payload)));
var dataPayload = JSON.parse(decodedPayload);
In the access token, there are 2 kinds, "self-contained" and "reference/opaque" token.
The token we can decode is "self-contained" token and which format is JSON Web
Token (JWT).
# JWT = BASE64URL(Header).BASE64URL(Payload).BASE64URL(Signature)
Important information is included in "Payload", so extract it
using regex, and decode it.

24. 23
© Hitachi, Ltd. 2019. All rights reserved.
Useful feature 2: Call endpoints of the authorization server
Endpoints Description
Authorization Endpoint Issues authorization code.
Token Endpoint Issues tokens.
Token Introspection Endpoint Checks token validity. (RFC 7662)
UserInfo Endpoint Shows the authenticated user
information. (OIDC)
Well-Known Endpoint Shows the authorization server
metadata. (RFC 8414)
Logout Endpoint / Token
Revocation Endpoint
Logs out from the client. (RFC 7009)
If we can call endpoints using the mock, we can check whether the access control (e.g.
token introspection) is worked correctly or not right there.
Calling these endpoints is
already supported.
Calling these endpoints is
not supported, but it is
important to know what
these endpoints response
to the client.
Mock
Client
Identity Management
Product
Call endpoints

25. 24
© Hitachi, Ltd. 2019. All rights reserved.
How to implement calling endpoints
This is not difficult.
These endpoints are usually published officially.
What we do is only calling endpoints according to the specification.
Endpoints Description Example of Keycloak
Authorization Endpoint Issues authorization code. /realms/{realm-name}/protocol/openid-
connect/auth
Token Endpoint Issues tokens. /realms/{realm-name}/protocol/openid-
connect/token
Token Introspection Endpoint Checks token validity. (RFC 7662) /realms/{realm-name}/protocol/openid-
connect/token/introspect
UserInfo Endpoint Shows the authenticated user
information. (OIDC)
/realms/{realm-name}/protocol/openid-
connect/userinfo
Well-Known Endpoint Shows the authorization server
metadata. (RFC 8414)
/realms/{realm-name}/.well-
known/openid-configuration
Logout Endpoint / Token
Revocation Endpoint
Logs out from the client. (RFC 7009) /realms/{realm-name}/protocol/openid-
connect/logout

26. 25
© Hitachi, Ltd. 2019. All rights reserved.
Summary
• Key features for high-security API system.
• PKCE
• OAuth MTLS
• Useful features to test the high-security API system.
• Decode tokens
• Call endpoints of the authorization server
• These features are not only necessary for engineers to test the API system
but also valuable for every application developer!
• Can check high-security requirements of APIs.
• Can check the issued tokens detail.
• Can check how-to-use of the authorization server endpoints.
• It would be great to be able to hear your suggestion where we should
propose this.

27. 26
© Hitachi, Ltd. 2019. All rights reserved.
Trademarks
• OpenID is a trademark or registered trademark of OpenID Foundation in the United States and other
countries.
• NGINX is a registered trademark of NGINX Inc.
• Other brand names and product names used in this material are trademarks, registered trademarks,
or trade names of their respective holders.