The OAuth 2.0 RFC 6749 describes multiple methods (so-called grant types resp. flows) how an end user can grant authorization to a 3rd party application. A grant type that is frequently used for server-to-server communication is the grant type authorization code. The grant type authorization code is redirection-based, i.e. relies on browser redirects between OAuth 2.0 authorization server and client to issue OAuth 2.0 tokens.
Figure 1 gives an overview about the OAuth 2.0 grant type authorization code. For details see the descriptions in section 4.1 of RFC 6749.
Figure 1: Grant type Authorization Code (See RFC 6749)
To access a resource protected by OAuth 2.0, a client must authenticate using an access token. The grant type authorization code shown in figure 1 is used to initially get an access token and additionally a refresh token from an OAuth 2.0 authorization server. Later on when the access token has expired, the client can use the refresh token to request new access tokens autonomously.
The following steps will be performed during the authorization code flow:
(A) The authorization code flow is initiated by the client, which first sends an authorization request to the authorization server. To do this it redirects the resource owner’s browser to the authorization server to receive an authorization code. (An authorization code is a short lived token, that confirms the resource owner's identity and that he has consented to issue an access token for a particular set of OAuth 2.0 scopes.)
(B) Before issuing the authorization code the authorization server will authenticate the resource owner and ask her for consent of the requested OAuth 2.0 scopes. I.e. it will display a consent screen and present a list of the scopes requested by the client. The resource owner can then give her consent or decline.
(C) If the resource owner has given his consent the authorization server will issue a short lived authorization code. The authorization code is sent back to the client, again by browser redirect.
(D) The client then requests an access and a refresh token from the authorization server. To achieve this the client sends an HTTP request directly to the authorization server and includes the authorization code. I.e. this request is sent directly from the client to the authorization server without browser redirect.
(E) Finally the authorization server validates the received authorization code and if successful responds to the client with a newly issued access and optionally a refresh token.
Initiate the authorization code flow in AS ABAP
The authorization code flow needs to be executed when no access token is available, i.e. normally when the user has not worked with OAuth 2.0 before. Later on, when an access token has expired, the AS ABAP application can perform the refresh flow to request a new access token autonomously without user interaction.
Therefore this initial execution of the authorization code flow needs to be actively triggered by the end user. There are two possibilities to trigger the flow:
- Call the endpoint /sap/bc/sec/oauth2/client/grant/authorization. This method can be used from within a web application to trigger the flow.
- Use transaction OA2C_GRANT to get an overview for the current user about all authorization servers the AS ABAP can access as an OAuth 2.0 client. From this web dynpro application an end user can initially trigger the authorization code flow as well.
Further details about initiating the authorization code flow are described in the example descriptions.
Usage of the OAuth 2.0 Client API in an ABAP program
After the OAuth 2.0 client received the access and refresh token from the authorization server, these tokens can be used from within an arbitrary ABAP program via the OAuth 2.0 Client API. There are two usage scenarios related with the authorization code flow. Firstly, an access token can be used to access a resource protected by OAuth 2.0. Secondly, a refresh token can be used by the client to receive a new access token without user interaction.
Using an access token
Figure 2 gives an overview about usage of the OAuth 2.0 Client API to send HTTP requests including OAuth 2.0 access tokens.
Figure 2: OAuth 2.0 Access Token usage
The following steps need to be performed by the ABAP program to use the OAuth 2.0 Client API:
(1) Firstly, an instance of the OAuth 2.0 client type IF_OAUTH2_CLIENT needs to be created using class CL_OAUTH2_CLIENT.
(2) Secondly, an instance of the HTTP client type IF_HTTP_CLIENT needs to be created, which will be used to send HTTP requests and receive the server responses.
(3) The OAuth 2.0 client instance is then used to set the access token in the HTTP client. To trigger this, the application program calls method SET_TOKEN on the OAuth 2.0 client instance and passes the HTTP client instance as a parameter.
(4) After the access token was handed over to the HTTP client as described in step 3, the HTTP client can be used to access OAuth 2.0 protected resources. Multiple resources can be accessed after setting the access token, if they are covered by one of the OAuth 2.0 scopes assigned to the access token.
The details of using an access token are described in the example descriptions.
Refreshing an expired access token
Figure 3 shows how the OAuth 2.0 Client API is used to refresh an expired access token.
Figure 3: Refreshing OAuth 2.0 tokens
The refresh of an OAuth 2.0 Access Token can be triggered very easily from an ABAP program by first instantiating an OAuth 2.0 client instance and then simply calling the execute refresh flow method. This method call will perform a synchronous HTTP request to the remote authorization server, executing the OAuth 2.0 refresh flow.
After refreshing the tokens the access token can be handed over to an HTTP client instance and be used for protected access as described in the previous section.
The details of executing the refresh flow are explained in the example descriptions.