Frequently asked questions
- 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. Do I have to renew APNS certificates myself?
- Q. What platforms does the ForgeRock Authenticator app support?
- Q. Can I use HTTP for push authentication?
Q. Do I have to use the provided AWS SNS push service?
- You can use the provided AWS SNS push service - in this case, you must use the ForgeRock authenticator app as is. See the following links for further information:
- 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 (All versions) 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.
Q. What URL does AWS SNS use for sending push notifications?
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 whitelist this URL if 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.
Q. What information is contained in the QR code?
The information contained in the QR code is in the following format:pushauth://push/forgerock:
- [userId] - the ID of the user.
- a=[authURL] - the authentication endpoint as a base64 encoded URL. For example, http://host1.example.com:8080/openam/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, http://host1.example.com:8080/openam/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=aHR0cDovL2hvc3QxLmV4YW1wbGUuY29tOjgwODAvb3BlbmFtL2pzb24vcHVzaC9zbnMvbWVzc2FnZT9fYWN0aW9uPWF1dGhlbnRpY2F0ZQ&image=aHR0cDovL2Nsb3VkLmV4YW1wbGUuY29tL2ltYWdlcy9xci1jb2RlLmpwZw&b=519387&r=aHR0cDovL2hvc3QxLmV4YW1wbGUuY29tOjgwODAvb3BlbmFtL2pzb24vcHVzaC9zbnMvbWVzc2FnZT9fYWN0aW9uPXJlZ2lzdGVy&s=XvPlyP6mQxZt-PzDdldx-3sIlg00SN0w45eoOCI&c=1GoaRp2ZMgKh2kRtk6SbyIy80yxvUgT5zfsy1DMs&l=YW1sYmNvb2tpZT0wMQ&m=REGISTER:4383d87f-4d57-4414-841a-a8d82e7b51d15693357446102&issuer=Rm9yZ2VSb2Nr
Q. How do I change what registration or authentication URLs are used?[baseURL]/[context]/json/[realm]/push/sns/message?_action=...
This means you can alter the Base URL Source to change these URLs. See Reference › 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. There is an RFE to address this: OPENAM-15430 (RFE: Able to have Push Authentication take a custom BaseURL different from the Realm). 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 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?
Q. Do I have to renew APNS certificates myself?
- 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.
Q. What platforms does the ForgeRock Authenticator app support?
- 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.
Q. Can I use HTTP for push authentication?
A. No, you cannot. You must use HTTPS for all communications with the backend and this is enforced by the Authenticator app. Additionally, self signed certificates are not currently permitted although there is an RFE for this: FRA-89 (Allow the use Self-Signed Certs ).