FAQ

FAQ: Push Services in AM

Last updated Feb 5, 2020

The purpose of this FAQ is to provide answers to commonly asked questions regarding the Push service and notifications in AM.


Frequently asked questions

Q. Do I have to use the provided AWS SNS push service?

A. No, you have three options for which push service you want to use:

Note

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 do I set up AM/OpenAM Push Notification Service credentials? 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?

A. The QR code contains a series of details, including the base64 encoded authentication and registration URLs. These URLs must be accessible externally, that is, from the internet.

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]
      

Where:

  • [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?

A. The registration and authentication URLs are derived from the Base URL Source as follows:

[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?

A. It depends whether you are using the ForgeRock SNS or your own. APNS certificates need renewing on an annual basis else you won't be able to send push notifications.

  • 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.

 SNS endpoints

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.

Note

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?

A. The ForgeRock Authenticator app is available on the following platforms:

  • 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 ).

See Also

How do I set up AM/OpenAM Push Notification Service credentials?

User cannot log in using Push authentication in AM (All versions) and OpenAM 13.5

Related Training

N/A

Related Issue Tracker IDs

FRA-80 (ForgeRock Authenticator Fails Registration for Push with v2.3.1 and Android v7.1.1 )



Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.
Loading...