- Q. Do I have to use the provided AWS SNS push service?
- Q. What URL does AWS SNS use for sending push notifications?
- Q. What information is contained in the QR code?
- Q. How do I change what registration or authentication URLs are used?
- Q. Can I use HTTP for push authentication?
- Q. Why am I getting an App Transport Security Policy error?
- Q. Do I have to renew APNS certificates myself?
- Q. Do I need to use an ESV for the AWS Secret Access Key in Identity Cloud?
- Q. What platforms does the ForgeRock Authenticator App support?
- MFA: Push authentication
- Multi-factor authentication
- How To Configure Service Credentials (Push Auth, Docker) in Backstage
If you are using the ForgeRock Authenticator App 1 or 2.x, then you have three options for which push service you want to use:
- You can use the provided AWS SNS push service - in this case, you must use the ForgeRock Authenticator App as is. See the documentation links above.
- You can use your own AWS SNS push service - in which case, you must modify/recompile the App with a new bundle ID.
- You can use your own non-AWS SNS push service - again, you will need to modify/recompile the App with a new bundle ID. See How do I use Push notifications in AM with a non-AWS SNS Push Service? for further information.
Creating your own push service requires customizations and possibly code changes. These changes are outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.
A. All the URLs used by AWS SNS are listed here: AWS Service Endpoints - Amazon Simple Notification Service (Amazon SNS):
- Backstage uses the us-east-1 region, so a valid URL would look similar to this if you use the provided AWS SNS push service: sns.us-east-1.amazonaws.com:443
- If you want to use a different URL, you will need to use your own push service.
You may need to allowlist this URL if Identity Cloud or AM cannot reach it, for example, it is being blocked by a firewall or proxy. AM also needs the SNS Root CA certificate in its Java® truststore when making contact with the SNS servers.
See How To Configure Service Credentials (Push Auth, Docker) in Backstage and How do I troubleshoot failed Amazon SNS push notification deliveries? for further information and troubleshooting steps.
The information contained in the QR code is in the following format:pushauth://push/forgerock:<userId>?a=<authURL>&image=<imageURL>&b=<color>&r=<registerURL>&s=<sharedSecret>&c=<challenge>&l=<lbKey>&m=<msgID>&issuer=<issuer>
- <userId> - the ID of the user.
- a=<authURL> - the authentication endpoint as a base64 encoded URL. For example, https://am.example.com:8443/am/json/push/sns/message?_action=authenticate when decoded.
- image=<imageURL> - the base64 encoded URL of the image to display (optional). For example, http://cloud.example.com/images/qr-code.jpg when decoded.
- b=<color> - the hex code (without the preceding #) of the background color. This is set to 519387 in a non-customized App.
- r=<registerURL> - the registration endpoint as a base64 encoded URL. For example, https://am.example.com:8443/am/json/push/sns/message?_action=register when decoded.
- s=<sharedSecret> - a base64 encoded random shared secret string (cannot be decoded).
- c=<challenge> - a base64 encoded random challenge string (cannot be decoded).
- l=<lbKey> - the load balancer cookie and value as a base64 encoded string. For example, amlbcookie=01 when decoded.
- m=<msgID> - the message ID as a string (cannot be decoded).
- issuer=<issuer> - the name of the issuer as a base64 encoded value. This decodes to ForgeRock in a non-customized App.
An example of the information in a QR code looks like this:pushauth://push/forgerock:demo?a=aHR0cHM6Ly9hbS5leGFtcGxlLmNvbTo4NDQzL2FtL2pzb24vcHVzaC9zbnMvbWVzc2FnZT9fYWN0aW9uPWF1dGhlbnRpY2F0ZQ==&image=aHR0cDovL2Nsb3VkLmV4YW1wbGUuY29tL2ltYWdlcy9xci1jb2RlLmpwZw&b=519387&r=aHR0cHM6Ly9hbS5leGFtcGxlLmNvbTo4NDQzL2FtL2pzb24vcHVzaC9zbnMvbWVzc2FnZT9fYWN0aW9uPXJlZ2lzdGVy&s=XvPlyP6mQxZt-PzDdldx-3sIlg00SN0w45eoOCI&c=1GoaRp2ZMgKh2kRtk6SbyIy80yxvUgT5zfsy1DMs&l=YW1sYmNvb2tpZT0wMQ&m=REGISTER:4383d87f-4d57-4414-841a-a8d82e7b51d15693357446102&issuer=Rm9yZ2VSb2Nr [baseURL]/[context]/json/[realm]/push/sns/message?_action=...
This means you can alter the Base URL Source to change these URLs. See Base URL Source for further information.
As you can see from this example, the realm value is not part of the Base URL Source and is derived separately, which means the realm will always be part of the URL. The only way to remove the realm value or create a different URL is to create your own push service as outlined in Q. Do I have to use the provided AWS SNS push service?
The resulting URLs must be accessible from the internet and via the device because the Authenticator App contacts the registration URL when registering a device. You can check that the expected URLs are actually being used by base64 decoding the relevant parts of the QR code as detailed in Q. What information is contained in the QR code?
A. The following error (seen when scanning the QR code):The resource could not be loaded because the App Transport Security Policy requires the use of a secure connectionSignifies that an insecure URL (HTTP) is being used for authentication and/or registration. You can verify this by base64 decoding the authentication and registration URLs in the QR code.
You can resolve this by changing the authentication and/or registration URLs as described in Q. How do I change what registration or authentication URLs are used?
- If you use the ForgeRock SNS: ForgeRock renews the APNS certificate on your behalf and also updates all SNS endpoints. This means the renewal process should be seamless and your users can continue to authenticate without having to re-register their devices.
- If you use your own SNS: you must renew the APNS certificate yourself and migrate the SNS endpoints for all existing devices to use the new certificate. Failure to do this will mean users have to re-register their devices.
The SNS endpoint looks similar to this:arn:aws:sns:us-east-1:012345678901:app/APNS/TT69G3eg1D99IW8OCid4b4
Where the final part of the endpoint (TT69G3eg1D99IW8OCid4b4 in this example) has a relationship to the APNS certificate. This is the part of the endpoint that needs to change after renewing your APNS certificate so that users can continue to authenticate. It is recommended that you write a script to migrate the SNS endpoints to use the new certificate.
Renewing APNS certificates and migrating the SNS endpoints is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.
A. Yes you do. All encrypted secrets (regardless of how they were created) must be created as ESV secrets.
If you add an encrypted secret directly to the Push Notification service, push notifications won't work and you will see a
The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method error.
See SignatureDoesNotMatch error and push notifications are not working in Identity Cloud for further information.
- iOS® - the ForgeRock Authenticator App works with iOS 9 and above on the iPhone, iPad and iPod Touch.
- Android™ - the ForgeRock Authenticator App works on any device running Android 4 and above.