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
- Configuring assets template for your mobile app
- Building your mobile app
- Authenticating to your mobile app
- Next steps
Prerequisites
Before configuring your mobile app for SSO with OpenID Connect, do the following tasks:
- Create an OpenID Connect or SAML authentication service
- Configure an OpenID Connect authentication service
- Create and configure an OAuth 2.0 client registration.
- Select the Enable proof key for code exchange check box when dealing with Pega Mobile Client™ to strengthen the security of your mobile app.
- Enable only the Authorization code grant type in the client registration instance that is used in the configuration.
- Provide a unique custom scheme for the redirect URI instead of
http
orhttps
. Custom schemes ensure that a redirection with an authentication code is routed back to the mobile app.
- Configure offlinehttp Service Package to use OAuth 2.0 authentication.
- Set the value of the Authentication type field to OAuth 2.0.
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.
- Clear the Dynamic System Settings for OAuth autorization in Pega Platform if you previously configured them.
- Download and extract the latest branding assets file from Branding assets templates for various Pega Mobile Client versions.
- Open the
custom.properties
file.- 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
- 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 - Compress your branding assets to
assets.zip
file.The compressed file must only contain android and ios folders, and the modifiedcustom.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.
- Add the following parameters and values:
Building your mobile app
After you modify the branding assets file, you are ready to build your application in Pega Platform.
- Upload your branding assets.
- Finish building your app.
- For more information about building Android apps, see Building an Android app.
- For iOS, see Building an iOS app.
If you are accessing the Dev Studio application with an URL that uses an explicit servlet name (for exampleprweb/PRServlet
), select the Use alternative server URL check box and provide the Pega Platform server URL without the servlet component (for examplehttp://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:
- Open your app.
- On the login screen, click Log in.
- 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 thecontainer.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. - 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.
Next steps
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.