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.

mobile client oauth 1

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.

mobile client oauth 2

<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:

mobile client oauth 3

Choose the second Yes button to activate all subnodes under the OAuth node.

mobile client oauth 4

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.

mobile client oauth 5

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.

mobile client oauth 6

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.

mobile client oauth 7

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.

mobile client oauth 8

Multidevice, same user setup (Since DXP22.0010)

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.

mobile client oauth 31

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.

mobile client oauth 9

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.

mobile client oauth 10

Then execute the method. A pop-up will come up.

Give a name of the scope. For instance ZNEPTUNE or YNEPTUNE and press ok.

mobile client oauth 11

Choose a transport request for the newly created Scope and press ok:

mobile client oauth 12

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.

mobile client oauth 13

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):

mobile client oauth 14

Click the External Aliases button on the top:

mobile client oauth 15

Right-click on the default_host node and choose Create External Alias:

mobile client oauth 16

For the name of the External Alias, specify /neptune/oauth/token and choose the corresponding /neptune/oauth/token ICF service in the Target tab:

mobile client oauth 17

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

mobile client oauth 18

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.

mobile client oauth 19

Navigate to the Authorizations tab and click on Change Authorization Data.

mobile client oauth 20

In the pop-up that comes up choose Do not select templates.

mobile client oauth 21

Click the button Manually on top.

mobile client oauth 22

Add the following authorization objects:

S_SERVICE

Hashed name of the TADIR ICF node neptune mobile client oauth 23

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:

  1. Set full authorization.

  2. Continue with the setup to execute the OAuth flow at least once.

  3. Go back to PFCG and now pick the Neptune ICF service as the SRV_NAME for the authorization object S_SERVICE.

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 mobile client oauth 24

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:

mobile client oauth 25

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.

mobile client oauth 26

In the next step, tick the checkbox Client User ID and Password and click Next.

mobile client oauth 27

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.

mobile client oauth 28

In the 4th Step, choose the OAuth 2 Scope you created in the previous step:

mobile client oauth 29

In the final step, review your settings and click Finish.

mobile client oauth 30

Explanation of ICF Nodes

Table 1. Enabling PKCE Functionality in SAP: Newly Added Endpoints
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:

Enable

Switch that activates the OAuth authentication for this mobile client.

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.

  • In some SAP Releases the ICF has a bug that the SAML2 Re-Authentication Policy (forced re-authentication) together with the "Completely Restricted Security Sessions" leads to issues in a way that the ICF handler cannot access any form_fields other than the sap-client (server→request→get_form_fields does not return all form fields). If you have a multi-user setup (thus, forced re-authentication is necessary to authenticate a different user with the /authorize call) and you experience this bug, there is an SAP Note that you might be able to import to solve the problem: 3433020 (URL parameters not available in ICF handler class after SAML authentication). When you test the OAuth setup this error will most likely show as an error page after successful authentication on your IDP with the error message "Code Challenge is mandatory". If you cannot import that note into your system, you need to switch to the InAppBrowser. There the mobile client can delete all cookies related to the former login sessions of the IDP. Thus, you will get presented a fresh login screen and authenticate with another user. If you want to have a real single sign-on experience and only have a single-user setup, you can disable the forced re-authentication setting in the SAML2 Re-Authentication Policy.

  • When you are using the native browser as the Authorize Browser Type in the mobile client setup you need to make sure that the app ID you are using contains only characters that are allowed to be used as a URI scheme (https://www.ietf.org/rfc/rfc2396.txt):

 Scheme names consist of a sequence of characters beginning with a lower case
letter and followed by any combination of lower case letters, digits, plus ("+"),
period ("."), or hyphen ("-").
 For resiliency, programs interpreting URI should treat upper case letters as
equivalent to lower case in scheme names (e.g., allow "HTTP" as well as "http").

scheme = alpha *( alpha | digit | "+" | "-" | "." )

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.