What API Specifications and Tools Help Engineers to Construct a High-Security API System?
Download as PPTX, PDF0 likes72 views
Yoshiyuki Tabata from Hitachi presented on API specifications and tools that help engineers construct high-security API systems. He discussed standards like OAuth 2.0, OIDC, PKCE, and OAuth MTLS. Useful features for testing include decoding tokens to check validity, and calling authorization server endpoints to validate access control. Implementing these features in mock servers and clients allows engineers to efficiently test if high-security requirements are met before production.
![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.](https://image.slidesharecdn.com/apispecificationsconference2019yoshiyukitabatashare-220117123046/85/What-API-Specifications-and-Tools-Help-Engineers-to-Construct-a-High-Security-API-System-23-320.jpg)
![[APIdays INTERFACE 2021] The Evolution of API Security for Client-side Applic...](https://cdn.slidesharecdn.com/ss_thumbnails/apidays-interface-johannstalk-210709062455-thumbnail.jpg?width=560&fit=bounds)
![OpenID Connect - a simple[sic] single sign-on & identity layer on top of OAut...](https://cdn.slidesharecdn.com/ss_thumbnails/gluecon2014-oidc-140521065808-phpapp01-thumbnail.jpg?width=560&fit=bounds)
Ad
More Related Content
What's hot (20)
Similar to What API Specifications and Tools Help Engineers to Construct a High-Security API System? (20)
Ad
More from Hitachi, Ltd. OSS Solution Center. (20)
Ad
Recently uploaded (20)
What API Specifications and Tools Help Engineers to Construct a High-Security API System?
- 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.