Login Screenlet for iOS


  • Xcode 9.3 or above
  • iOS 11 SDK
  • Liferay Portal 6.2 CE/EE, Liferay CE Portal 7.0/7.1, Liferay DXP


  • iOS 9 and above

Xamarin Requirements

  • Visual Studio 7.2
  • Mono .NET framework


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.

UserServicegetUserByEmailAddressBasic login
UserServicegetUserByScreenNameBasic login
UserServicegetUserByIdBasic login
UserServicegetCurrentUserCookie and OAuth login


  • Auth


  • Default (default)
  • Flat7 (flat7)

For instructions on using Themes, click here.

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.

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.


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.


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.


AttributeData typeExplanation
companyIdnumberThe 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.
loginModestringThe 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.
basicAuthMethodstringSpecifies 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.
OAuthConsumerKeystringSpecifies the Consumer Key to use in OAuth authentication.
OAuthConsumerSecretstringSpecifies the Consumer Secret to use in OAuth authentication.
saveCredentialsbooleanWhen 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.
shouldHandleCookieExpirationbool 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.
cookieExpirationTimeint How long the cookie lasts, in seconds. This value depends on your portal instance’s configuration. The default value is 900.


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

« Introduction to Screenlets in Liferay Screens for iOSSign Up Screenlet for iOS »