This document discusses authorization and authentication processes for API services. It is a part of the Build API Services: A Beginner’s Guide tutorial series.
To securely access an API service, a client must go through a two-step process:
- Authorization: The resource owner grants the client access to the API service, usually in the form of a key or a token.
- Authentication: The client passes the key or the token to the API service, which verifies its validity and responds accordingly.
If helpful, think of authorization as government issuing your ID card and authentication as airport security verifying your ID card.
Authorization and authentication are two separate processes. Government cares very little about where and how you use your ID card (well, terms and conditions may apply); the document single-handedly proves your identity (and your level of access). On the other hand, airport has no idea where and how you acquire your ID card; officers will let you through as long as your ID card is valid and/or registered in the system. In a similar manner, API services cares little about authorization process; its sole responsibility is to authenticate clients, certifying that they have the clearance to access the resources via the API service.
Authorization is usually fulfilled by a server outside the API service (an authorization server). Authentication is, of course, completed within the API service itself. This document will discuss briefly some of the authorization models (frameworks); however, the specifics of the process, namely how to build an authorization server, is beyond the scope of this tutorial series. If you have decided on an authorization framework, see its specification and documentation for more information.
In most cases, you should never build an API service without setting up authorization and authentication flows. These processes help prevent abuse, protect data, and grant you the power of access control. They also enable you to track and analyze API calls, which can be of great help to the development of your API service.
Authorization models (frameworks) and their corresponding authentication processes
API keys
An API key is a randomly generated string prepared in a cryptographically strong manner.
Many programming languages offer dedicated modules for generating cryptographically strong bits, such as the secrets module from Python; note that after generation the key should be encoded in Base64/URL Safe scheme so that it can be transferred safely via HTTP.
Each API key corresponds to a record in a database, which specifies the access scopes of the and other related information. To use API keys in your API service, first assign every developer planning to use your API service a unique API key; every time the developer wants to access an API, he or she passes the key to the API service as a part of the request. Upon receiving an API call, the API service verifies the incoming API key, usually by matching it with the key records, and complies with (or declines) the request accordingly.
HTTP Basic Authentication
Alternatively, you may use HTTP Basic Authentication, as specified in RFC 7235, in your API service. This framework is first introduced to developers as a part of the HTTP protocol, allowing applications to send a username/password combination in the header of an HTTP request. For example, if a developer has username user and password pass in your API service, he or she can send an HTTP request with the header
Authorization: Basic dXNlcjpwYXNzto your API service, where the sequence dXNlcjpwYXNz is the base64 encoded version of string user:pass; the API service checks the header field when the request arrives, and complies with (or declines) the request accordingly.
Token-based Models
API Keys and HTTP Basic Authentication require that credentials be sent to the API service every time an API call is made. Straightforward as it is, the design is far from ideal, as it incurs unnecessary overhead and poses additional security risks: your API service have to repeatedly verify the same set of credentials, and transmitting sensitive information over the network over and over again increases the chances of security compromises.
Token-based models help address some of the concerns above. Instead of passing credentials, clients now use tokens to access APIs. Tokens are independent of user credentials and usually short lived, consequently even if a leak happens, the damage can be quickly controlled. Some token formats, such as JWT (JSON Web Token), are self-contained as well: your API service can verify them without having to inquire a source.
In an API service with token-based authentication, developers need to request a token first with their credentials before accessing APIs (authorization). Many developers choose to use OAuth2 (and its extensions) as the authorization framework for their token-based authentication API services.
OAuth2
OAuth2 is a widely used authorization framework enabling clients to access resources securely and efficiently. It includes four different authorization flows, each for a specific scenario, which developers can choose to implement for their system. There are also a variety of extensions to the OAuth2 framework.
Specifics of OAuth2 and OAuth2 authorization servers are beyond the scope of this document. There are many tutorials, frameworks, and services that can help you build your own OAuth2 authorization server; you may also want to refer to RFC 6749 for more information. This tutorial series, Understanding OAuth2 and Building a Basic Authorization Server of Your Own: A Beginner’s Guide, is a good start as well.
Choosing a model (framework) for your API service
Generally speaking, If the resources behind your API service belongs to someone else (for example, calendars behind Google Calendar API belongs to Google Calendar users, rather than the API provider, Google), you should always use the OAuth2 framework for authorization and implement token-based authentication in your API service. OAuth2 framework, more specifically its Authorization Code flow and Implicit flow, allows third-party developers to access your APIs on behalf of the actual resource owners without knowing their credentials, thus protecting the users from data breach and identity theft.
On the other hand, if you are the owner of the resources provided by your API service, all of the options above (API Keys, HTTP Basic Authentication, and token-based models) are open to you. API Keys and HTTP Basic Authentication are easier to implement; token-based authentication, however, offers better security and performance.
A few side notes
- Regardless of your model (framework) decision, you should always force SSL/TLS in your API service. None of the models (frameworks) above is truly secure without SSL/TLS.
- gRPC offers built-in support for SSL/TLS and token-based authentication. With some additional setup it is possible to use API Keys and HTTP Basic Authentication as well.
What’s next
If you plan to build a HTTP RESTful API service, see
If you plan to build a gRPC API service, see
