IBM Cloud Docs

IBM Cloud® App ID is deprecated. As of 01 May 2024, you can't create new instances, and access to free instances will be removed. Existing instances are supported until 01 October 2025. Any instances that still exist on that date will be deleted.

With IBM Cloud® App ID you can use a default UI, called a Login Widget, to allow application users the ability to choose the identity provider that they want to sign in with. If you're using Cloud Directory, the Login Widget also provides additional UI's for extra functionalities such as sign-up, forgot password, multi-factor authentication, and more.

One of the best parts of the Login Widget is that you can start using App ID before you implement any of your own authentication UIs - which makes the developer onboarding experience that much easier.

By default, the Login Widget is enabled to use Facebook, Google, and Cloud Directory. You can change the behavior at any time by choosing which identity providers that you want to configure as an option. When more than one identity provider is enabled, the Login Widget presents a screen where the user can make their identity provider selection. But, if you have a single provider that is enabled, users do not see the previously mentioned selection screen. They are taken directly to the identity provider to begin the sign-in process.

For example, if you're using the default - Facebook, Google, and Cloud Directory - users see the screen. If you enable Facebook only, user's are taken directly to Facebook for authentication.

When you use Cloud Directory, App ID is able to provide you with the extended functionality of user management. The extended functionality also applies to the Login Widget's capabilities. User's that are stored in Cloud Directory can take advantage of the functionality such as signing up or resetting their password directly in the Login Widget. Check out the following table to see which screens you can display for each type of identity provider.

Table 1. The Login Widget screens that each identity provider can display
Login Widget screen	Social identity provider	Enterprise identity provider	Cloud Directory
Sign in
Sign up
Forgot password
Change password
Account details

The Login Widget is dynamic. You can customize the look and feel or identity provider configuration, and the changes are applied immediately. You do not need to update your application code or redeploy your app in any way!

Do you need more customization than the Login Widget provides? You can implement your own, fully customized UI for user sign in, sign up, reset password, and other flows to create an experience that's unique to your app. To get started, check out branding your app.

To customize the screen:

Open the App ID service dashboard.
Select the Login Customization section. You can modify the appearance of the Login Widget to align with your company's brand.
Upload your company's logo by selecting a PNG or JPG file from your local system. The recommended image size is 320 x 320 pixels. The maximum file size is 100 Kb.
Select a header color for the widget from the color picker, or enter the hex code for another color.
Inspect the preview pane, and click Save Changes when you are happy with your customizations. A confirmation message is displayed.
In your browser, refresh your login page to verify your changes.

You can call preconfigured screens with the Android client SDK.

Place the following command in your code.

LoginWidget loginWidget = AppID.getInstance().getLoginWidget();
loginWidget.launch(this, new AuthorizationListener() {
      @Override
      public void onAuthorizationFailure (AuthorizationException exception) {
      //Exception occurred
      }

      @Override
      public void onAuthorizationCanceled () {
      //Authentication canceled by the user
      }

      @Override
      public void onAuthorizationSuccess (AccessToken accessToken, IdentityToken identityToken, refreshToken: RefreshToken) {
      //User authenticated
      }
   });

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.

Add the following code to your app. When a user signs up for your app from your custom screen, the sign-up flow is started. The following call not only registers the user, but can also send a verification email to complete the registration, depending on your Cloud Directory configurations.

LoginWidget loginWidget = AppID.getInstance().getLoginWidget();
loginWidget.launchSignUp(this, new AuthorizationListener() {
   @Override
   public void onAuthorizationFailure (AuthorizationException exception) {
         //Exception occurred
   }

   @Override
   public void onAuthorizationCanceled () {
         //Sign up canceled by the user
   }

   @Override
   public void onAuthorizationSuccess (AccessToken accessToken, IdentityToken identityToken, RefreshToken refreshToken) {
         if (accessToken != null && identityToken != null) {
            //User authenticated
         } else {
            //email verification is required
         }
   }
});

Configure your Cloud Directory settings in the GUI. Allow users to manage their account from your app must be set to On.
In the Reset Password tab of the service dashboard, be sure that Forgot password email is set to On.

Add the following code to your app. When a user clicks "forgot password" in your application, the SDK calls the forgot_password API to send an email to the user that allows them to reset their password.

LoginWidget loginWidget = AppID.getInstance().getLoginWidget();
loginWidget.launchForgotPassword(this, new AuthorizationListener() {
   @Override
   public void onAuthorizationFailure (AuthorizationException exception) {
         //Exception occurred
   }

   @Override
   public void onAuthorizationCanceled () {
         // Forogt password canceled by the user
   }

   @Override
   public void onAuthorizationSuccess (AccessToken accessToken, IdentityToken identityToken, RefreshToken refreshToken) {
         // Forgot password finished, in this case accessToken and identityToken will be null.
   }
});

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.
In the Password changed tab of the service dashboard, set Password changed email to

Call the login widget to start the change details flow.

LoginWidget loginWidget = AppID.getInstance().getLoginWidget();
loginWidget.launchChangeDetails(this, new AuthorizationListener() {
   @Override
   public void onAuthorizationFailure (AuthorizationException exception) {
         // Exception occurred
   }

   @Override
   public void onAuthorizationCanceled () {
         // Changed details canceled by the user
   }

   @Override
   public void onAuthorizationSuccess (AccessToken accessToken, IdentityToken identityToken, RefreshToken refreshToken) {
         // User authenticated, and fresh tokens received
   }
});

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.

Place the following code in your app to start the change password flow.

LoginWidget loginWidget = AppID.getInstance().getLoginWidget();
loginWidget.launchChangePassword(this, new AuthorizationListener() {
   @Override
   public void onAuthorizationFailure (AuthorizationException exception) {
         // Exception occurred
   }

   @Override
   public void onAuthorizationCanceled () {
         // Change password canceled by the user
   }

   @Override
   public void onAuthorizationSuccess (AccessToken accessToken, IdentityToken identityToken, RefreshToken refreshToken) {
         // User authenticated, and fresh tokens received
   }
});

You can call preconfigured screens with the iOS Swift client SDK.

Place the following command in your code.

import IBMCloudAppID
class delegate : AuthorizationDelegate {
   public func onAuthorizationSuccess(accessToken: AccessToken, identityToken: IdentityToken, refreshToken: RefreshToken?) {
         //User authenticated
   }

   public func onAuthorizationCanceled() {
         //Authentication canceled by the user
   }

   public func onAuthorizationFailure(error: AuthorizationError) {
         //Exception occurred
   }
}

AppID.sharedInstance.loginWidget?.launch(delegate: delegate())

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.

Place the following code in your application. When a user attempts to sign up for your application, the login widget is called and displays your custom sign-up page.

class delegate : AuthorizationDelegate {
   public func onAuthorizationSuccess(accessToken: AccessToken?, identityToken: IdentityToken?, refreshToken: RefreshToken?, response:Response?) {
      if accessToken == nil && identityToken == nil {
      //email verification is required
      return
      }
   //User authenticated
   }

   public func onAuthorizationCanceled() {
      //Sign up canceled by the user
   }

   public func onAuthorizationFailure(error: AuthorizationError) {
      //Exception occurred
   }
}

AppID.sharedInstance.loginWidget?.launchSignUp(delegate: delegate())

Configure your Cloud Directory settings in the GUI. Allow users to manage their account from your app must be set to On.
In the Reset Password tab of the service dashboard, be sure that Forgot password email is set to On.

Place the following code in your application. When one of your app users requests that their password is updated, the login widget is called and the process starts.

class delegate : AuthorizationDelegate {
   public func onAuthorizationSuccess(accessToken: AccessToken?, identityToken: IdentityToken?, refreshToken: RefreshToken?, response:Response?) {
      //forgot password finished, in this case accessToken and identityToken will be null.
   }

   public func onAuthorizationCanceled() {
      //forgot password canceled by the user
   }

   public func onAuthorizationFailure(error: AuthorizationError) {
      //Exception occurred
   }
}

AppID.sharedInstance.loginWidget?.launchForgotPassword(delegate: delegate())

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.
In the Password changed tab of the service dashboard, set Password changed email to

Call the login widget to start the change details flow.

class delegate : AuthorizationDelegate {
   public func onAuthorizationSuccess(accessToken: AccessToken?, identityToken: IdentityToken?, refreshToken: RefreshToken?, response:Response?) {
      //User authenticated, and fresh tokens received
   }

   public func onAuthorizationCanceled() {
         //changed details canceled by the user
   }

   public func onAuthorizationFailure(error: AuthorizationError) {
         //Exception occurred
   }
}

AppID.sharedInstance.loginWidget?.launchChangeDetails(delegate: delegate())

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.

Place the following code in your app to start the change password flow.

class delegate : AuthorizationDelegate {
   public func onAuthorizationSuccess(accessToken: AccessToken?, identityToken: IdentityToken?, refreshToken: RefreshToken?, response:Response?) {
         //User authenticated, and fresh tokens received
   }

   public func onAuthorizationCanceled() {
         //change password canceled by the user
   }

   public func onAuthorizationFailure(error: AuthorizationError) {
         //Exception occurred
   }
}

AppID.sharedInstance.loginWidget?.launchChangePassword(delegate: delegate())

You can call preconfigured screens with the Node.js server SDK.

Add a post route to your app that can be called with the username and password parameters and log in by using the resource owner password.

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
}));

WebAppStrategy allows users to sign in to your web apps with a username and password. After a successful login, a user's access token is stored in the HTTP session and is available during the session. After the HTTP session is destroyed or expired, the token is invalid.

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.
Place the following code in your application. When a user attempts to sign up for your application, the login widget is called and displays your custom sign-up page.
```
app.get("/sign_up", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
successRedirect: LANDING_PAGE_URL,
show: WebAppStrategy.SIGN_UP
}));
```

Configure your Cloud Directory settings in the GUI. Allow users to manage their account from your app must be set to On.
In the Reset Password tab of the service dashboard, be sure that Forgot password email is set to On.
Place the following code in your application to pass the show property to WebAppStrategy.FORGOT_PASSWORD. When a user requests that their password to your app be updated, the login widget is called and the process starts.
```
app.get("/forgot_password", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
successRedirect: LANDING_PAGE_URL,
show: WebAppStrategy.FORGOT_PASSWORD
}));
```

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.
In the Password changed tab of the service dashboard, set Password changed email to

Place the following code in your application to pass the show property to WebAppStrategy.FORGOT_PASSWORD to launch the change details form.

app.get("/change_details", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
successRedirect: LANDING_PAGE_URL,
show: WebAppStrategy.CHANGE_DETAILS
}));

Configure your Cloud Directory settings in the GUI. Both Allow users to sign up to your app and Allow users to manage their account from your app must be set to On.
In the Password changed tab of the service dashboard, set Password changed email to

Place the following code in your application to pass the show property to WebAppStrategy.FORGOT_PASSWORD to launch the change details form.

app.get("/change_password", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
successRedirect: LANDING_PAGE_URL,
show: WebAppStrategy.CHANGE_PASSWORD
}));

Using the Login Widget

Understanding the Login Widget

What is the default Login Widget behavior?

Which screens can be displayed for each provider?

Customizing an SSO login flow

Customizing the Login Widget

Displaying the Login Widget with the Android SDK

Sign up

Forgot password

Change details

Change password

Displaying the Login Widget with the iOS Swift SDK

Sign up

Forgot password

Change details

Change password

Displaying the Login Widget with the Node.js SDK

Sign up

Forgot password

Change details

Change password