OAuth 2.0
Introduction
Neptune OAuth 2.0 Authentication is a feature that enables the use of OAuth 2.0 authentication with a PKCE (Public Key Code Exchange) flow on mobile clients within the /neptune/… ICF nodes. This authentication method stands out due to its ability to utilize the configured authentication in your SAP System (similar to the Native Authentication type) while also implementing a Bearer token header authentication that uses access and refresh tokens.
To use this authentication mechanism, your SAP System needs the following components:
SAP_BASIS 7.40 SP02 and SAP_GWFND 7.40 SP02
| If these requirements are not met you will not find the OAuth Authentication tab in the mobile client configuration. |
Settings
- Enable
-
Enables the authentication type.
- OAuth 2.0 Client ID
-
Name of the OAuth 2.0 client ID you created with transaction SOAUTH2, see more information at One Time Setup.
- SAML 2.0 Identity Provider
-
The OAuth authentication type will open a browser login page that will show a Login screen. With the Setting SAML 2.0 Identity Provider you can control what login page you want to use.
Possible values are:
- None
-
This will add the query parameter &saml2=disabled to the URL. Thus, no SAML2 IDP login screen will show up, but you will be presented with the Neptune login screen that’s being used for SAP Username and SAP Password Authentication.
- Default
-
This won’t add any query parameter to the URL. Thus, the default SAML2 authentication that’s configured in transaction SAML2 will bring the corresponding login screen.
- <NameOfSaml2Idp>
-
In addition to None and Default, all SAML2 IDPs configured in transaction SAML2 will show up. Selecting a specific SAML2 IDP will add query parameter &saml2idp=<NameOfSaml2Idp> to the URL. By specifying exactly one IDP, you can control which SAML2 IDP you want to use for this mobile client.
One Time Setup
To allow SAP Standard OAuth authentication in ICF nodes that are non-odata related (/neptune/…), you need to perform some manual steps upfront before you can use the Authentication Type in your mobile client.
Activate /neptune/oauth/… ICF nodes
Go to Transaction SICF and expand the top neptune node. Right-click on the oauth node and choose Activate Service:
Choose the second Yes button to activate all subnodes under the OAuth node.
Implicit Enhancements
To enable SAP Standard OAuth authentication for non-OData related ICF nodes, we must enhance SAP OAuth Framework to allow also the /neptune ICF node to work with OAuth authentication.
Navigate to method CL_OAUTH2_S_SCOPE_CONTROLLER⇒CLASS_CONSTRUCTOR and create an implicit enhancement at the end of the method. Choose Type Code and enter the following code snippet:
*---> Enable NEPTUNE SICF Node for OAuth2 Authentication
CLEAR ls_scope_properties.
ls_scope_properties-object = 'SICF'.
ls_scope_properties-name_derivation_method = c_derive_name_1to1.
ls_scope_properties-authority_check_method = c_authority_check_classic.
ls_scope_properties-runtime_handler = '/NEPTUNE/HTTP_HANDLER'. " Neptune Handler
CLEAR ls_scope_properties-rbam_strategy.
INSERT ls_scope_properties INTO TABLE mt_scope_properties.
INSERT ls_scope_properties-runtime_handler INTO TABLE mt_whitelist.
create_hta ls_scope_properties-runtime_handler
c_pgmid 'SICF' 'NEPTUNE 0000000000000000000000000'. " SICF Entry for Neptune Node| Depending on your release, there might not be the macro create_hta available. Just comment this last section in this case. |
Navigate to method CL_OAUTH2_S_TOKEN_ENDPOINT⇒CHECK_AUTHENTICATION_ICF and create an implicit enhancement at the beginning of the method. Choose Type Code and enter the following code snippet:
*---> NEPTUNE Custom PKCE Authentication Checks
if /neptune/cl_oauth_pkce_token=>check_pkce_auth_method( io_client = io_client
io_server = io_server ) = abap_true. "Self-Contained PKCE Authentication Checks
return. " >>>>>>>>>>>>>
endif.
Navigate to method CL_OAUTH2_S_TOKEN_ENDPOINT⇒CHECK_AUTHENTICATION_CLIENT and create an implicit enhancement at the beginning of the method. Choose Type Code and enter the following code snippet:
*---> NEPTUNE Custom PKCE Authentication Checks
if /neptune/cl_oauth_pkce_token=>check_pkce_auth_method( io_client = io_client
io_server = io_server ) = abap_true. "Self-Contained PKCE Authentication Checks
return. " >>>>>>>>>>>>>
endif.
Depending on your SAP release you might also have the method CHECK_CLIENT_ID_PARAMETER of class CL_OAUTH2_S_TOKEN_ENDPOINT available. In this case, you will also need to place the same enhancement there at the top like the other CHECK_… enhancements:
*---> NEPTUNE Custom PKCE Authentication Checks
if /neptune/cl_oauth_pkce_token=>check_pkce_auth_method( io_client = io_client
io_server = io_server ) = abap_true. "Self-Contained PKCE Authentication Checks
return. " >>>>>>>>>>>>>
endif.
Multidevice, same user setup
The access and refresh token creation and revocation used for OAuth authentication is handled by SAP Standard. SAP will only allow one refresh token per SAP User. So when obtaining a new refresh token, old existing refresh tokens for that user (stored eventually on other devices) will be not valid anymore. Thus, the client that authenticated at the latest point in time and that set a pin code will be the only one that can re-authenticate with that pin code. The other clients that might have stored an old refresh token cannot re-authenticate with that anymore. The Mobile Client and PWA-enabled Launchpads will detect this and trigger the /authorize flow for re-authenticating. So, the only noticeable difference for the end users is that after entering the pin code they are asked to re-authenticate at the IDP. This is considered a good security best practice. So, you can only use one refresh token per user. However, if you want to have multiple refresh tokens for the same SAP user in the system, you will need to implement the following additional implicit enhancement:
*---> NEPTUNE Custom PKCE Authentication multi-refresh token support
if /NEPTUNE/CL_OAUTH_PKCE_TOKEN=>SHOULD_OLD_CONTEXTS_BE_REMOVED( ) = space.
return. " >>>>>>>>>>>
endif.
SAML Re-Authentication Policy
We will need to set up the following SAML policy (which can be maintained with transaction SAML2) that will be used for re-authentication when the Neptune endpoint is called to authorize.
Scope for /neptune ICF node
OAuth 2.0 authentication is based on Scopes. Scopes are identifying which resource is requested in the authentication flow. In this step, we will create the scope that is later to target the /neptune ICF node.
Execute method CL_OAUTH2_S_SCOPE_MANAGER⇒CREATE_SCOPE_FROM_OBJECT via SE24 Execute in Test Environment (F8) and pass the following values:
-
In IS_OBJECT add the following code snippet.
R3TR SICF NEPTUNE 0000000000000000000000000-
In I_DEVCLASS, choose your desired SAP Development Package.
-
In I_DESCRIPTION, choose your desired SAP Development Package.
| Ensure the Case-Sensitive checkbox is enabled. |
Then execute the method. A pop-up will come up.
Give a name of the scope. For instance ZNEPTUNE or YNEPTUNE and press ok.
Choose a transport request for the newly created Scope and press ok:
Create an OAuth System User
OAuth 2.0 in SAP NetWeaver stack requires a user for the token retrieval. The User Type should be set to B System and this user should not have any roles nor should the user have SAP_ALL.
External Alias for /neptune/oauth/token
For the Neptune implementation of a PKCE authentication flow you need to set this user with his password in the /neptune/oauth/token ICF service. There is an elegant way to achieve this without modifying the /neptune/oauth/token ICF node directly (modification-free) which makes use of an external alias that has the same path as the target ICF node path.
Open transaction SICF and click execute (F8):
Click the External Aliases button on the top:
Right-click on the default_host node and choose Create External Alias:
For the name of the External Alias, specify /neptune/oauth/token and choose the corresponding /neptune/oauth/token ICF service in the Target tab:
In the Logon Data tab apply the following settings:
- Procedure
-
O Required with Logon Data
- Security Session
-
F Completely restricted
- User/Password
-
Username and password for the OAuth user you created in the previous step
- Security Requirement
-
SSL
PFCG Role for the End Users of the Mobile Client
To allow the endorsers running the mobile client to use a Bearer type authentication against the /neptune/… ICF nodes, these users will need to get authorization to use the OAuth scope you created in the step above.
Open Transaction PFCG and create a Single Role with your desired name.
Navigate to the Authorizations tab and click on Change Authorization Data.
In the pop-up that comes up choose Do not select templates.
Click the button Manually on top.
Add the following authorization objects:
- S_SERVICE
-
Hashed name of the TADIR ICF node neptune
|
If you cannot select the NEPTUNE ICF node as the field SRV_NAME you will first need to set the full authorization of the SRV_NAME field by clicking the button "Full Authorization". This is due to the special handling of SAP to only show the services that are listed in table USOBHASH. The entry will be added there if you execute the OAuth flow once. So the steps in your SAP System might be:
|
- S_SCOPE
-
Name of the OAuth2 client (Name of the OAUTH system user) and Neptune scope you created in step Scope for /neptune ICF node
SAP Standard OAuth 2 Configuration
After you have prepared all the steps above, you can finally create the SAP Standard Configuration for the OAuth PKCE Authentication.
Call Transaction SOAUTH2 and click on the Create … button:
In the pop-up, supply as OAuth 2.0 Client ID the name of the OAUTH system user you created in a step before and supply a description. Adjust the Token Lifetime parameter to your desired level of security. Click Next.
In the next step, tick the checkbox Client User ID and Password and click Next.
In the 3rd Step, only tick the checkboxes Grant Type Authorization Code Active and Refresh Allowed.
As Redirect URI supply the following URL pattern where you would exchange <URLToMySapSystem.com> and put in your real SAP URL.
You can set the Auth. Code Lifetime and Refresh Token Expires After parameters to your desired level of security.
Click Next.
In the 4th Step, choose the OAuth 2 Scope you created in the previous step:
In the final step, review your settings and click Finish.
Explanation of ICF Nodes
| Endpoint | SICF | Function | Class |
|---|---|---|---|
Token |
/neptune/oauth/token |
Wrapper around the standard SAP Token Service for OAuth and enables PKCE verifier processing and authentication. |
/NEPTUNE/CL_OAUTH_PKCE_TOKEN |
Authorize |
/neptune/oauth/authorize |
Custom Authorize service that allows for the processing of PKCE challenges and storage. |
/NEPTUNE/CL_OAUTH_PKCE_AUTH |
Session |
/neptune/oauth/session |
This is an optional service that allows for the generation of SSO cookies. This is used mostly for Fiori integration into the Neptune client. |
/NEPTUNE/CL_OAUTH_GET_SESSION |
Mobile Client Configuration
In the Mobile Client, you will find the OAuth 2.0 configuration in the Authentication tab of the detail screen of a Mobile Client.
| This will only be visible when your SAP System supports OAuth 2.0 authentication (see also minimum SAP release on the top). |
There you will find the following settings:
OAuth 2.0 Client ID
Enter here the Name of the OAuth 2.0 client you created with transaction SOAUTH2.
SAML 2.0 Identity Provider
Specify the SAML2 identity provider that you want to use for the /authorize endpoint (IDP authorize login screen). This is only necessary if you have set up multiple SAML2 IDPs in the system and want to control which one should be used. To stick with the default one, we recommend setting the value to Default. If you specify None, SAML2 authentication will be disabled and the user will be presented the /webapp login screen for authentication with SAP Username and Password.
Authorize Browser Type (only Mobile Client and not PWA-enabled Launchpad)
This setting allows you to specify which browser type should be used that calls the /authorize URL and presents the user with the login screen of the corresponding IDP. It is recommended to use the Native Browser as this is the most modern way of implementing OAuth authentication flows in mobile applications. However, there can be situations where you might want to use the InAppBrowser.
So for instance you cannot use any underscores in the app ID. The reason for this is that the callback from the native browser to the main Cordova app happens through an app URL scheme. The value for the app URL scheme will be the app ID. If that contains invalid scheme characters the native browser window will stay open and the authorization code cannot be sent back to the main app. Example: When you have an app ID in the mobile client with the value "com.neptune.oauthapp" the final step of the /neptune/oauth/authorize call will be a redirected to the URL com.neptune.oauthapp://code=theAuthorizeCode after successful authentication. This will lead to a redirect to the mobile client. However, if you have an app ID that contains unsupported characters as a URI scheme (for example com.neptune_dev.oauthapp) the redirect would not work. Instead, you would get an error page telling you that the redirect does not work. The native browser window will stay open in that case. |