Developer

OpenUI SMPOpenUICredentialProvider (iOS)

This example demonstrates how to authenticate the iOS client against the SAP Mobile Platform platform using application security settings and the SMPOpenUICredentialProvider class.

The SAP Mobile Platform platform requires up to two separate levels of authentication. One level of authentication is against Agentry back-end connections. The second level of authentication is against the platform itself as configured in the Security options of the application settings within the platform. The iOS client portion for this second level of authentication can be achieved using the SMPOpenUICredentialProvider class. Currently, the SMPOpenUICredentialProvider class provides credentials for two types of authentication.

The first authentication type supported is SSL Authentication. In this type, the iOS client through OpenUI allows for the use of an SMPOpenUICredentialProvider to provide a PCKS12 client certificate, and its password to the Agentry iOS client. The second authentication type supported is HTTP Header Authentication. In this second authentication type, the iOS client allows for an SMPOpenUICredentialProvider to provide an HTTP header to the Agentry iOS client. These client certificate and password credentials and/or HTTP headers are used for platform authentication.

You can create a credential provider that optionally uses the GUI. Alternatively, you can create a credential provider that does not use a GUI, and does not require client user interaction for providing the credentials. In either case, you must create the credential provider using the name SMPOpenUICredentialProvider for Agentry to recognize it as the OpenUI adapter intended for credential authentication.

An SMPOpenUICredentialProvider must adopt protocol SMPOpenUICredentialProviderAdapter. During initialization, the credential provider is passed a model object that adopts protocol SMPOpenUICredentialProviderModel. The credential provider can optionally find out the previous authentication result by calling the model's SMPOpenUICredentialProviderModel::getLastClientAuthenticationResult: `getLastClientAuthenticationResult:` method.

SMPOpenUICredentialProvider Use Case With GUI

When implementing an SMPOpenUICredentialProvider that uses a GUI, create a user class that adopts protocol SMPOpenUICredentialProviderAdapter. Although not required, the user class would likely be a subclass of UIViewController. Specifically, the SMPOpenUICredentialProvider should implement the SMPOpenUICredentialProvider::shouldDisplayUIForModel: `shouldDisplayUIForModel:` and SMPOpenUICredentialProvider::getViewControllerforModel: `getViewControllerforModel:` methods. If either of these two methods are optionally not implemented, Agentry defaults to using the SMPOpenUICredentialProvider without a GUI as described in the next section.

This SMPOpenUICredentialProvider should have its view property set with a UIView (or subclass) that handles the user interaction for obtaining the network credentials. When ready to submit the network credentials to Agentry for SSL Authentication, the SMPOpenUICredentialProvider should execute the following steps:
  1. Send a SMPOpenUICredentialProviderModel::setClientCertificate: `setClientCertificate:` message to the model. This message provides Agentry the client certificate data. The data should be in PCKS12 format.

  2. Send a SMPOpenUICredentialProviderModel::setClientCertificatePassword: `setClientCertificatePassword:` message to the model. This message informs Agentry of the password for the client certificate.

  3. Send a SMPOpenUICredentialProviderModel::complete: `complete:` message to the model. This message informs Agentry that the SMPOpenUICredentialProvider has completed providing the certificate and password. This causes the dismissal of any UI dialog presented for the SMPOpenUICredentialProvider. The SMPOpenUICredentialProvider should not use a separate mechanism to dismiss its own UI.

When ready to submit the network credentials to Agentry for HTTP Header Authentication, the SMPOpenUICredentialProvider should execute the following steps for HTTP Header Authentication:
  1. Send a SMPOpenUICredentialProviderModel::setNextRequestHeaders: `setNextRequestHeaders:` message to the model. This message provides Agentry the HTTP header data. The data should be an NSArray* containing a set of NSDictionary elements. Each NSDictionary must only contain one key/value HTTP header pair. Including multiple key/value pairs in an NSDictionary object will yield undefined behavior.

  2. Send a SMPOpenUICredentialProviderModel::complete: `complete:` message to the model. This message informs Agentry that the SMPOpenUICredentialProvider has completed providing the HTTP header data. This will cause the dismissal of any UI dialog presented for the SMPOpenUICredentialProvider. The SMPOpenUICredentialProvider should not use a separate mechanism to dismiss its own UI.

During HTTP Header Authentication, the adapter can cancel the current authentication transmission. To cancel the HTTP Header Authentication transmission, the SMPOpenUICredentialProvider should execute the following steps:
  1. Send a SMPOpenUICredentialProviderModel::setContinueXmit: `setContinueXmit:` message to the model with a NO parameter.

  2. Send a SMPOpenUICredentialProviderModel::complete: `complete:` message to the model. This message informs Agentry that the SMPOpenUICredentialProvider has completed. This causes the dismissal of any UI dialog presented for the SMPOpenUICredentialProvider. The SMPOpenUICredentialProvider should not use a separate mechanism to dismiss its own UI.

SMPOpenUICredentialProvider Use Case Without a GUI

When implementing a SMPOpenUICredentialProvider without a GUI, a subclass of NSObject should be used that adopts the protocol SMPOpenUICredentialProviderAdapter.

For SSL Authentication, the SMPOpenUICredentialProvider should implement the SMPOpenUICredentialProvider::getCertificateForModel: `getCertificateForModel:`, and SMPOpenUICredentialProvider::getCertificatePasswordForModel: `getCertificatePasswordForModel:` methods. If either of these two methods are optionally not implemented, Agentry defaults to not transmitting a client certificate to SAP Mobile Platform Server.

For HTTP Header Authentication, the SMPOpenUICredentialProvider should implement the SMPOpenUICredentialProvider::getNextRequestHeadersForModel: `getNextRequestHeadersForModel:` method. If this methods is optionally not implemented, Agentry default to not transmitting any user HTTP header data to SAP Mobile Platform Server.

Demo Examples: SMPOpenUICredentialProvider

The SMPOpenUISampleAdapters within the SMPAgentryClientFrameworkDemo includes three simple, working examples of an SMPOpenUICredentialProvider class and its associated views for an iPad and an iPhone layout.

Demo Example: SMPOpenUICredentialProvider SSL Certificate

This example uses the following four files: SMPOpenUICredentialProvider.h, SMPOpenUICredentialProvider.mm, SMPOpenUICredentialProvider.xib, and SMPOpenUICredentialProvider-iPad.xib.

This sample code creates a simple UI that contains two text fields, one for entering the file name of the PCKS12 certificate and another for the password used to decrypt the certificate. There is also a text view that indicates the previous authentication result and a button for the user to press when they are finished. When this button is pressed, Agentry attempts to continue the transmit with the provided information. In addition to this basic workflow, the sample SMPOpenUICredentialProvider stores the most recently used file name and password, and these will be automatically reused for future transmits if the previous result was successful. This sample code's UI and implementation can be extended to create a customized and/or sophisticated user experience.

Demo Example: SMPOpenUICredentialProvider HTTP Header Authentication with GUI

This example uses the following four files: SMPOpenUICredentialProviderSystemLoginWithUI.h, SMPOpenUICredentialProviderSystemLoginWithUI.mm, SMPOpenUICredentialProviderSystemLoginWithUI.xib, and SMPOpenUICredentialProvider-iPadSystemLoginWithUI.xib.

To use of these files within the demo, all four files need to remove "SystemLoginWithUI" from their file names. Before doing this, the existing four files from the SSL Certificate Demo example need to be either renamed or deleted.

This sample code creates a simple UI that contains two text fields, one for entering a user name and another for entering a password. There is also a text view that indicates the previous authentication result and a button for the user to press when they are finished. When this button is pressed, Agentry attempts to continue the transmit with the provided information. There is a second button to cancel the authentication transmission. In addition to this basic workflow, the sample SMPOpenUICredentialProvider stores the most recently used user name and password, and these will be automatically reused for future transmits if the previous result was successful. This sample code's UI and implementation can be extended to create a customized and/or sophisticated user experience.

Demo Example: SMPOpenUICredentialProvider HTTP Header Authentication without GUI

This example uses the following two files: SMPOpenUICredentialProviderSystemLoginNoUI.h and SMPOpenUICredentialProviderSystemLoginNoUI.mm.

To use of these files within the demo, both files need to remove "SystemLoginNoUI" from their file names. Before doing this, the existing two files from the SSL certificate Demo example need to be either renamed or deleted. This sample code creates a simple SMPOpenUICredentialProvider without a UI that creates an HTTP header for authentication using a hard coded user name and password. This sample code and implementation can be extended to create a customized, sophisticated user experience.