Protecting your APIs with OAuth 2.0
0 likes137 views
This white paper discusses the implementation of OAuth 2.0 for protecting APIs, detailing its role in providing authentication and authorization services while ensuring secure access to valuable resources. It clarifies terminology related to OAuth, explores the technical intricacies of token generation, validation, and various authorization flows, and compares the OAuth 2.0 methodology with traditional API key usage. The document aims to simplify the understanding of OAuth 2.0 while addressing common misconceptions surrounding its complexity.
Protecting your APIs with OAuth 2.0
- 1. API PROTECTION WITH OAUTH 2.0 SECURITY, IDENTITY & AUTHORIZATION FOR THE API ECONOMY WHITE PAPER Connecting Identity. Transforming Digital Business.
- 2. UBISECURE WHITE PAPER 2 [email protected] www.ubisecure.com 1. INTRODUCTION APIs are now the standard entry point to the majority of newly created ‘back-end’ functionality. These APIs exist to provide not only a standardized, structured way to access the required features or functions, but also to act as ‘gatekeepers’, ensuring appropriate security, auditing, accounting etc. Security is always underpinned by identity and as such, APIs need to know if not who is accessing them, what is the context in which they are being accessed. A variety of techniques of passing either authentication or authorization data have been used over the years from additional username/password parameters to API keys to full blown OAuth 2.0 based token support. This whitepaper looks at the background to OAuth 2.0 API protection and seeks to dispel some of the complexity myths that still surround this approach. We take the view of the API writer (the Resource Server), future blogs and white papers will explore the work required in other actors within the eco-system. 2. TERMINOLOGY To ensure a consistent understanding the following terms will be used throughout this white paper: Term Description Resource Owner An entity capable of granting access to a protected resource. In the context of this document, the end user who uses a client to access a protected API Resource Server The server hosting the protected resources. In the context of this document this means the API in question, running on a ‘web’ server. Client An application making protected resource requests on behalf of the resource owner and with its authorization. "Application" may be a web application, mobile application, command line script etc that invokes the protected API. Authorization Server The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization Note that these roles are not restricted to single role per application. In fact it is common for real world applications to simultaneously act in many roles. For example, an OAuth 2.0 authorization server often acts in both Authorization server and Resource server roles, and a web application acts in both Client and Resource server roles.
- 3. UBISECURE WHITE PAPER 3 [email protected] www.ubisecure.com 3. RESOURCE SERVER AND PROTECTED API This chapter details what a Resource Server needs to implement in order to protect an API with OAuth 2.0. From the Resource Server’s perspective, hosting a protected API is very simple. Each API request from a Client will contain an access token. The Resource Server will validate this access token with the Authorization Server using a well defined introspection service provided by the Authorization Server. The Resource Owner in collaboration with the Client must generate the required access token, and this is performed using the normal OAuth 2.0 flows for authorization. The outline of these two basic steps is shown below: Diagram: OAuth 2.0 and API 3.1 ACCESS TOKEN GENERATION In the above diagram, the ‘Authentication and authorization’ part is simplified, and it is assumed that the Token response message contains an access token for the Client. Different protocols for a Client to get access tokens from an Authorization server will be presented later in this document. What is important to understand is that the abstraction of Client, Resource Server and Authorization Server roles allows the Resource Server be completely unaware of how a Client gets its access token. This abstraction greatly simplifies the implementation of the Resource Server. Different end users with different clients may all use different authorization and authentication protocols, and these protocols may evolve with time - without any modifications needed to Resource Server implementation.
- 4. UBISECURE WHITE PAPER 4 [email protected] www.ubisecure.com 3.2 API REQUEST AND TOKEN VALIDATION ❶ API request The syntax of API request is entirely specified by the application and the API. OAuth 2.0 recommends that the Client puts the access token in the HTTP standard Authorization header using the "Bearer" scheme. OAuth 2.0 puts no other restrictions on parameters, body, content types or other parts of the request. Below are two API request examples. First one is "RESTful" with JSON formatted content, and second is "Web Services" style with SOAP encoding. RESTful API request SOAP API request POST /api Authorization: Bearer 179c8216e1a0 Content-Type: application/json { "message":"hello server" } POST /api Authorization: Bearer 179c8216e1a0 Content-Type: application/soap+xml <soap:Envelope> <soap:Body> <message>hello server</message> </soap:Body> </soap:Envelope> ❷ Token validation When processing an API request the Resource Server will read access token from the Authorization header, and sends the token to introspection endpoint of the Authorization Server for validation. The Resource Server must previously have registered an identity with the OAuth 2.0 authorization server. The introspection request is authenticated with credentials registered for the Resource server. The example below is using HTTP Basic authentication protocol. Request parameters • token - the access token received with the API request Introspection request to the Authorization Server POST /introspection Authorization: Basic cmVzb3VyY2VzZXJ2ZXI6c2VjcmV0 Content-Type: application/x-www-form-urlencoded token=179c8216e1a0 ❸ Validation response If the Authorization Server considers the token valid for the entity making the request, then the validation response will contain a parameter named "active" with boolean value "true". This is the only mandatory parameter of an introspection response. Response parameters • active = true - indicates token is valid for the entity that made the introspection request Depending on the features and configuration of the OAuth 2.0 Authorization Server, the response will often contain other parameters and claims including: • scope - what scopes resource owner granted to client, useful for API request authorization
- 5. UBISECURE WHITE PAPER 5 [email protected] www.ubisecure.com • sub - machine readable identifier of resource owner, useful for API request auditing and authorization • exp - timestamp indicating time when this token is expected to expire, useful if resource server wants to keep a cache of validation responses • other parameters and claims such as role, organization, etc that may be useful for authorization or other logic implemented by the API Introspection response from the Authorization Server HTTP/1.1 200 OK Content-Type: application/json { "active":true, "scope":"api", "sub":"[email protected]", "exp":1514764800 } ❹ API response As with the originating API request, the syntax and contents of API response are entirely specified by the application. OAuth 2.0 puts no restrictions on body, content types or other parts of the response. RESTful response SOAP response HTTP/1.1 200 OK Content-Type: application/json { "message":"hello client" } HTTP/1.1 200 OK Content-Type: application/soap+xml <soap:Envelope> <soap:Body> <message>hello client</message> </soap:Body> </soap:Envelope> 4. AUTHORIZATION AND AUTHENTICATION PROTOCOLS This chapter presents some protocols the Client may use to get access tokens from an Authorization server. 4.1 PASSWORD GRANT Password grant is the simplest protocol for getting an access token from an Authorization server. However there are a number of serious security issues with this protocol that need to be considered. • Your username and password are disclosed to the Client If the Client is a random application downloaded from the app store or a web application hosted by a third party then this is a potential security issue This is less of a problem if the Client is provided by the same organization as the OAuth 2.0 provider, or if the client is for example a command line script or other trusted tool that you are running in a trusted environment • Privilege escalation because there is no authorization There is no way to control the scope of access tokens the client is requesting from the OAuth 2.0 authorization server If the Client is not trustworthy it could easily request access tokens with a much wider scope than what was intended • Your application becomes limited to username and password authentication mechanism Two-factor authentication mechanisms are out of scope when using password grant protocol
- 6. UBISECURE WHITE PAPER 6 [email protected] www.ubisecure.com See OAuth 2.0 Threat Model and Security Considerations for more details The diagram below outlines the flow for Password grant: Diagram: OAUth 2.0 resource owner password grant ❶ Token request with password grant Request parameters • grant_type = password - indicates password grant protocol is being used • scope - list scopes requested by client • username - Resource owner username • password - Resource owner password Password grant request POST /token Authorization: Basic Y2xpZW50OnNlY3JldA== Content-Type: application/x-www-form-urlencoded grant_type=password&scope=api&[email protected]&password=c04ab498d645 ❷ Token response Response parameters • token_type = Bearer - indicates access token is present in response • access_token - the access token • expires_in - indicates token expiry time, after which client should assume access token has expired • scope - list of scopes granted to client Password grant response HTTP/1.1 200 OK Content-Type: application/json { "token_type":"Bearer", "access_token":"179c8216e1a0", "expires_in":3600, "scope":"api" }
- 7. UBISECURE WHITE PAPER 7 [email protected] www.ubisecure.com 4.2 AUTHORIZATION CODE The authorization code grant protocol requires the Resource Owner use a user agent such as web browser. Authorization code protocol solves the security issues of password grant protocol because Resource Owner authentication and authorization happen within a web browser. No credentials or other confidential information are disclosed to the Client. Because there is a web browser involved, almost any authentication mechanism is possible. In addition to web applications, this protocol is also suitable for mobile and desktop applications. A common method in these use cases is where the Client launches the platform's native web browser and starts a very simple localhost web server to capture the Authorization response. Diagram: OAuth authorization code grant ❶ Authorization request Request parameters • response_type = code • client_id - client registration identifier • redirect_uri - redirect uri registered for client • scope - list scopes requested by client
- 8. UBISECURE WHITE PAPER 8 [email protected] www.ubisecure.com Authorization code grant request GET /authorization?client_id=client&response_type=code& redirect_uri=http://localhost:29634/redirect&scope=api ❷ Authorization redirect Authorization response is not a direct request from the Authorization server to the Client. Instead the Authorization server uses the User agent as intermediary when sending the authorization code to the Client. Request parameters • code - authorization code received from authorization server Authorization response GET /redirect?code=f2889c08f94e ❸ Token request with authorization code Request parameters • grant_type = authorization_code • redirect_uri - redirect uri registered for client • code - authorization code received from authorization server Token request POST /token Authorization: Basic Y2xpZW50OnNlY3JldA== Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=f2889c08f94e&redirect_uri=http://localhost:29634/redirect ❹ Token response Response parameters • token_type = Bearer - indicates access token is present in response • access_token - the access token • expires_in - indicates token expiry time, after which client should assume access token has expired • scope - list of scopes granted to client Token response HTTP/1.1 200 OK Content-Type: application/json { "token_type":"Bearer", "access_token":"179c8216e1a0", "expires_in":3600, "scope":"api" }
- 9. UBISECURE WHITE PAPER 9 [email protected] www.ubisecure.com 4.3 CLIENT INITIATED BACKCHANNEL AUTHENTICATION ("CIBA") The CIBA protocol enables the use of an ‘out of band’ authentication mechanism. Often the Authentication device will be software running on a Mobile device such as mobile phone, but other solutions are also possible. CIBA also solves issues with password grant protocol because no confidential information is disclosed to the Client. The authentication device can implement any suitable authentication mechanism. Ranging from simple "click ok" schemes to highly secure mechanisms with biometric verification. This protocol is suitable for the widest range of applications. In addition to web, mobile and desktop applications this protocol works with use cases with very limited user interfaces such as call centers, petrol pumps, etc. The diagram below outlines the CIBA flow: Diagram: Client Initiated Backchannel Authentication ❶ Authentication request Request parameters • login_hint - username, mobile phone number or other identifier that allows authorization server reach authentication device of Resource owner • scope - list scopes requested by client
- 10. UBISECURE WHITE PAPER 10 [email protected] www.ubisecure.com Authentication request POST /bc-authorize Authorization: Basic Y2xpZW50OnNlY3JldA== Content-Type: application/x-www-form-urlencoded login_hint=5551234&scope=api ❷ Authentication response Response parameters • auth_req_id - authentication transaction identifier Authentication response HTTP/1.1 200 OK Content-Type: application/json { "auth_req_id":"450ab58cafe5" } ❸ Token request with transaction ID Request parameters • grant_type = urn:openid:params:modrna:grant-type:backchannel_request • auth_req_id - authentication transaction identifier Token request POST /token Authorization: Basic Y2xpZW50OnNlY3JldA== Content-Type: application/x-www-form-urlencoded grant_type=urn:openid:params:modrna:grant type:backchannel_request&auth_req_id=450ab58cafe5 ❹ Token response - polling Response parameters • error = authorization_pending - indicates Authorization server is still waiting for interaction from Resource owner Token response (failed poll) HTTP/1.1 200 OK Content-Type: application/json { "error":"authorization_pending" } ❺ Token response Response parameters • token_type = Bearer - indicates access token is present in response • access_token - the access token
- 11. UBISECURE WHITE PAPER 11 [email protected] www.ubisecure.com • expires_in - indicates token expiry time, after which client should assume access token has expired • scope - list of scopes granted to client Token response (successful) HTTP/1.1 200 OK Content-Type: application/json { "token_type":"Bearer", "access_token":"179c8216e1a0", "expires_in":3600, "scope":"api" } 4.4 REFRESH TOKEN The access token allows the client to make requests of the API for some determined length of time. If the Resource Owner wishes to allow the client to continually access for a long time a security issue exists where the access token once created will be usable for that period without further authentication requests. The use of such a long running token would be considered bad practice. To solve this issue, the Authorization Server can provide not only an access token, but also a refresh token. The access token will have a ‘short’ expiry time, but the refresh token will have a long expiry time. When the access token expires the client can use the refresh token to generate a new access token, but this re-issuance by the Authorization Server enables any changes to be included (underlying account changes, authorization changes etc). Diagram: OAuth 2.0 ❶ Token request with refresh token Request parameters • grant_type = refresh_token • refresh_token - refresh token is an optional parameter of the Token response Token request POST /token Authorization: Basic Y2xpZW50OnNlY3JldA== Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=cd51acb1b04a
- 12. UBISECURE WHITE PAPER 12 [email protected] www.ubisecure.com ❷ Token response Response parameters • token_type = Bearer - indicates access token is present in response • access_token - the access token • expires_in - indicates token expiry time, after which client should assume access token has expired • scope - list of scopes granted to client Token response HTTP/1.1 200 OK Content-Type: application/json { "token_type":"Bearer", "access_token":"179c8216e1a0", "expires_in":3600, "scope":"api" } 5. A COMPARISON OF OAUTH 2.0 AND API KEYS The pre-cursor to OAuth for APIs has been the use of API keys, and such API key methods are still in common use today. Advocates of API keys approaches emphasize simplicity of API keys over the complexity of OAuth 2.0. OAuth 2.0 based solutions bring the advantage of standardisation, and the ability to completely decouple authentication/authorization from API usage. Purpose of this comparison is to show that OAuth 2.0 is scalable: It may be as simple as any API keys approach, and it is very easy to build an application that scales from simple API keys style approach to full OAuth 2.0 suite. Area API Keys OAuth 2.0 access token Token differences Lifetime of API keys often unlimited which makes approach attractive for headless server-to-server approaches Lifetime of access token often limited - need to use saved credentials or refresh tokens for headless server-to-server approaches Ease of use - often there exists an easy to use tool or user interface for generating API keys Ease of use varies - some protocols for getting access tokens are very simple, others are more complex Authorization Server Equivalent mechanism to required, both to generate and initial (lifetime) key and to validate presented key on API call. OAuth 2.0 requirement - provides services to generates and validate access tokens Client API key is the token and is ready to use for the client Client must first request an access token using some dynamic mechanism before it can be used Resource Server Must validate the API key on presentation Must validate the access token on presentation
- 13. UBISECURE WHITE PAPER 13 [email protected] www.ubisecure.com Although there are differences between the two mechanisms, at the high level, and without considering key/token generation, the usage is very similar. 5.1 MIGRATING FROM API KEYS TO OAUTH 2 The work required to migrate an API key based platform to an OAuth 2.0 based platform is quite minimal. • Put API key in HTTP standard Authorization header using "Bearer" scheme • Publish OAuth 2.0 compatible introspection service for validating API keys This way your API application will be OAuth 2.0 ready. The existing key management system will have to be exposed to enable access tokens to be created (wrapping existing key meaning) however this can be achieved by a number of off the shelf components, such as Ubisecure’s Identity Server. 6. CONCLUSION Creating a new API server (Resource Server) in an OAuth 2.0 compliant manner is, as has been shown, simple and no more effort than an older API key base manner. More over, using an OAuth 2.0 based authorization strategy provides significantly more flexibility and security than API keys. Migrating an existing API service to OAuth 2.0 authorization is simple and quick and brings many additional security and operational benefits. 7. REFERENCES • https://tools.ietf.org/html/rfc6749 • https://tools.ietf.org/html/rfc6750 • https://tools.ietf.org/html/rfc7235 • https://tools.ietf.org/html/rfc7662 • http://openid.net/specs/openid-connect-modrna-client-initiated-backchannel-authentication-1_0.html • https://en.wikipedia.org/wiki/Application_programming_interface_key API Protection with OAuth 2.0 authored by Petteri Stenius Principle Scientist, Ubisecure
- 14. UBISECURE WHITE PAPER 14 [email protected] www.ubisecure.com Ubisecure is a pioneering European b2b and b2c Customer Identity & Access Management (CIAM) software provider and cloud identity services enabler dedicated to helping its customers realise the true potential of digital business. Ubisecure provides a powerful Identity Platform to connect customer digital identities with customer- facing SaaS and enterprise applications in the cloud and on-premise. The platform consists of productised CIAM middleware and API tooling to help connect and enrich strong identity profiles; manage identity usage, authorisation and progressive authentication policies; secure and consolidate identity, privacy and consent data; and streamline identity based workflows and decision delegations. Uniquely, Ubisecure’s Identity Platform connects digital services and Identity Providers, such as social networks, mobile networks, banks and Governments, to allow Service Providers to use rich, verified identities to create frictionless login, registration and customer engagement while improving privacy and consent around personal data sharing to meet requirements such as GDPR and PSD2. Ubisecure is accredited by the Global Legal Entity Identifier Foundation (GLEIF) to issue Legal Entity Identifiers (LEI) under its RapidLEI brand, a cloud-based service that automates the LEI lifecycle to deliver LEIs quickly and easily. The company has offices in London and Finland. To learn more about Customer IAM and Company Identity solutions visit www.ubisecure.com or contact us at [email protected]