This content has been archived.

Configuring a mobile app to use external login with OpenID Connect or SAML protocol in Pega 8.1

By using an OpenID Connect identity provider (IdP) with single sign-on, you ensure that user credentials are never shared with the mobile app while providing an easy way to authenticate to Pega Platform™ applications. Accessing mobile apps through an external identity provider increases the security of user data. Pega Platform™ now allows mobile apps to log in by using an external IdP compatible with OpenID Connect (such as Google, Auth0, Okta, and others) or SAML protocol (such as Azure AD).

A mobile app can only access the data from the resource server after presenting a valid access token. An access token is acquired through the OAuth 2.0 authorization code grant process between a mobile app and the Pega Platform server. The Pega Platform server works as an identity broker that delegates the authentication to the external IdP. This IdP is configured in the Pega Platform server as one of the authentication services. To ensure that the token acquisition process is secure, the external login takes place in a system browser that displays the IdP login screen. This process guarantees that the authentication happens outside of the mobile app environment. The Pega Platform server acts as an identity broker, so that you do not have to modify the code of a mobile app. As a result, you can set up full configuration in Pega Platform, allowing it to be used across many apps.

Prerequisites

Before configuring your mobile app for SSO with OpenID Connect, do the following tasks:

Configuring the assets template for your mobile app

You configure most of the authorization settings in the custom.properties file that is available in the assets file. Before you upload your app's branding assets, modify them to support the OAuth 2.0 flow.

  1. Clear the Dynamic System Settings for OAuth autorization in Pega Platform if you previously configured them.
  2. Download and extract the latest branding assets file from Branding assets templates for various Pega Mobile Client versions.
  3. Open the custom.properties file.
    1. Add the following parameters and values:
      container.authentication.servletName=PRMobileOAuth2
      container.authentication.type=oauth2
      container.authentication.oauth2.grantType=authorization_code
      container.authentication.oauth2.scope=openid email profile
      
    2. Add the following parameters and modify the values to reflect the values in your OAuth 2.0 client registration instance:
      container.authentication.oauth2.authorizationEndpoint=https://hostname.rpega.com:8080/prweb/PRRestService/oauth2/v1/authorize
      container.authentication.oauth2.clientId=clientID
      container.authentication.oauth2.clientSecret=clientSecret
      container.authentication.oauth2.tokenEndpoint=https://hostname.rpega.com:8080/prweb/PRRestService/oauth2/v1/token
      container.authentication.oauth2.redirectUri=pega://example.com
      container.authentication.oauth2.userInfoEndpoint=https://hostname.rpega.com:8080/prweb/PRRestService/oauthclients/v1/userinfo/json
      container.authentication.oauth2.tokenRevocationEndpoint=https://hostname.rpega.com:8080/prweb/PRRestService/oauth2/v1/revoke
    3. Compress your branding assets to  assets.zip file.
      The compressed file must only contain android and ios folders, and the modified custom.properties file. Additional folder layers can cause problems during the upload of the assets file. For more information, see Build fails because the updated assets.zip file cannot be uploaded.

Building your mobile app

After you modify the branding assets file, you are ready to build your application in Pega Platform.

  1. Upload your branding assets.
  2. Finish building your app.
    If you are accessing the Dev Studio application with an URL that uses an explicit servlet name (for example prweb/PRServlet), select the Use alternative server URL check box and provide the Pega Platform server URL without the servlet component (for example http://prpcserver.com/prweb). For more information, see Setting up an alternative server URL for Pega Mobile Client.

Authenticating to your mobile app

Your app is now ready for use. To authenticate by using an external login with OpenID Connect, complete the following steps:

  1. Open your app.
  2. On the login screen, click Log in.

  3. To give the app permission to authenticate, click Continue.
    After you click Continue, the app starts an external browser window and loads the URL that is provided in the  container.authentication.oauth2.authorizationEndpoint parameter.

     

    The consent window displays a Pega Platform server URL because Pega Platform acts as an identity broker in this process. The app interacts with the Pega Platform server, and the Pega Platform server interacts directly with the IdP. Authentication is delegated to the external IdP. User's credentials are never shared with the mobile app or the Pega Platform resource server.
  4. Log in to the configured IdP to finish authentication and access the app.
    If more than one authentication service is enabled, the Pega Platform-rendered IdP selector screen is displayed. Choose which IdP you want to use for authentication.

When the Pega Platform server receives an access token the interaction with the external IdP ends. At this point, authorization is handled between the app and the Pega Platform server. If a refresh token was issued, the access token is refreshed without repeating the login process. The login screen is only displayed again when the mobile app no longer has a valid access token. You can also unlock mobile apps that use an external IdP compatible with OpenID Connect or SAML for login by using the device's PIN or a biometric sensor, instead of using an application-specific password. For more information, see Using a device lock to protect your mobile app.

Suggest Edit

100% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.