About Push Notifications in AM/OpenAM
OpenAM 13.5 introduced a new passwordless authentication module that uses push notifications. This module relies on a cloud based notification service provided by ForgeRock to AM/OpenAM customers.
The ForgeRock Authenticator (Push) authentication module introduced in OpenAM 13.5 provides authentication using an additional factor, for example a phone running Android™ or iOS® and the ForgeRock Authenticator app.
The ForgeRock Authenticator (Push) authentication module sends messages through an online push notification service called SNS (provided by Amazon AWS™), which delegates push messages to APNS (Apple Push Notification Service) for iOS devices and GCM (Google Cloud Messaging) for Android devices.
ForgeRock customers who have subscribed for the Push Authentication module for AM/OpenAM can provision Push Authentication credentials in BackStage. Only credentials created via BackStage can be used with the official ForgeRock Authenticator App available in the Apple® App Store and the Google® Play Store.
If you are a ForgeRock customer and AM/OpenAM is part of your subscription, but you do not have access to Push Authentication credentials in BackStage, it means that your contract currently does not include the Push Authentication (AM-PUSH-AUTH) module. To add this module to your subscription, please contact your account manager or our sales team at email@example.com.
Push Notification Service Credentials
The credentials required for the Push Notification Service are the following:
- Amazon IAM User (“sub-account”)
- AWS Key ID
- AWS Key Secret
- Amazon SNS Endpoints
- GCM Endpoint (identified by an ARN)
- APNS Endpoint (identified by an ARN)
- Amazon AWS Region
A set of credentials (and endpoints) can be created for an environment. Each subscription can have multiple projects and each project can have multiple environments, but each environment can only have a single set of credentials, see Working with Projects in BackStage and Working with Environments in BackStage.
Push Notification Service credentials cannot be provisioned for your private projects (that is, projects that are not owned by a subscription).
If your subscriptions do not have any projects, a project must be created first. If the selected project does not have any environments, an environment must also be created before credentials can be provisioned.
To create a project, go to https://backstage.forgerock.com/support/projects/. To create an environment, navigate to an existing project’s details page and click “new environment”.
While you can only provision a single set of credentials per environment, there is no limit to the number of environments a project can have.
BackStage stores each set of credentials created (along with some audit data such as user ID and a timestamp), but it does NOT store the secret key. The secret key must therefore be copied and saved by the user who requested the credentials before they leave or refresh the page.
To provision Push Notification Service credentials for an environment, go to https://backstage.forgerock.com/support/projects/, select (or create) a project, then scroll down to the Environments section and select (or create) an environment.
On the environment details page, scroll down to the Cloud Services section. Under Cloud Services, you should see a panel entitled OpenAM Push Authentication.
If you selected an environment that belongs to a private project or the subscription doesn't have a valid AM/OpenAM subscription, the OpenAM Push Authentication section will not be available.
If there are not credentials for this environment yet, there will be a button labeled Set up Push Auth Credentials.
Clicking the Set up Push Auth Credentials button opens a modal dialog where you can fill in a description, and then submit your provisioning request by clicking Submit.
Once created, the credentials will appear in a modal dialog.
You must save the secret key as it will not be stored by BackStage. There is no way to recover a lost or forgotten secret key.
You must select the correct SNS Client Region (us-east-1).
After the credentials have been provisioned, the controls on environment details page change to allow showing or deleting the credentials.
Credentials can be viewed after they have been created, but the access key secret is no longer there.
Credentials for each environment can be deprovisioned by the user who created the credentials or by any admin member of the subscription that owns the credentials. However, customers can have an unlimited number of projects and environments in BackStage.
Deprovisioning a set of credentials will remove the Amazon IAM user, the policies and SNS endpoints from Amazon, but will keep a record of the credentials in the BackStage database for audit purposes.
BackStage runs an automated task every day to check if there are any Push Auth credentials for customers without a valid subscription. If BackStage finds that a subscription has expired one month ago, it will automatically deprovision any Push Auth credentials that are owned by that subscription.
If the credentials were deprovisioned manually, members of the subscription have the option to provision a new set of credentials for the same environment.