{"id":19773170,"url":"https://github.com/ibm-cloud-security/appid-serversdk-nodejs","last_synced_at":"2025-07-06T11:33:14.622Z","repository":{"id":37549953,"uuid":"79605439","full_name":"ibm-cloud-security/appid-serversdk-nodejs","owner":"ibm-cloud-security","description":"Node.js SDK for the IBM Cloud App ID service","archived":false,"fork":false,"pushed_at":"2024-09-30T05:30:58.000Z","size":2826,"stargazers_count":30,"open_issues_count":16,"forks_count":36,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-04T12:58:20.767Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibm-cloud-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-20T22:17:40.000Z","updated_at":"2024-11-05T10:19:42.000Z","dependencies_parsed_at":"2024-12-13T19:12:02.757Z","dependency_job_id":"0eafdae2-0a41-430b-b37f-0e251c3b341d","html_url":"https://github.com/ibm-cloud-security/appid-serversdk-nodejs","commit_stats":{"total_commits":371,"total_committers":43,"mean_commits":8.627906976744185,"dds":0.7681940700808625,"last_synced_commit":"7be2d61dd9fe1d5af881438b978fdc10785a79fe"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/ibm-cloud-security/appid-serversdk-nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fappid-serversdk-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fappid-serversdk-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fappid-serversdk-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fappid-serversdk-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibm-cloud-security","download_url":"https://codeload.github.com/ibm-cloud-security/appid-serversdk-nodejs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fappid-serversdk-nodejs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263893565,"owners_count":23526312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:08:52.895Z","updated_at":"2025-07-06T11:33:14.594Z","avatar_url":"https://github.com/ibm-cloud-security.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IBM Cloud App ID Node.js SDK\n\n[![IBM Cloud powered][img-ibmcloud-powered]][url-ibmcloud]\n[![Coveralls][img-coveralls-master]][url-coveralls-master]\n[![Version][img-version]][url-npm]\n[![DownloadsMonthly][img-npm-downloads-monthly]][url-npm]\n[![DownloadsTotal][img-npm-downloads-total]][url-npm]\n[![License][img-license]][url-npm]\n\n[![GithubWatch][img-github-watchers]][url-github-watchers]\n[![GithubStars][img-github-stars]][url-github-stars]\n[![GithubForks][img-github-forks]][url-github-forks]\n\n## Table of Contents\n* [Summary](#summary)\n* [Requirements](#requirements)\n* [Migrating from v6 to v7](#migrating-from-v6-to-v7)\n* [Installation](#installation)\n* [Example Usage](#example-usage)\n* [License](#license)\n\n## Summary\n\nThis SDK provides Passport.js strategies for protecting two types of resources - APIs and Web applications. The major difference between these two resource types is the way client is challenged.\n\nIf you use the API protection strategy the unauthenticated client will get HTTP 401 response with list of scopes to obtain authorization for as described below.\n\nIf you use the Web application protection strategy the unauthenticated client will get HTTP 302 redirect to the login page hosted by App ID service (or, depending on configuration, directly to identity provider login page). WebAppStrategy, as the name suggests, best fit for building web applications.\n\nIn addition, the SDK provides helper utilities centered around tokens and user profiles. The token manager supports token retrieval for additional flows such as Application Identity and Custom Identity, as well as token specific functions. The user profile manager supports helper functions that retrieve identity provider and custom profile information about the user.\n\nRead the [official documentation](https://cloud.ibm.com/docs/appid?topic=appid-getting-started) for information about getting started with IBM Cloud App ID Service.\n\n## Requirements\n* npm 6.+\n* node 12.+\n* passport.js 0.6.0+\n\n## Migrating from v6 to v7\nBreaking changes in passport.js require users to pass the `{ keepSessionInfo: true }` object to the middleware when protecting endpoints when using WebAppStrategy.\n\nOld Usage (SDK v6):\n```\napp.use(passport.authenticate(WebAppStrategy.STRATEGY_NAME));\napp.get(CALLBACK_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME));\n```\nNew Usage (SDK v7):\nIn SDK version 7, when using webappStrategy, you need to pass { keepSessionInfo: true } to the passport.authenticate method. Update your code as follows:\n\n```\napp.use(passport.authenticate(WebAppStrategy.STRATEGY_NAME, { keepSessionInfo: true }));\napp.get(CALLBACK_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME, { keepSessionInfo: true }));\n```\n\n## Installation\n```\nnpm install --save ibmcloud-appid\n```\n\n## Example Usage\nBelow find two examples of using this SDK to protect APIs and Web applications. Both samples are available under `samples` folder in this repository.\n\nNote that below examples are using additional npm modules. In order to install required npm modules run below commands in your node.js application.\n```\nnpm install --save express\nnpm install --save log4js\nnpm install --save passport\nnpm install --save express-session\nnpm install --save pug\n```\n\n#### Protecting APIs using the APIStrategy\nAPIStrategy expects request to contain an Authorization header with valid access token and optionally identity token. See App ID docs for additional information. The expected header structure is `Authorization=Bearer {access_token} [{id_token}]`\n\nIn case of invalid/expired tokens the APIStrategy will return HTTP 401 with `Www-Authenticate=Bearer scope=\"{scope}\" error=\"{error}\"`. The `error` component is optional.\n\nIn case of valid tokens the APIStrategy will pass control to the next middleware while injecting the `appIdAuthorizationContext` property into request object. This property will contain original access and identity tokens as well as decoded payload information as plain JSON objects.\n\n```JavaScript\nconst express = require('express');\nconst log4js = require('log4js');\nconst passport = require('passport');\nconst APIStrategy = require(\"ibmcloud-appid\").APIStrategy;\n\nconst app = express();\nconst logger = log4js.getLogger(\"testApp\");\n\napp.use(passport.initialize());\n\n// The oauthServerUrl value can be obtained from Service Credentials\n// tab in the App ID Dashboard. You're not required to provide this argument if\n// your node.js application runs on IBM Cloud and is bound to the\n// App ID service instance. In this case App ID configuration will be obtained\n// using VCAP_SERVICES environment variable.\npassport.use(new APIStrategy({\n\toauthServerUrl: \"{oauth-server-url}\"\n}));\n\n// Declare the API you want to protect\napp.get(\"/api/protected\",\n\n\tpassport.authenticate(APIStrategy.STRATEGY_NAME, {\n\t\tsession: false\n\t}),\n\tfunction(req, res) {\n\t\t// Get full appIdAuthorizationContext from request object\n\t\tvar appIdAuthContext = req.appIdAuthorizationContext;\n\n\t\tappIdAuthContext.accessToken; // Raw access_token\n\t\tappIdAuthContext.accessTokenPayload; // Decoded access_token JSON\n\t\tappIdAuthContext.identityToken; // Raw identity_token\n\t\tappIdAuthContext.identityTokenPayload; // Decoded identity_token JSON\n\t\tappIdAuthContext.refreshToken // Raw refresh_token\n\n\t\t// Or use user object provided by passport.js\n\t\tvar username = req.user.name || \"Anonymous\";\n\t\tres.send(\"Hello from protected resource \" + username);\n\t}\n);\n\nvar port = process.env.PORT || 1234;\n\napp.listen(port, function(){\n\tlogger.info(\"Send GET request to http://localhost:\" + port + \"/api/protected\");\n});\n\n```\n\n##### Protecting APIs using the APIStrategy: Access Control\nUsing access control, you can define the scopes that are required to access a specific endpoint.\n```JavaScript\napp.get(\"/api/protected\",\n\tpassport.authenticate(APIStrategy.STRATEGY_NAME, {\n\t\taudience: \"myApp\",\n\t\tscope: \"read write update\"\n\t}),\n\tfunction(req, res) {\n\t\tres.send(\"Hello from protected resource\");\n\t}\n);\n```\nThe scope parameter defines the required scopes.\nThe audience parameter is optional and should be set to the application clientId\nto guarantee the scopes are for the requested application.\n\n#### Protecting web applications using WebAppStrategy\nWebAppStrategy is based on the OAuth2 authorization_code grant flow and should be used for web applications that use browsers. The strategy provides tools to easily implement authentication and authorization flows. When WebAppStrategy provides mechanisms to detect unauthenticated attempts to access protected resources. The WebAppStrategy will automatically redirect user's browser to the authentication page. After successful authentication user will be taken back to the web application's callback URL (redirectUri), which will once again use WebAppStrategy to obtain access, identity and refresh tokens from App ID service. After obtaining these tokens the WebAppStrategy will store them in HTTP session under WebAppStrategy.AUTH_CONTEXT key. In a scalable cloud environment it is recommended to persist HTTP sessions in a scalable storage like Redis to ensure they're available across server app instances.\n\n```JavaScript\nconst express = require('express');\nconst session = require('express-session')\nconst log4js = require('log4js');\nconst passport = require('passport');\nconst WebAppStrategy = require('ibmcloud-appid').WebAppStrategy;\n\nconst app = express();\nconst logger = log4js.getLogger(\"testApp\");\n\napp.use(passport.initialize());\n\n// Below URLs will be used for App ID OAuth flows\nconst LANDING_PAGE_URL = \"/web-app-sample.html\";\nconst LOGIN_URL = \"/ibm/cloud/appid/login\";\nconst CALLBACK_URL = \"/ibm/cloud/appid/callback\";\nconst LOGOUT_URL = \"/ibm/cloud/appid/logout\";\n\n// Setup express application to use express-session middleware\n// Must be configured with proper session storage for production\n// environments. See https://github.com/expressjs/session for\n// additional documentation.\n\n// Also, if you plan on explicitly stating cookie usage with the\n// \"sameSite\" attribute, you can set the value to \"Lax\" or \"None\"\n// depending on your preferences. However, note that setting the\n// value to \"true\" will assign the value \"Strict\" to the sameSite\n// attribute which will result into an authentication error because\n// setting the \"Strict\" value will cause your browser not to send your \n// cookies after the redirect that happens during the authentication process.\n\napp.use(session({\n\tsecret: '123456',\n\tresave: true,\n\tsaveUninitialized: true\n}));\n\n// Use static resources from /samples directory\napp.use(express.static(\"samples\"));\n\n// Configure express application to use passportjs\napp.use(passport.initialize());\napp.use(passport.session());\n\n// Below configuration can be obtained from Service Credentials\n// tab in the App ID Dashboard. You're not required to manually provide below\n// configuration if your node.js application runs on IBM Cloud and is bound to the\n// App ID service instance. In this case App ID configuration will be obtained\n// automatically using VCAP_SERVICES environment variable.\n//\n// The redirectUri value can be supplied in three ways:\n// 1. Manually in new WebAppStrategy({redirectUri: \"....\"})\n// 2. As environment variable named `redirectUri`\n// 3. If none of the above was supplied the App ID SDK will try to retrieve\n//    application_uri of the application running on IBM Cloud and append a\n//    default suffix \"/ibm/cloud/appid/callback\"\npassport.use(new WebAppStrategy({\n\ttenantId: \"{tenant-id}\",\n\tclientId: \"{client-id}\",\n\tsecret: \"{secret}\",\n\toauthServerUrl: \"{oauth-server-url}\",\n\tredirectUri: \"{app-url}\" + CALLBACK_URL\n}));\n\n// Configure passportjs with user serialization/deserialization. This is required\n// for authenticated session persistence across HTTP requests. See passportjs docs\n// for additional information http://passportjs.org/docs\npassport.serializeUser(function(user, cb) {\n\tcb(null, user);\n});\n\npassport.deserializeUser(function(obj, cb) {\n\tcb(null, obj);\n});\n\n// Explicit login endpoint. Will always redirect browser to login widget due to {forceLogin: true}. If forceLogin is set to false the redirect to login widget will not occur if user is already authenticated\napp.get(LOGIN_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tforceLogin: true\n}));\n\n// Callback to finish the authorization process. Will retrieve access and identity tokens/\n// from App ID service and redirect to either (in below order)\n// 1. the original URL of the request that triggered authentication, as persisted in HTTP session under WebAppStrategy.ORIGINAL_URL key.\n// 2. successRedirect as specified in passport.authenticate(name, {successRedirect: \"....\"}) invocation\n// 3. application root (\"/\")\napp.get(CALLBACK_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME));\n\n// Logout endpoint. Clears authentication information from session\napp.get(LOGOUT_URL, function(req, res){\n\tWebAppStrategy.logout(req);\n\tres.redirect(LANDING_PAGE_URL);\n});\n\n// Protected area. If current user is not authenticated - redirect to the login widget will be returned.\n// In case user is authenticated - a page with current user information will be returned.\napp.get(\"/protected\", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){\n\tres.json(req.user);\n});\n\n// Start the server!\napp.listen(process.env.PORT || 1234);\n```\n\n##### Protecting web applications using WebAppStrategy: Access Control\nUsing access control, you can check which scopes exist on the request.\n```JavaScript\napp.get(\"/protected\", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){\n    if(WebAppStrategy.hasScope(req, \"read write\")){\n      \tres.json(req.user);\n    }\n    else {\n        res.send(\"insufficient scopes!\");\n    }\n});\n```\nUse WebAppStrategy's hasScope method to check if a given request has some specific scopes.\n\n#### Anonymous login\nWebAppStrategy allows users to login to your web application anonymously, meaning without requiring any credentials. After successful login the anonymous user access token will be persisted in HTTP session, making it available as long as HTTP session is kept alive. Once HTTP session is destroyed or expired the anonymous user access token will be destroyed as well.  \n\nTo allow anonymous login for a particular URL use two configuration properties as shown on a code snippet below:\n* `allowAnonymousLogin` - set this value to true if you want to allow your users to login anonymously when accessing this endpoint. If this property is set to true no authentication will be required. The default value of this property is `false`, therefore you must set it explicitly to allow anonymous login.\n* `allowCreateNewAnonymousUser` - By default a new anonymous user will be created every time this method is invoked unless there's an existing anonymous access_token stored in the current HTTP session. In some cases you want to explicitly control whether you want to automatically create new anonymous user or not. Set this property to `false` if you want to disable automatic creation of new anonymous users. The default value of this property is `true`.  \n\n```JavaScript\nconst LOGIN_ANON_URL = \"/ibm/cloud/appid/loginanon\";\n\n// Explicit anonymous login endpoint\napp.get(LOGIN_ANON_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tallowAnonymousLogin: true,\n\tallowCreateNewAnonymousUser: true\n}));\n```\n\nAs mentioned previously the anonymous access_token, identity_token and refresh_token (optional) will be automatically persisted in HTTP session by App ID SDK. You can retrieve them from HTTP session via same mechanisms as regular tokens. Access and identity tokens will be kept in HTTP session and will be used until either them or HTTP session expires.\n\n### Refresh Token\nRefresh Token may be used to acquire new access and identity tokens without the need to re-authenticate. Refresh Token is usually configured to have longer expiration than access token. Refresh Token is optional and can be configured in your App ID Dashboard.\n\nAfter a successful login, in addition to access_token and identity_token, a refresh_token will be persisted in the HTTP session as well.\n\nYou may persist the refresh_token in any method you'd like. By doing so, you can avoid your users login after the HTTP session has expired as long as the refresh_token is valid. `web-app-sample-server.js` contains an example of storing a refresh-token in a cookie and how to use it.\n\nIn order to use the persisted refresh_token, you need to call `webAppStrategy.refreshTokens(request, refreshToken)`. `refreshTokens()` returns a Promise. After the Promise has resolved, the user will be authenticated and new tokens will be generated and persistent in the HTTP session like in a classic login. If the Promise is rejected, the user won't be authenticated.\n\n### Token Manager\n\nThe `tokenManager` object provides token helper functions as well as retrieves tokens generated as a result of the Custom Identity and Application Identity flows. The `tokenManager` object can be initialized in two ways.\n\nIn the first case, the application has already configured the SDK with the App ID service configuration using other managers, and so `TokenManager` can simply inherit the configurations:\n\n```javascript\nconst TokenManager = require('ibmcloud-appid').TokenManager;\n```\n\nIn the second case, the application can directly configured the SDK with the App ID service configuration using the `TokenManager` object:\n\n```javascript\nconst config = {\n\ttenantId: \"{tenant-id}\",\n\tclientId: \"{client-id}\",\n\tsecret: \"{secret}\",\n\toauthServerUrl: \"{oauth-server-url}\"\n};\n\nconst TokenManager = require('ibmcloud-appid').TokenManager(config);\n```\n\n### Custom Identity\nApp ID's custom identity flow enables developers to utilize their own authorization protocols, while still leveraging App ID's capabilities. Instead of managing the entirety of the authorization flow, App ID's custom identity flow allows clients to leverage their own authorization protocol to authenticate and authorize their users and then provides a framework for exchanging verified authentication data securely for App ID tokens.\n\nTo utilize the custom identity flow, the user must first register a public key in PEM form using the App ID Dashboard. The user must generate a signed JWT using any open source library and then the user can then use `TokenManager.getCustomIdentityTokens(jwsTokenString, scopes)` to exchange the token for access and identity tokens. `getCustomIdentityTokens()` is an asynchronous function that returns the access token and identity token. These tokens can be stored in the HTTP session for future use. `custom-identity-app-sample-server.js` contains an example of using the Token Manager.\n\nRefer to the [documentation on custom identity](https://cloud.ibm.com/docs/appid?topic=appid-custom-identity) for more details on how to implement App ID's custom identity flow in your application.\n\n\n### Application Identity and Authorization\n\nIn case you want to call protected APIs from applications or clients that are non-interactive (i.e., there is no user involved), you can use the App ID application identity and authorization flow to secure your applications.   \n\nApp ID application authorization implements the OAuth2.0 Client Credentials grant.\n\nBefore you can obtain access tokens using the application authorization flow, you need to obtain a `client ID` and a `secret` by registering your application with your App ID instance. Refer to the [App ID application identity and authorization documentation](https://cloud.ibm.com/docs/appid?topic=appid-app) on how to register your applications.\n\nSince the application needs to store the `client ID` and the `secret`, this flow must never be used with untrusted clients such as mobile clients and browser based applications.\n\nAlso, note that this flow only returns an access token and no identity or refresh tokens are issued.\n\nThe code snippet below describes how to obtain the access token for this flow.\n\n```javascript\nconst config = {\n\ttenantId: \"{tenant-id}\",\n\tclientId: \"{client-id}\",\n\tsecret: \"{secret}\",\n\toauthServerUrl: \"{oauth-server-url}\"\n};\n\nconst TokenManager = require('ibmcloud-appid').TokenManager;\n\nconst tokenManager = new TokenManager(config);\n\nasync function getAppIdentityToken() {\n\ttry {\n\t\t\tconst tokenResponse = await tokenManager.getApplicationIdentityToken();\n\t\t\tconsole.log('Token response : ' + JSON.stringify(tokenResponse));\n\n\t\t\t//the token response contains the accessToken, expiresIn, tokenType\n\n\t} catch (err) {\n\t\t\tconsole.log('err obtained : ' + err);\n\t}\n}\n```\nFor more detailed information on using the application identity and authorization flow, refer to the [App ID documentation](https://cloud.ibm.com/docs/appid?topic=appid-app).\n\n### Manage User Profile\nUsing the App ID UserProfileManager, you are able to create, delete, and retrieve user profile attributes as well as get additional info about a user.\n\n```javascript\nconst userProfileManager = require(\"ibmcloud-appid\").UserProfileManager;\nuserProfileManager.init();\nvar accessToken = req.session[WebAppStrategy.AUTH_CONTEXT].accessToken;\n\n// get all attributes\nuserProfileManager.getAllAttributes(accessToken).then(function (attributes) {\n\n        });\n\n// get single attribute\nuserProfileManager.getAttribute(accessToken, name).then(function (attributes) {\n\n        });\n\n// set attribute value\nuserProfileManager.setAttribute(accessToken, name, value).then(function (attributes) {\n\n        });\n\n// delete attribute\nuserProfileManager.deleteAttribute(accessToken, name).then(function () {\n\n        });\n\n// retrieve user info\nuserProfileManager.getUserInfo(accessToken).then(function (userInfo) {\n\n        });\n\n// (recommended approach) retrieve user info and validate against the given identity token\nuserProfileManager.getUserInfo(accessToken, identityToken).then(function (userInfo) {\n\n        });\n\n```\n## Cloud Directory\nMake sure to that Cloud Directory identity provider set to **ON** in the App ID dashboard and that you've included a callback endpoint.\n\n### Login using resource owner password flow\nWebAppStrategy allows users to login to your web application using username/password.\nAfter successful login, the user access token will be persisted in HTTP session, making it available as long as HTTP session is kept alive. Once HTTP session is destroyed or expired the user access token will be destroyed as well.\nTo allow login using username/password add to your app a post route that will be called with the username and password parameters.\n```javascript\napp.post(\"/form/submit\", bodyParser.urlencoded({extended: false}), passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tfailureRedirect: ROP_LOGIN_PAGE_URL,\n\tfailureFlash : true // allow flash messages\n}));\n```\n* `successRedirect` - set this value to the url you want the user to be redirected after successful authentication, default: the original request url. (in this example:\"/form/submit\")\n* `failureRedirect` - set this value to the url you want the user to be redirected in case authentication fails, default: the original request url. (in this example:\"/form/submit\")\n* `failureFlash` - set this value to true if you want to receive the error message that returned from cloud directory service, default: false\n\nNote:\n1. If you submitting the request using a html form, use [body-parser](https://www.npmjs.com/package/body-parser) middleware.\n2. Use [connect-flash](https://www.npmjs.com/package/connect-flash) for getting the returned error message. see the web-app-sample-server.js.\n\n### Sign up\nPass WebAppStrategy \"show\" property and set it to WebAppStrategy.SIGN_UP, will launch the App ID sign up form.\n```javascript\napp.get(\"/sign_up\", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tshow: WebAppStrategy.SIGN_UP\n}));\n```\nNote:\n1. If your Cloud directory setting ***Allow users to sign-in without email verification** is set to **No**, the process will end without retrieving App ID access and id tokens.\n2. Be sure to set **Allow users to sign up and reset their password\" to **ON**, in the settings for Cloud Directory.\n\n\n### Forgot Password\nPass WebAppStrategy \"show\" property and set it to WebAppStrategy.FORGOT_PASSWORD, will launch the App ID forgot password from.\n```javascript\napp.get(\"/forgot_password\", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tshow: WebAppStrategy.FORGOT_PASSWORD\n}));\n```\nNote:\n1. This process will end without retrieving App ID access and id tokens.\n2. Make sure to set \"Allow users to sign up and reset their password\" and \"Forgot password email\" to ON, in Cloud Directory settings that are in the App ID dashboard.\n\n### Change Details\nPass WebAppStrategy \"show\" property and set it to WebAppStrategy.CHANGE_DETAILS, will launch the App ID change details from.\n```javascript\napp.get(\"/change_details\", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tshow: WebAppStrategy.CHANGE_DETAILS\n}));\n```\nNote:\n1. This call requires that the user is authenticated with Cloud directory identity provider.\n2. Make sure to set \"Allow users to sign up and reset their password\" to ON, in Cloud Directory settings that are in the App ID dashboard.\n\n### Change Password\nPass WebAppStrategy \"show\" property and set it to WebAppStrategy.CHANGE_PASSWORD, will launch the App ID change password from.\n```javascript\napp.get(\"/change_password\", passport.authenticate(WebAppStrategy.STRATEGY_NAME, {\n\tsuccessRedirect: LANDING_PAGE_URL,\n\tshow: WebAppStrategy.CHANGE_PASSWORD\n}));\n```\nNote:\n1. This call requires that the user is authenticated with Cloud directory identity provider.\n2. Make sure to set \"Allow users to sign up and reset their password\" to ON, in Cloud Directory settings that are in App ID dashboard.\n\n### Self Service APIs\n\nUse the self service manager when you want to control the UI for the sign-up, forgot password, changeDetail and change password flows.\nThe selfServiceManager can be init with the following options:\n\n* iamApiKey: If supplied, it will be used to get iamToken before every request of the selfServiceManager.\n* managementUrl: The App ID management url.\n\n```javascript\n// The managementUrl value can be obtained from Service Credentials tab in the App ID Dashboard.\n// You're not required to provide the managementUrl and the iamApiKey arguments if\n// your node.js application runs on IBM Cloud and is bound to the App ID service instance.\n// In this case App ID configuration will be obtained using VCAP_SERVICES environment variable,\n// during resource-binding process an auto generated apikey is created for you and it can be found in the VCAP_SERVICES environment variable.\n// (if you wish to use diffrent IAM api key you can supply it to the iamApiKey).\n// Note: If your Service Credentials does not contain managementUrl you can supply the tenantId, and the oauthServerUrl instead.\nconst SelfServiceManager = require(\"ibmcloud-appid\").SelfServiceManager;\nlet selfServiceManager = new SelfServiceManager({\n\tiamApiKey: \"{iam-api-key}\",\n\tmanagementUrl: \"{management-url}\"\n});\n```\n\nThe self service manger exposed the following APIs, each API can get 'iamToken' as optional parameter, if passed it will be added to the App ID management request.\nYou must supply 'iamApikey' to the selfServiceManager otherwise you must supply the 'iamToken' to each of the selfServiceManager APIs.\n\n#### Sign-up\nSign up a new user.\nuserData is a JSON object with the user SCIM profile (https://tools.ietf.org/html/rfc7643#page-35).\nlanguage currently unused, default to 'en'.\n\n```javascript\nselfServiceManager.signUp(userData, language, iamToken).then(function (user) {\n\t\t\tlogger.debug('user created successfully');\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n\n#### Forgot Password\nForgot password flow.\nemail is the user email that request the forgot password request.\nlanguage currently unused, default to 'en'.\n\n```javascript\nselfServiceManager.forgotPassword(email, language, iamToken).then(function (user) {\n\t\t\tlogger.debug('forgot password success');\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n\n#### Resend Notification\nResend notification.\nuuid is the Cloud Directory user uuid.\ntemplateName is the template to be send.\nlanguage currently unused, default to 'en'.\n\n```javascript\nselfServiceManager.resendNotification(uuid, templateName, language, iamToken).then(function () {\n\t\t\tlogger.debug('resend success');\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n#### Get Sign-up confirmation result\nGet the stored result for the sign up confirmation.\nThis should be called to verify the authenticity of the sign up verification.\ncontext is a random string that will be supply by App ID, for authenticity purposes.\nreturn a JSON with a 'success' and 'uuid' properties. if 'success' is false additional 'error' property containing 'code' and 'description' properties will be added.\n\n```javascript\nselfServiceManager.getSignUpConfirmationResult(context, iamToken).then(function (result) {\n\t\t\tlogger.debug('returned result: ' + JSON.stringify(result));\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n#### Get Forgot password confirmation result\nGet the stored result for the forgot password confirmation.\nThis should be called to verify the authenticity of the forgot password request.\ncontext is a random string that will be supply by App ID, for authenticity purposes.\nreturn a JSON with a 'success' and 'uuid' properties. if 'success' is false additional 'error' property containing 'code' and 'description' properties will be added.\n\n```javascript\nselfServiceManager.getForgotPasswordConfirmationResult(ucontext, iamToken).then(function (result) {\n            logger.debug('returned result: ' + JSON.stringify(result));\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n#### Set User new password\nChange the user passowrd.\nuuid is the Cloud Directory user uuid.\nnewPassword the new password to be set.\nlanguage currently unused, default to 'en'.\nchangedIpAddress (optional) is the ip address that trigger the change password request, if supply the placeholder %{passwordChangeInfo.ipAddress} will be available with that value, for change password email template.\n\n```javascript\nselfServiceManager.setUserNewPassword(uuid, newPassword, language, changedIpAddress, iamToken).then(function (user) {\n\t\t\tlogger.debug('user password changed');\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n#### Get user details\nGets the stored details of the Cloud directory user.\nuuid is the Cloud Directory user uuid.\n\n```javascript\nselfServiceManager.getUserDetails(uuid, iamToken).then(function (user) {\n\t\t\tlogger.debug('user details:'  + JSON.stringify(user));\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n#### Update user details\nupdate the user details.\nuuid is the Cloud Directory user uuid.\nuserData is a JSON object with the updated user SCIM profile (https://tools.ietf.org/html/rfc7643#page-35).\n\n```javascript\nselfServiceManager.updateUserDetails(uuid, userData, iamToken).then(function (user) {\n\t\t\tlogger.debug('user created successfully');\n\t\t}).catch(function (err) {\n\t\t\tlogger.error(err);\n\t\t});\n\t}\n```\n\n### Logging\nThis SDK uses the log4js package for logging. By default the logging level is set to `info`. To create your own logging configuration for your application, add a log4js.json file and set the `process.env.LOG4JS_CONFIG` environment variable to your json file.\n\nTo learn more about log4js, visit the documentation here (https://log4js-node.github.io/log4js-node/).\n\n## Got Questions?\nJoin us on [Slack](https://www.ibm.com/cloud/blog/announcements/get-help-with-ibm-cloud-app-id-related-questions-on-slack) and chat with our dev team.\n\n### License\nThis package contains code licensed under the Apache License, Version 2.0 (the \"License\"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 and may also view the License in the LICENSE file within this package.\n\n[img-ibmcloud-powered]: https://img.shields.io/badge/ibm%20cloud-powered-blue.svg\n[url-ibmcloud]: https://www.ibm.com/cloud/\n[url-npm]: https://www.npmjs.com/package/ibmcloud-appid\n[img-license]: https://img.shields.io/npm/l/ibmcloud-appid.svg\n[img-version]: https://img.shields.io/npm/v/ibmcloud-appid.svg\n[img-npm-downloads-monthly]: https://img.shields.io/npm/dm/ibmcloud-appid.svg\n[img-npm-downloads-total]: https://img.shields.io/npm/dt/ibmcloud-appid.svg\n\n[img-github-watchers]: https://img.shields.io/github/watchers/ibm-cloud-security/appid-serversdk-nodejs.svg?style=social\u0026label=Watch\n[url-github-watchers]: https://github.com/ibm-cloud-security/appid-serversdk-nodejs/watchers\n[img-github-stars]: https://img.shields.io/github/stars/ibm-cloud-security/appid-serversdk-nodejs.svg?style=social\u0026label=Star\n[url-github-stars]: https://github.com/ibm-cloud-security/appid-serversdk-nodejs/stargazers\n[img-github-forks]: https://img.shields.io/github/forks/ibm-cloud-security/appid-serversdk-nodejs.svg?style=social\u0026label=Fork\n[url-github-forks]: https://github.com/ibm-cloud-security/appid-serversdk-nodejs/network\n\n[img-coveralls-master]: https://coveralls.io/repos/github/ibm-cloud-security/appid-serversdk-nodejs/badge.svg\n[url-coveralls-master]: https://coveralls.io/github/ibm-cloud-security/appid-serversdk-nodejs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud-security%2Fappid-serversdk-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm-cloud-security%2Fappid-serversdk-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud-security%2Fappid-serversdk-nodejs/lists"}