BlockApps STRATO integrates with enterprise user authorization framework, e.g., OAuth2, to allow user access and achieve single sign-on for blockchain applications.
Why OAauth2 Is Needed
BlockApps STRATO includes configuration settings that allow it to integrate with the enterprise user authorization toolset of OAuth2. This enables developers integrate with external authorization/identity systems when they would like to create blockchain applications that restrict user access, use external identity validation, or integrate with other single sign-on processes. This feature was also added to support the practical problem of securing blockchain interactions because of the number of API calls that are required with most applications and blockchain use cases. Specifically, it becomes highly impractical to provide a blockchain account private key or password each time we want to interact with the decentralized applications where all the data is stored on the blockchain and every action or transaction requires an API call.
How Oauth works
This process generally works behind the scenes with OAuth client credentials that are loaded onto the server during STRATO setup, which validates the client's authorization and then provides an access token and a refresh token. Access tokens typically have a short lifespan (i.e. 1 hour) while refresh tokens can be valid for a longer period of time (Note that these timeframes may be configurable through your identity provider). The access token is then passed with any HTTP requests to the content provider (the blockchain, in our case) as part of the request. These are passed as a query argument, HTTP header, or POST form data.
To illustrate, let's take the example of a single sign on (SSO)solution. While the access token is valid, you can typically use any of the websites which use the SSO solution while the access token is valid. Once it expires in an hour - it's automatically refreshed for you with the refresh token. It happens seamlessly. However, once the refresh token is outdated as well - this means the SSO session is over for you permanently - then your SSO identity provider will ask you to re-login with your account again to access anything. In the context of dApps, when your refresh token has expired, you are no longer able to make any requests to the OAuth-protected APIs until you have corrected the issue with your tokens. This is worth mentioning because it can be a common oversight during dApp development when working with this feature.
For dApps built on the STRATO platform, the arrangement is a little more complex. You can follow this diagram below to understand how OAuth works in the application:
Your OAuth provider should be set up to generate two token cookies -- one for STRATO node as a client and one for the protected dApp as a second client. If you attempt to access an API with OAuth enabled and you do not have an existing authorization and token, the OAuth protected API will redirect you to the OAuth provider. Likewise, the code should be constructed so that you are redirected to the OAuth provider if you attempt to access an OAuth protected dApp without the tokens. After you have log into your OAuth provider the first time, it should have generated both sets of token cookies. When you return to try and access either the API or the dApp, you should now be able to make requests and transact with each of these components. Note that there are two sets of distinct token cookies. This can become important to understand in the event that you need to troubleshoot OAuth issues while developing your application.
How do I get the credential/auth token?
Create a user in OAuth provider
Get a token using the token-getter tool in blockapps-rest
First, clone the repository:
git clone https://github.com/blockapps/blockapps-rest cd blockapps-rest npm i
Next, create a
./config.yaml file with contents:
nodes: - id: 0 url: "http://<STRATO_NODE_HOST_WITH_PORT>" # optional oauth: appTokenCookieName: "my_strato_app_access_token" scope: "email openid" appTokenCookieMaxAge: 7776000000 # 90 days: 90 * 24 * 60 * 60 * 1000 clientId: "<CLIENT_ID_HERE>" clientSecret: "<CLIENT_SECRET_HERE>" openIdDiscoveryUrl: "https://<URL_PATH>/.well-known/openid-configuration" redirectUri: "http://localhost/api/v1/authentication/callback" logoutRedirectUri: "http://localhost"
Once configured, run token-getter to obtain user tokens (using the browser, one token per user):
sudo npm run token-getter --config ./config.yaml --flow authorization-code
Or get the service-user token (programmatically, only one token per oauth client (app)):
sudo npm run token-getter --config ./config.yaml --flow client-credential
See npm run token-getter --help for more info.
How to Develop an Application Using OAuth2 (coming soon)
Note: If you already have an OAuth enabled node, you can dig in and start building an OAuth enhanced application. If you do not have an OAuth enabled node, go to [OAuth User Management] under [Installing A New Node / Network]: to learn how to enable OAuth on your node and then return to this section.
We are currently finalizing some tools that will be useful to assist in incorproating the OAuth functionality into dApps developed for STRATO. We will update this section within the next few sprints, once the related toolsets are complete.