Configuring a single-page application (SPA) to work with App ID.
New to IBM Cloud App ID? Welcome!
With App ID, you can easily add authentication, authorization, and user profile services to web apps, mobile apps, and APIs with minimal to zero code changes, without redeploying your app. By using App ID, you no longer have to worry about setting up infrastructure, ensuring geo-availability, or trying to understand complex compliance regulations when it comes to managing user identity.
With the SDKs, you can get a sign-in flow going in minutes with Facebook, SAML 2.0, and more. You can also choose to use App ID's scalable user registry (called Cloud Directory) to let your users manage their own account. Additionally, the App ID user profiles feature can be used to store information about your users—such as their preferences—to make their experience of your app personalized and, most importantly, secure.
Understanding the flow
The figure below shows how to securely authenticate and authorize single-page application (SPA) users with the Authorization Code + PKCE flow.
- A user attempts to log in to your single-page application.
- The App ID SDK creates a code verifier for the authorization request, which is the plain text version of the code challenge.
- Along with the authorization request, the client sends the code challenge and the challenge method that is used to encode the challenge.
- The authentication flow is started by App ID in a new window.
- The user chooses an identity provider to authenticate with and completes the sign-in process.
- The App ID SDK on the application receives the grant code.
- The SDK then makes an XHR request to the App ID token endpoint along with the grant code and the code verifier.
- App ID returns access and identity tokens.
Before you get started with your React SPA, be sure that you have the following prerequisites:
- Node.js version 8.10+
- NPM package manager version 5.6+
- IBM Cloud App ID instance with SPA credentials
- A Redirect URI set in the App ID service dashboard
Creating your app
- Set up a frontend build pipelines using create-react-app. Then, move into the project directory:
- Install the IBM Cloud App ID SDK:
- In your code editor in the src directory of the application, open the App.js file. Import App ID by adding the following code:
- In the
main App()function, declare a new App ID instance with useMemo, which recomputes a memorized value when a dependency changes:
- Initialize App ID and add error handling. Add your client ID and discovery endpoint, which can be found in the Applications tab of the App ID dashboard:
- Create a login action that will execute when the login button is clicked. After a successful authentication, the
welcomeDisplayStatewill be set to true and the
userNamewill be set to the name returned in the App ID token:
- Add a welcome div, the login button that calls the login action, and an error div:
- Save all of the files. Your entire App.js file should look like this:
- Open your terminal. Run the following command to access your app from http://localhost:3000:
Make sure you register your redirect_uri (in this case http://localhost:3000/*) with App ID to ensure that only authorized clients are allowed to participate in the authorization workflow. This can be done on the App ID dashboard under the Manage Authentication tab in the Authentication Settings. See the docs for more details.
Well done! You successfully integrated IBM Cloud App ID's SDK for SPA into a React application.
Note: You can view the code repository for our React sample app here.
Tips and things to note
- You can use the App ID client SDK to automatically obtain a new pair of tokens without requiring that the user explicitly sign in. For more information, see Silent login.
- To learn more about security vulnerabilities with the implicit grant type and authorization code flow, visit OAuth 2.0 Security Best Current Practice.
- For more information about how PKCE and the authorization code flow work together, see the spec.
Questions and feedback
- If you have technical questions about App ID, post your question on Stack Overflow and tag your question with
- For questions about the service and getting started instructions, use the IBM Developer Answers forum. Include the
- Open a support ticket in the IBM Cloud menu.
- Reach out directly to the development team on Slack!
To get started with App ID, check it out in the IBM Cloud Catalog.