OAuth 2.0 is a standard authorization protocol that allows applications to access a user's account in a web service (HTTP) such as the Valuekeep CMMS Web API.
The protocol delegates user authentication to the service that holds the user's account and authorizes external applications to access that user's account. The protocol makes authorization flows available for Web, desktop and mobile apps.
We now describe the basic operation of the protocol from the perspective of an application developer.
The protocol defines 4 roles:
1. Resource owner: this is the user who authorizes the application's access to his account. Such access is limited to the scope of the authorization given by the user.
2. Client: is the application that wants to access the user account.
3. Resource server: is the server that hosts the user's accounts.
4. Authorization server: is the server that verifies the identity of the user and assigns authorization tokens to the client (the application).
From the point of view of an application developer, the Web API you want to consume acts both as resource server and the authorization server. It is, therefore, common for the two roles to be combined in what is called a Service or simply an API.
The normal authorization flow from an external application will follow these steps:
1. The application requests permission to access user resources.
2. If the user has already authorized such a request, the application receives an authorization grant.
3. The application asks the authorization server for an access token, showing the user's identity and the authorization grant.
4. If the application's identity is authenticated and the authorization grant is valid, the authorization server assigns an access token to the application and the authorization flow ends.
5. The application requests a certain resource from the resource server and displays the access token it obtained before.
6. If the access token is valid, the resource server will return the requested resource to the application.
7. This is OAuth's normal conceptual flow, but the actual authentication flow depends on the type of authorization grant that is used. We will now discuss the different authorization grants available.
The type of grant used depends on the authorization method the app wishes to use and, of course, of the methods supported by the Web API. To work with the Valuekeep CMMS Web API, you must use the Client Credentials authorization method.
When an access token expires, its use to perform requests to the API will result in the error “Invalid Token Error”. In that moment, if a refresh token has been included when the access token is generated, you can use it for a new server access token.
Example of a request of that type: