Branding your app

Can I use some of my own and some default screens?

Yes! You can create a hybrid flow that uses some of your screens and some default screens. However, you can use only one option per flow. As an example, you can use your own sign-in screen and also use the default sign-up screen. But, if you choose to use the default sign-up screen, then you must continue to use the default through entire sign-up flow, including sign-up verification.

How are the flows technically different?

The service uses OAuth 2.0 grant flows to map the authorization process. When you configure social identity providers such as Facebook, the Authorization Grant flow is used to call the Login Widget. When you use your own screens, the Resource Owner Password Credentials flow is used to provide access and identity tokens that you can use to call your screens.

Sign in

1. Configure your Cloud Directory settings in the GUI.

2. Add the following code to your application. The sign-in flow is triggered when a user clicks sign in on your custom screen. You get access, identity, and refresh tokens by supplying the user's username and password.

   AppID.getInstance().signinWithResourceOwnerPassword(getApplicationContext(), username, password, new TokenResponseListener() {
      @Override
      public void onAuthorizationFailure (AuthorizationException exception) {
            //Exception occurred
      }
   
      @Override
      public void onAuthorizationSuccess (AccessToken accessToken, IdentityToken identityToken, RefreshToken refreshToken) {
            //User authenticated
      }
   });
   

Sign in

1. Configure your Cloud Directory settings in the GUI.

2. Place the following code in your application. When a user attempts to sign in, your customized screen is called and the authorization and authentication process starts with your customized sign-in page.

   class delegate : TokenResponseDelegate {
      public func onAuthorizationSuccess(accessToken: AccessToken?, identityToken: IdentityToken?, response:Response?) {
      //User authenticated
      }
   
      public func onAuthorizationFailure(error: AuthorizationError) {
      //Exception occurred
      }
   }
   
   AppID.sharedInstance.signinWithResourceOwnerPassword(username: username, password: password, delegate: delegate())
   

Sign in

By using WebAppStrategy, users can sign in to your web apps with their username and a password. After a user successfully signs in to your app, their access token is persisted in an HTTP session while it is kept alive. After the HTTP session is closed or expired, the access token is also destroyed.

1. Configure your Cloud Directory settings in the GUI.

2. Place the following code in your application. When a user attempts to sign in, your customized screen is called and the authorization and authentication process starts.

   app.post("/form/submit", bodyParser.urlencoded({extended: false}), passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
   successRedirect: LANDING_PAGE_URL,
   failureRedirect: ROP_LOGIN_PAGE_URL,
   failureFlash : true // allow flash messages
   }));
   

   Sign-in parameters

   Parameter	Description
   successRedirect	The URL that you want to redirect the user after a successful authentication.
   failureRedirect	The URL that you want to redirect the user to if authentication fails. Users are redirected to the specified URL when the following authentication failures occur: The user inputs an incorrect username or password. The plan limit for the App ID instance was reached.
   failureFlash	When set to true an error message is returned from the Cloud Directory service. By default, the value is set to false.

   If you submit the request in HTML, you can use body parser middleware. To see the returned error message, you can use connect-flash. To see it in action, check out the web app sample.

Sign up

You can use the /sign_up endpoint to allow users to sign themselves up for your app. Supply the following data in the request body:

• Your tenantID.
• Cloud Directory user data with the following required attributes. See SCIM Full User Representation for more details.
  • A password attribute.
  • An emails array with at least one email address and a primary attribute that is set to true.

Depending on your email configuration, a user might receive a request for verification, an email that welcomes them when they sign up for your app, or both. Both types of emails are triggered when a user signs up for your app. The verification email contains a link that the user can click to confirm their identity; a screen is displayed, that thanks them for verifying or confirms that their verification is complete.

To present your own post verification page:

1. Navigate to the Cloud Directory identity provider in the App ID dashboard.
2. Click the Email verification tab.
3. In the custom verification page URL, enter the URL for your landing page.

When this value is provided, App ID calls the URL along with a context query. When you call the /sign_up/confirmation_result endpoint and pass the received context parameter, the result tells you whether your user verified their account. If they have, then you can display your custom page.

Forgot password

You can use the /forgot_password endpoint to allow users to recover their password if they forget it.

Supply the following data in the request body:

• Your tenant ID.
• The email of the Cloud Directory user.

When the endpoint is called, a reset password email is sent to the user. The email contains a Reset button. After they press the button, a screen is displayed by App ID where they can reset their password.

You can present your own post reset password page:

1. Configure your Cloud Directory settings in the GUI. Allow users to manage their account from your app must be set to On.
2. In the Reset Password tab of the service dashboard, be sure that Forgot password email is set to On.
3. Enter the URL for your landing page in the URL for your custom reset password page

When this value is provided, App ID calls the URL along with a context query. The context parameter is used to receive the result when /forgot_password/confirmation_result is called. If the result is successful, then you can display your custom page.

Add a random string to your custom reset password page and pass it to your back-end when the request is submitted. Have your handler validate the string and call the /change_password endpoint only if it is valid. By doing so, you can reduce vulnerability of your back-end reset password endpoint.

Change password

You can use the /change_password endpoint in two ways: when a user submits a reset request, or when a user is signed in to your app and wants to update their password.

Before you call the /change_password API to allow a user to reset their password, it is highly recommended to check whether the context has a successful result by using the /forgot_password/confirmation_result endpoint. This operation adds a higher level of security to your back-end reset password process and ensures that a user can modify their password only if the context is still valid.

To update a user's password after a reset request, supply the following data in the request body:

• Your tenantID.
• The user's new password.
• The Cloud Directory user UUID.
• Optional: The IP address from which the password reset was performed. If you choose to pass the IP address, then the placeholder %{passwordChangeInfo.ipAddress} is available for the change password email template.

Depending on your configuration, when a password is changed App ID sends an email to the user that lets them know that a change was made.

To allow users to change their password while they are signed in to your app, supply the following data in the request body:

• Your tenantID.
• The user's new password.
• The Cloud Directory user UUID.

Your change password page must prompt the user to enter their current password and their new password.

Your back-end validates the user's current password with the ROP API, and if valid, calls the endpoint with the new password. Depending on your configuration, when a password is changed App ID might send an email to the user letting them know that there was a change.

Resend

You can use the /resend/<templateName> to resend an email when a user does not receive it for some reason.

Supply the following data in the request body:

• The tenantID.
• The template name
• The Cloud Directory user UUID.

Change details

When a user is signed in to your app, they can update some of their information. You can use the /Users/<userID> to get and update their information.

When the user details are updated, the endpoint gets the updated user data in the request body in SCIM format. Be sure that you change only the relevant details.

Their email address cannot be changed.