You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To use push notification-based authentication, you need to configure at least one push notification provider in {{ product_name }}. {{ product_name }} supports **Firebase Cloud Messaging (FCM)**and **Amazon Simple Notification Service (SNS)** as push notification providers.
3
+
To send push notifications from {{ product_name }}, you need to configure a Push Provider. {{ product_name }} supports **Firebase Cloud Messaging (FCM)**to send push notifications. With FCM, you can send push notifications to multiple platforms, including Android, iOS, and the web.
4
4
5
5
!!! note
6
-
You can configure **multiple providers** and keep them active at the same time. During enrollment, the device will send the preferred push provider in the registration request. Once successfully registered, {{product_name}} will send push notifications via the device's registered push provider.
6
+
Firebase cloud messaging has the capability to send push notification to iOS devices through Apple Push Notification Service (APNs). However, you need to configure APNs separately to send push notifications to iOS devices.
7
+
For more information, [refer to the Firebase documentation](https://firebase.google.com/docs/cloud-messaging/ios/client).
7
8
8
-
You can also mark one provider as the **default push provider**.
9
-
10
-
The following list shows the platforms that each provider supports.
11
-
12
-
-**FCM**: Android, iOS (APNs), and web.
13
-
-**Amazon SNS**: Android, iOS (APNs), Amazon Fire OS (ADM), Baidu Cloud Push, Windows Phone (MPNS), and Windows (WNS).
14
-
15
-
## Configure the push provider
9
+
Follow the below steps to configure FCM as your Push Provider:
16
10
17
11
1. On the {{ product_name }} Console, go to **Notification Channels** and select **Push Providers**.
Firebase Cloud Messaging can send push notifications to iOS devices through Apple Push Notification Service (APNs). However, you need to configure APNs separately to send push notifications to iOS devices. For more information, [refer to the Firebase documentation](https://firebase.google.com/docs/cloud-messaging/ios/client).
37
-
38
-
### Configure Amazon Simple Notification Service (SNS)
39
-
40
-
1. In the AWS console, create a platform application for each platform you plan to support (for example, FCM or APNs). For instructions, see [Mobile push notifications](https://docs.aws.amazon.com/sns/latest/dg/sns-mobile-application-as-subscriber.html) in the AWS documentation.
41
-
42
-
2. Create an IAM user and attach a policy that grants the following permissions. For guidance on creating IAM users and attaching policies, see the [AWS IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).
43
-
44
-
-`sns:CreatePlatformEndpoint` — register devices with SNS
-`sns:DeleteEndpoint` — unregister devices from SNS
48
-
-`sns:Publish` — send push notifications to device endpoints
49
-
50
-
!!! note
51
-
IAM users are global by default. If desired, you can limit the scope of these permissions to a specific AWS Region by defining the region in the policy's Resource ARN.
52
-
53
-
3. Select the **Amazon SNS** tab on the Push Providers page.
Choose an **AWS region** where Amazon SNS is available and geographically close to **your {{ product_name }}** deployment. This reduces latency between {{ product_name }} and Amazon SNS.
72
-
Because Amazon SNS acts as a push notification hub and the platform, such as FCM or APNs, delivers the final notification to the device, choosing a region close to your user base does not provide a significant latency advantage.
73
-
74
-
## Configure the default push provider
75
-
76
-
When a device does not specify a push provider in its registration request, {{ product_name }} registers the device with the default push provider. This is useful for maintaining backward compatibility with older versions of your authenticator application that do not include provider information in the registration payload.
77
-
78
-
To set a provider as the default:
79
-
80
-
1. Select the tab of the provider you want to set as the default.
Amazon SNS requires additional metadata, such as the `platform` field, in the registration request. For more information, see [Build your own push authenticator app]({{base_path}}/references/tutorials/build-your-own-push-authenticator-app/). Therefore, even if Amazon SNS is configured as the default provider, the registration payload must still include the required metadata.
88
-
89
-
!!! note
90
-
If you configure **only one provider** and do not explicitly set a default provider, {{ product_name }} uses that provider for legacy registration payloads. In that case, {{ product_name }} registers the device with the configured provider. However, we recommend that you still mark the provider as the default if you need legacy payload support.
@@ -17,6 +17,7 @@ A push authenticator application should have the following capabilities:
17
17
{{product_name}} provides the necessary APIs to build your own push authenticator application. The below given guide explains how to build a push authenticator application using the APIs
18
18
provided by {{product_name}}.
19
19
20
+
20
21
## Register push notification device
21
22
22
23
For the users to receive push notifications during an authentication flow, they need to register their devices with the {{product_name}}.
@@ -27,10 +28,10 @@ The registration process starts with the user scanning a QR code that contains t
27
28
can be accessed from the MyAccount portal or when push device progressive enrollment is enabled for an authentication flow of an application.
28
29
29
30
!!! note
30
-
Learn more about enrolling push notification devices [via My Account](../../guides/user-self-service/register-push-notification-device.md)
31
+
Learn more about enrolling push notification devices [via My Account](../../guides/user-self-service/register-push-notification-device.md)
31
32
and [progressive enrollment](../../guides/authentication/mfa/add-push-auth-login.md#enable-push-notification-device-progressive-enrollment).
32
33
33
-
The content encoded in the QR code is retrieved from the response of the push device registration discovery data API endpoint.
34
+
The content encoded in the QR code is retrieved from the response of the push device registration discovery data API endpoint.
34
35
This response contains the following information:
35
36
36
37
<table>
@@ -85,24 +86,25 @@ From above response, information such as the **device ID**, **tenant domain**, *
To send push notifications, {{product_name}} needs a unique identifier for each user's device. This identifier ensures that the notification reaches the correct app instance.
89
-
90
-
Depending on which push notification service you use, the process for obtaining this identifier varies:
89
+
Push notifications are sent to a unique device of a user during the authentication process. These notifications are sent through different push notification services.
90
+
These services identify the device using a **unique identifier**. Since, the IAM system triggers the push notification through the
91
+
push notification service, the device unique identifier should be registered with the IAM system.
91
92
92
-
-**Firebase Cloud Messaging (FCM)**: Since FCM acts as both the platform and the provider, obtain the **registration token** directly from the FCM SDK within your app. Learn more about [Firebase Cloud Messaging Architecture](https://firebase.google.com/docs/cloud-messaging/fcm-architecture){:target="_blank"}.
93
-
-**Amazon SNS**: Since SNS acts as a delivery hub, it requires a token from the underlying platform push service (such as APNs for iOS or FCM for Android). Register the device with the specific platform first to obtain its native token, which SNS then uses to identify the endpoint. For the list of supported platforms, see [Step 5](#step-5-build-the-provider-object).
93
+
{{product_name}} supports Firebase Cloud Messaging (FCM) to send push notifications. Firebase identifies the devices using a unique identifier called the **registration token**.
94
+
This token will be generated by Firebase and assigned to the specific app instance in the device to uniquely identify it.
94
95
95
-
Regardless of the service, retrieve this unique token from the app instance and include it in the registration request to {{product_name}} to enable push authentication.
96
+
!!! note
97
+
Learn more about [Firebase Cloud Messaging Architecture](https://firebase.google.com/docs/cloud-messaging/fcm-architecture){:target="_blank"}.
96
98
97
99
### **Step 3**: Generate public and private key pair
98
100
99
101
Since push notification based authentication leverages asymmetric cryptography to secure the authentication process,
100
102
during the registration process, the device should generate a **public and private key** and securely store the private key on the device.
101
-
The private key is used to sign the authentication response during the authentication process and the public key is used by the IAM system
103
+
The private key is used to sign the authentication response during the authentication process and the public key is used by the IAM system
102
104
to verify the signed authentication response.
103
105
104
-
{{product_name}} supports public and private key pairs generated using the **RSA algorithm** with a key size of **2048 bits**.
105
-
In order to send the public key in the registration request, it should be converted to a **PEM format**, **headers and footers should be removed**,
106
+
{{product_name}} supports public and private key pairs generated using the **RSA algorithm** with a key size of **2048 bits**.
107
+
In order to send the public key in the registration request, it should be converted to a **PEM format**, **headers and footers should be removed**,
106
108
and the content should be **base64 encoded**.
107
109
108
110
### **Step 4**: Generate the signature for registration verification
@@ -118,77 +120,7 @@ send it along with the registration request. The signature should be generated u
118
120
4. Sign the concatenated string using the **RSA private key** that was generated during the registration process. Use **PKCS#1 v1.5 padding** and **SHA-256 hashing** before encryption.
119
121
5. Encode the signature in **base64** format.
120
122
121
-
### **Step 5**: Build the provider object
122
-
123
-
The registration request includes a `provider` object that tells {{product_name}} which push notification provider to use for the device. You must construct this object based on the push provider your organization has configured in {{product_name}}.
124
-
125
-
The `provider` object has the following structure:
126
-
127
-
```json
128
-
"provider": {
129
-
"name": "<provider name>",
130
-
"metadata": {
131
-
"<metadata key>": "<metadata value>"
132
-
}
133
-
}
134
-
```
135
-
136
-
#### Determine the provider name
137
-
138
-
Set `provider.name` to the name of one of the push notification providers that the administrator has configured in {{product_name}} and that your application intends to use for the device. The supported values are:
139
-
140
-
-`FCM` — for Firebase Cloud Messaging
141
-
-`AmazonSNS` — for Amazon Simple Notification Service
142
-
143
-
#### Provider metadata
144
-
145
-
Each provider has different metadata requirements.
146
-
147
-
??? "Firebase Cloud Messaging (FCM)"
148
-
**FCM** does not require any additional metadata. Send an empty object for the `metadata` field.
149
-
150
-
```json
151
-
"provider": {
152
-
"name": "FCM",
153
-
"metadata": {}
154
-
}
155
-
```
156
-
157
-
??? "Amazon Simple Notification Service (SNS)"
158
-
**Amazon SNS** requires a `platform` field that identifies the platform application the device registers with. Set `platform` to the value that matches the device's push platform.
159
-
160
-
| Device type | `platform` value |
161
-
|---|---|
162
-
| Android (Firebase/GCM) | `FCM` |
163
-
| iOS (APNs) | `APNS` |
164
-
| Amazon Fire OS | `ADM` |
165
-
| Windows Phone | `MPNS` |
166
-
| Windows | `WNS` |
167
-
| Baidu | `BAIDU` |
168
-
169
-
```json
170
-
"provider": {
171
-
"name": "AmazonSNS",
172
-
"metadata": {
173
-
"platform": "APNS"
174
-
}
175
-
}
176
-
```
177
-
178
-
!!! note
179
-
If the platform is `BAIDU`, include an additional `userId` field in `metadata`. This is the user identifier that the Baidu platform assigns to the end user.
180
-
181
-
```json
182
-
"provider": {
183
-
"name": "AmazonSNS",
184
-
"metadata": {
185
-
"platform": "BAIDU",
186
-
"userId": "<Baidu user ID>"
187
-
}
188
-
}
189
-
```
190
-
191
-
### **Step 6**: Invoke the registration API
123
+
### **Step 5**: Invoke the registration API
192
124
193
125
As the final step of the registration process, the device should invoke the registration API of the {{product_name}} with the following information:
194
126
@@ -221,10 +153,6 @@ As the final step of the registration process, the device should invoke the regi
221
153
<td><code>signature</code></td>
222
154
<td>Base64 encoded, hashed and encrypted string value signed by the private key from the registering device (From Step 4).</td>
223
155
</tr>
224
-
<tr>
225
-
<td><code>provider</code></td>
226
-
<td>The object containing the push notification provider details for the device. Includes the provider <code>name</code> and any provider-specific <code>metadata</code> required for device registration (From Step 5).</td>
227
-
</tr>
228
156
</table>
229
157
230
158
Based on the registration discovery data response, the push authenticator app should conditionally invoke the relevant
@@ -240,45 +168,18 @@ If response contains the **organization ID**, that means it is an **organization
240
168
241
169
The below given is a sample request payload to be sent to the registration API.
Although it is still supported with default provider configuration, it is highly recommended to use the new request payload. The main purpose for supporting this payload is to be backward compatible with already existing applications.
277
-
278
-
Note that Amazon SNS does not support this payload as it requires additional metadata.
279
179
280
180
Upon successful registration, the registration request will return a **201 Created** response.
281
181
182
+
282
183
## Receive push notifications
283
184
284
185
During a push notification based authentication flow, {{product_name}} builds the data required for the authentication and send it as a push notification through
@@ -355,9 +256,10 @@ The data sent through the push notification contains the following information:
355
256
With the above information, the push authenticator app should display the authentication request information to the user.
356
257
The user should be able to approve or deny the authentication request based on the information displayed.
357
258
259
+
358
260
## Invoke the authentication API
359
261
360
-
The push authentication API endpoint has to be invoked to send an authentication response to the {{product_name}} server from the push authenticator application.
262
+
The push authenticate API endpoint has to be invoked to send an authentication response to the {{product_name}} server from the push authenticator application.
361
263
With this request, the {{product_name}} server will validate the authentication response and complete the authentication flow.
362
264
363
265
The authentication from the push authenticator app should be in the form of a JWT token signed with the private key generated during the registration process.
0 commit comments