Login Screenlet for iOS

Requirements

  • Xcode 9.0
  • iOS 11 SDK
  • Liferay Portal 6.2 (CE or EE), Liferay 7.0 CE, Liferay DXP
  • OAuth Provider app (OAuth authentication is optional. Note that OAuth only works with Liferay EE and DXP instances).

Compatibility

  • iOS 9 and above

Xamarin Requirements

  • Visual Studio 7.2
  • Mono .NET framework 5.4.1.6

Features

The Login Screenlet authenticates portal users in your iOS app. The following authentication methods are supported:

  • Basic: uses user login and password according to HTTP Basic Access Authentication specification. Depending on the authentication method used by your Liferay instance, you need to provide the user’s email address, screen name, or user ID. You also need to provide the user’s password.

  • OAuth: implements the OAuth 1.0a specification.

  • Cookie: uses a cookie to log in. This lets you access documents and images in the portal’s document library without the guest view permission in the portal. The other authentication types require this permission to access such files.

For instructions on configuring the Screenlet to use these authentication types, see the below Portal Configuration and Screenlet Attributes sections.

When a user successfully authenticates, their attributes are retrieved for use in the app. You can use the SessionContext class to get the current user’s attributes.

Note that user credentials and attributes can be stored securely in the keychain (see the saveCredentials attribute). Stored user credentials can be used to automatically log the user in to subsequent sessions. To do this, you can use the method SessionContext.loadStoredCredentials() method.

JSON Services Used

Screenlets in Liferay Screens call the portal’s JSON web services. This Screenlet calls the following services and methods.

Service Method Notes
UserService getUserByEmailAddress Basic login
UserService getUserByScreenName Basic login
UserService getUserById Basic login
UserService getCurrentUser Cookie and OAuth login

Module

  • Auth

Themes

  • Default (default)
  • Flat7 (flat7)

For instructions on using Themes, click here.

screens-ios-login.png

The Login Screenlet using the Default and Flat7 Themes.

Portal Configuration

Basic Authentication

Before using Login Screenlet, you should make sure your portal is configured with the authentication option you want to use. You can choose email address, screen name, or user ID. You can set this in the Control Panel by selecting ConfigurationInstance Settings, and then selecting the Authentication section. The authentication options are in the How do users authenticate? selector menu.

screens-portal-auth.png

Setting the authentication method in your Liferay instance.

For more details, please refer to the Setting up a Liferay Instance section of the User Guide.

OAuth

To use OAuth authentication, first install the OAuth provider app from the Liferay Marketplace. Click here to get this app. Once it’s installed, go to Control PanelUsersOAuth Admin, and add a new application to be used from Liferay Screens. Once the application exists, copy the Consumer Key and Consumer Secret values for later use in Login Screenlet.

Offline

This Screenlet doesn’t support offline mode. It requires network connectivity. If you need to log in users automatically, even when there’s no network connection, you can use the saveCredentials attribute together with the SessionContext.loadStoredCredentials() method.

Attributes

Attribute Data type Explanation
companyId number The ID of the portal instance to authenticate to. If you don’t set this attribute or set it to 0, the Screenlet uses the companyId setting in LiferayServerContext.
loginMode string The Screenlet’s authentication type. You can set this attribute to basic, oauth, or cookie. If you don’t set this attribute, the Screenlet defaults to basic authentication.
basicAuthMethod string Specifies the basic authentication option to use. You can set this attribute to email, screenName or userId. This must match the server’s authentication option. If you don’t set this attribute, and don’t set the loginMode attribute to oauth or cookie, the Screenlet defaults to basic authentication with the email option.
OAuthConsumerKey string Specifies the Consumer Key to use in OAuth authentication.
OAuthConsumerSecret string Specifies the Consumer Secret to use in OAuth authentication.
saveCredentials boolean When set, the user credentials and attributes are stored securely in the keychain. This information can then be loaded in subsequent sessions by calling the SessionContext.loadStoredCredentials() method.
shouldHandleCookieExpiration bool  Whether to refresh the cookie automatically when using cookie login. When set to true (the default value), the cookie refreshes as it’s about to expire.
cookieExpirationTime int  How long the cookie lasts, in seconds. This value depends on your portal instance’s configuration. The default value is 900.

Delegate

The Login Screenlet delegates some events to an object that conforms to the LoginScreenletDelegate protocol. This protocol lets you implement the following methods:

  • - screenlet:onLoginResponseUserAttributes:: Called when login successfully completes. The user attributes are passed as a dictionary of keys (String or NSStrings) and values (AnyObject or NSObject). The supported keys are the same as the portal’s User entity.

  • - screenlet:onLoginError:: Called when an error occurs during login. The NSError object describes the error.

  • - screenlet:onCredentialsSavedUserAttributes:: Called when the user credentials are stored after a successful login.

  • - screenlet:onCredentialsLoadedUserAttributes:: Called when the user credentials are retrieved. Note that this only occurs when the Screenlet is used and stored credentials are available.

Challenge-Response Authentication

To support challenge-response authentication when using a cookie to log in to the portal, the SessionContext class has a challengeResolver attribute. For more information about how iOS handles challenge-response authentication, see the article Authentication Challenges and TLS Chain Validation.

The challenge resolver type is a closure or block that receives two parameters:

  1. URLAuthenticationChallenge
  2. Another closure or block. You must call this to resolve the challenge (e.g., by passing credentials, canceling the challenge, etc.). You can do this by passing a URLSession.AuthChallengeDisposition.

Here’s an example that sends a basic authorization in response to an authentication challenge:

SessionContext.challengeResolver = resolver

func resolver(challenge: URLAuthenticationChallenge,
    decisionCallback: (URLSession.AuthChallengeDisposition, URLCredential) -> Void) {

    // Use the challenge variable to get information about the challenge itself
    if challenge.previousFailureCount == 0 {
        // To solve the challenge, call the decision callback with your decision
        // Pass the credentials to the server
        decisionCallback(.useCredential, URLCredential(user: "user", password: "password", 
            persistence: .forSession))
    }
    else {
        // Something went wrong, so let the system handle the challenge
        decisionCallback(.performDefaultHandling, URLCredential(user: "these credentials", 
            password: "are ignored", persistence: .none))
    }

}
0 (0 Votes)
Screenlets in Liferay Screens for iOS Previous