When you set up custom authentication, you control the authentication process and customize the sign-in experience in the AEM Mobile app. The custom authentication sign-in experience appears in the app as a full-screen web view that you design.

Custom sign-in experiences

The following formats are supported:

  • SAML 2.0, including support for MFA/OKTA and Gigya.
  • OAuth 2.0, including social sharing logins such as Facebook or Gmail.
  • Generic, which allows you to design your own sign-in behavior and interact with your entitlement service.

For example, you can allow your sales representatives to login to the app using their email and password plus OKTA verification (SAML 2.0). Or, you could allow customers to log in to the app using their Gmail or Facebook account (OAuth 2.0). The app obtains authorization tokens from these identity providers, which you can use in your entitlement service to authorize users to content. By leveraging the setAuthToken API, you can expand your authentication methods in a number of ways, including using multiple authentication methods within the same app.

Generic identity providers allow two alternate authentication use cases, including:

  • Providing a custom UI such as an HTML form instead of using the standard user name and password prompt.
  • Building a sign-in experience within an article rather than through the standard authentication process.

 

Note that an entitlement service using the v2 Direct Entitlement APIs is still required to authorize users to content.

APIs are provided for the customer to determine if the user is authenticated, get the auth token, and launch the sign-in UI web view. See Using AEM Mobile specific Cordova-enabled APIs.

 

Custom Authentication Video

Custom Authentication Video
Introduction to custom authentication video.

Set up custom authentication

Identity providers are set up in Master Settings and applied to a project in Project Settings. You can create multiple identity providers at the Master Account level for use in projects.

  1. Set up an entitlement service to work with AEM Mobile.

    Even if you enable a custom authentication service, an entitlement service using the v2 Direct Entitlement APIs is required to authorize users to content. See Entitlement in AEM Mobile apps.

  2. Set up a SAML 2.0, OAuth 2.0, or generic identity provider for use with AEM Mobile and your entitlement service.

    Google identity provider

    For an example of setting up a Google identity provider, see this PDF file (English only):  

    Facebook identity provider

    For an example of setting up a Facebook identity provider, see this PDF file (English only):

    Generic identity provider

    For an example of setting up a generic identity provider, see this example (English only):

    For a video about generic identity providers, see the Generic IdP video (English only).

    Gigya

    You can use Gigya Customer Identity Management as an identity provider, which allows customers to sign in using both traditional and various social media methods such as Facebook, Google, and LinkedIn. For an example of setting up a Gigya identity provider, see this example (English only):

    See this AEM Mobile article in Gigya documentation.

     

    Note:

    Gigya's authentication workflow relies on cookies set in the users' browsers. Gigya authentication may fail in AEM Mobile apps when the app detects these cookies as third-party cookies and blocks them. If blocked third-party cookies are preventing the Gigya workflow from authenticating properly, you may want to implement a workaround as described in Gigya’s documentation: Blocked Third-Party Cookies.

     

    The example entitlement service code includes support for custom authentication. For details, see Set up an entitlement service.

  3. Sign in to the On-Demand Portal with a Master Admin account. Click Master Settings, and then click the Identity Providers tab.

  4. Click the Create Identity Provider (+) icon, and then specify the identity provider name and type (OAuth 2.0, SAML 2.0, or Generic).

  5. Specify the information for your identity provider. See the option descriptions later in this document.

  6. To set up a trust between your identity provider and the AEM Mobile app, copy the Experience Manager Mobile Response Endpoint (SAML 2.0) or Experience Manager Mobile Redirection Endpoint (OAuth 2.0) value, and add it to your identity provider configuration.

    Adding this information tells the service how to inform AEM Mobile of the results of the authentication process. For example, the auth token returned from Facebook is different from the token in your entitlement service for that user. In your entitlement service, you need to map the Facebook auth token for the user so that when AEM Mobile calls for entitlements, the entitlement service will return the correct response. The user will then be authorized to view content when signing in.

  7. In the On-Demand Portal, go to Project Settings, edit the project, and click the Access tab. Select “Enable Custom Authentication” and choose the appropriate Identity Provider created in Master Settings.

  8. Build a non-preflight app and test your custom authentication setup.

SAML 2.0 settings

Service Provider ID – The value that AEM Mobile will use to identify itself when sending an authentication request to the identity provider. The service provider ID should be registered with the identity provider.

Protocol Binding – Defines the SAML protocol binding to use to send authentication requests to the identity provider. The POST and REDIRECT protocol bindings are supported.

NameID Format – If specified, the AEM Mobile entitlement service will request the response's subject identifier to use the specified format: None, Persistent, Transient, or Unspecified. Use "Unspecified" for Gigya identity providers.

Auth Token Source – Specifies which part of the authentication response contains the auth token. If you use Attribute, specify the name of an attribute in the authentication response that contains the auth token. If the NameID Format is set to Transient, you can select NameID.

Authentication URL – The identity provider URL that AEM Mobile should send the authentication request to.

Public Signing Key Certificate – The X509 certificate of the identity provider's signing public key used by AEM Mobile to validate the assertion signature.

Default Session Expiry – Number of seconds for which a successful sign in response is valid if a duration is not explicitly specified in the response. Once expired, the session will be refreshed if supported by the identity provider; otherwise, the user will be signed out. The default is one hour (3600s).

Experience Manager Mobile Response Endpoint – URL that the identity provider needs to send the assertion response to. You must configure your identity provider to use this value provided by AEM Mobile.

Experience Manager Mobile Public Encryption Key Certificate – The X509 certificate of the encryption public key that can be used by the identity provider to encrypt the key in the authentication response if required.

OAuth 2.0 settings

Authorization Grant Type – Determines the type of authorization grant: Authorization Code or Implicit.

Token Endpoint – Used by AEM Mobile to exchange an authorization code or a refresh token for an access token. HTTPS is highly recommended.

Client Secret – AEM Mobile uses this value to authenticate itself when contacting the token endpoint. The client secret you specify needs to be registered with the identity provider.

Default Session Expiry – Number of seconds in which a successful sign in response is valid if a duration is not explicitly specified in the response. Once expired, the session will be refreshed if supported by the identity provider; otherwise, the user will be signed out. The default is one hour (3600s).

Authorization Endpoint – Used by AEM Mobile to obtain authorization from the identity provider. HTTPS is highly recommended.

Client Identifier – AEM Mobile uses this value to identify itself when contacting the identity provider. The client identifier needs to be registered with the identity provider.

Access Token Scope – Describes the scope of the access request. Use spaces to specify multiple values. Facebook examples: public_profile, email, user_likes, user_friends.

Experience Manager Mobile Redirection Endpoint – Specifies the AEM Mobile URL that the identity provider should redirect to after completing the authorization process. This value provided by AEM Mobile needs to be registered with the identity provider.

Generic settings

Authentication URL –Specify the URL of the website that includes the UI for the sign-in behavior. This website should include information that passes the auth token to the entitlement service when the user signs in.

Default Session Expiry – Number of seconds in which a successful sign in response is valid if a duration is not explicitly specified in the response. Once expired, the session will be refreshed if supported by the identity provider; otherwise, the user will be signed out. The default is one hour (3600s).

Custom authentication notes and best practices

  • After creating the identity provider in Master settings, you cannot change an identity provider type (SAML 2.0 or OAuth 2.0). To change the type, you will need to create a new identity provider.
  • Changing the identity provider on an active project will log out all users.
  • SAML does not support refresh. At the end of a session, a user will have to log in again. This is also true for OAuth if the OAuth provider does not support refresh tokens.
  • Logging out on a device doesn’t necessarily log the user out of the identity provider. The identity provider determines how long the session remains valid.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy