Push authentication
Mobile authentication can be performed via push messages that are sent to the user's mobile device.
The user must have installed a mobile app with the Mobile SDK to use mobile authentication via push messaging. After the user installs the app, they must enroll their app for mobile authentication with push messaging.
The website initiates the mobile authentication at the OneWelcome Identity Platform, which sends a push message via Google's FCM or Apple's APNs service to the mobile device. When the user interacts with the push message, the mobile app is opened. The mobile app asks the user to approve the transaction. For extra security, the user might need to authenticate by entering their PIN, or using biometric authentication (fingerprint, face recognition). This is configurable. The Mobile SDK sends the approval result to the OneWelcome Identity Platform, which then notifies the website.
Configure mobile authentication enrollment rules
Go to the General subsection in General mobile config section to configure the mobile authentication enrollment. Enrollment enabled must be checked for push authentication.
PGP encryption keys are used to enroll devices in order to use mobile authentication with push.
By enabling the Unique PGP keys per enrollment enabled option in General subsection in the admin panel, for every user enrollment a new PGP key pair will be generated. For better performance it is advised to not enable this option.
Configure enrollment for mobile authentication with push rules
To configure push enrollment rules, mobile authentication enrollment must be enabled. Mobile authentication with push enrollment is not possible without mobile authentication enrollment performed upfront.
A user must enroll their push configuration to use mobile authentication via push messaging.
By default, a single user can enroll only a single device for single application. To enroll a different device or re-enroll for an application again, the current device needs to be deleted. For details, see user management and device API. To overcome this limitation, it is possible to change the Push enrollment mode mode:
-
Single device: (Default) Only a single device is allowed per user for a given application, and an attempt to enroll a new device fails.
-
Override allowed: Only a single device is allowed per user for a given application, but enrollment of a new device automatically replaces the previously registered device.
-
Multiple devices: Enrollment of multiple devices is allowed. If this option is enabled, you must be using version 4 of the mobile authentication API. Version 2 and 3 of the mobile authentication API respond with
Not Found(404) with this configuration.
A user can register different devices for different applications regardless of this setting.
Note
When mobile authentication with push is the only second factor authentication method, enabling either override allowed or multiple device support might introduce a security risk. Anyone who has access to the first factor credentials can enroll a new device and use this device for second factor authentication. A decision to enable multiple device support should therefore be taken carefully.
Configure mobile authentication with push
Mobile authentication with push consists of two processes that can be enabled or disabled individually:
-
Device enrollment: This process is used to activate mobile authentication with push for a user on a certain device.
-
Authorization: This process is used to send push messages to users for authorization.
For mobile authentication with push, platform-specific services are offered by the platform vendors (Google and Apple). In the application version configuration section, the administrator can specify the platform of a version and the app version-specific configuration for mobile authentication with push.
To perform the actual authentication with push, some mobile authentication types need to be configured.
iOS
To configure iOS-specific push messaging, go to the Push messaging configuration subsection of the Mobile Authentication section. Click Add push messaging configuration and select the ios platform, to display iOS specific configuration fields:
For iOS applications, the Apple Push Notification service (APNs) is used to send notifications. This service allows clients (such as the OneWelcome Identity Platform) to authenticate using signed JSON web tokens (JWT). This involves some configuration on the part of the administrator.
The overview of the APNs can be found in the Apple developer documentation.
Configure push messaging
Note
The OneWelcome Identity Platform previously used certificate authentication, which was configured per application and used a more complex configuration. The newer token authentication supported by Apple is a much more straightforward process and can be used across all applications per team, which is why support for certificate authentication has been dropped for newer applications (old configurations still work, but should be migrated as soon as possible).
-
Register the mobile application in the Apple developer account
-
Retrieve the Apple developer team ID (you can find it under Account → Membership).
-
Download an APNs auth key from the Apple developer account (making a note of its identifier). This download is in the form of a .p8 file, which is a PKCS#8 encoded EC private key, in PEM format. You can find more information on how to create an APNs authentication token signing key in the Apple Developer Account Help.
The Apple developer team ID and key ID should be entered into the form. The .p8 file should be selected using the form input.
APNs environment
Apple supports two environments: production and development (also known as sandbox). The URLs for these environments are pre-configured. Both environments can be accessed using the same push messaging configuration. The desired environment is therefore not specified in the push messaging configuration. Instead, the desired environment can be configured at the application version level. See app version management for more details.
Application bundle identifier
The application bundle identifier is a unique identifier of an app. It uses the reverse domain name notation. You can find it in the Certificates, Identifiers & Profiles page page of your Apple developer account.
Multiple applications can use the same push messaging configuration. The application bundle identifier is therefore not specified in the push messaging configuration. Instead, the desired application bundle identifier can be configured at the application version level. See app version management for more details.
Android
To configure Android-specific push messaging, go to the Push messaging configuration subsection of the Mobile Authentication section. Click the Add push messaging configuration and select the android platform to display Android-specific configuration fields:
For Android applications, the Firebase Cloud Messaging (FCM) services are used.
Note
Your client application needs to be registered in the Firebase Console to use Firebase. To set up your Android app to use FCM, follow the steps described in Add Firebase to your app FCM guide.
FCM API versions
FCM introduced a new type of APIs, HTTP v1 APIs, which replace existing legacy APIs. Legacy APIs were deprecated on 6/20/2023 and stop working on 6/20/2024. Consequently, all existing push messaging configurations need to migrate to use HTTP v1 APIs as soon as possible.
New push messaging configurations should use HTTP v1 APIs.
Information about the API differences is available here.
Configuration using HTTP v1 FCM APIs
-
Obtain the FCM Service Account Key JSON file from the Firebase Console. A description about how to do this is available here.
-
Proceed to the FCM Push Messaging section of Add Push messaging configuration form.
-
Select the HTTP v1 API FCM API Version.
-
Select downloaded Service Account as FCM Service Account key.
Configuration using legacy FCM APIs (deprecated)
Configure FCM endpoint (optional)
The default endpoint for this service is https://fcm.googleapis.com/fcm/send.
If a different URL is required it can be provided as a push server endpoint, otherwise leave this field empty.
Configure FCM server key
FCM requires an API key to identify the project or application that you want to send push messages for. To configure it, follow the steps described below:
-
Go to your project dashboard in the Firebase Console.
-
Click the cog in the left menu, and select Project Settings.
-
Choose the Cloud messaging tab.
-
Copy the server key and provide it in the FCM Key for server applications field of the Android push messaging configuration in the OneWelcome Identity Platform admin console.
Mobile authentication type configuration
Go to Configuration → Mobile authentication → Mobile authentication types.
The following fields are required:
-
Name: This is used to identify the type when calling the mobile authentication API.
-
Authentication method:
-
Max allowed resends: The maximum number of times the push message or SMS fallback message can be sent for a single mobile authentication transaction. 0 means that resending the message is not allowed.
-
Request expires in: This is the time the user gets to complete the authentication via OTP.
-
Fallback type: The fallback is used when the originally requested mobile authentication method cannot be initialized. For example, a mobile authentication type with the PUSH method can be configured to use SMS as a fallback. In the event that the user has not enrolled any applications for push authentication, the OneWelcome Identity Platform is unable to send a push notification. Instead, it starts SMS authentication.
Optional configurations:
-
Transaction signing: This enables or disables transaction signing when using this mobile authentication type.
-
Default messages: You can pre-configure the message that is sent to the user, per supported language.
Push
To receive push messages, a user must be enrolled for push, in addition to having keys enrolled. For regular push, no refresh token or access token is required for the user, only an enrolled application.
Push with PIN
Push with PIN requires the user to have a refresh token. Therefore, the application used must have PIN authentication enabled. In this application configuration, the max allowed PIN attempts must also be configured. When a user receives a push with a PIN request for this application, the user is disconnected after the maximum number of attempts is exceeded.
Push with fingerprint
A push with fingerprint mobile authentication request can be approved by a valid fingerprint or by a valid PIN. If a user does not have a fingerprint configured or the device does not support it, the PIN can be used. The idea behind this is that the PIN mechanism is more secure than the fingerprint authentication. Therefore, the PIN can be always used as a fallback in this case.
To enable fingerprint authentication for an application, it must have fingerprint authentication enabled.
Push with custom authenticator
A transaction for push with a custom authenticator can be approved via the authentication flow of the custom authenticator or by entering a valid PIN. If the user does not have a custom authenticator configured, they can use the PIN. The PIN is always available.
To enable custom authenticators for an application, it must have configuration for the custom authenticator.
