Skip to content

oAuth Authentication

Other applications can use BizzStream to authenticate users. To facilitate this, BizzStream supports authentication flow for the oAuth 2 authorization_code grant type. Click here for an in-depth explanation of this authentication flow.

As BizzStream has a very fine-grained permission system, the scopes functionality of the flow is not supported. Instead, it is possible to authenticate a user against a specific document.

Application Registration

Before another application can use BizzStream to authenticate users, you have to register the application in your environment. You can do so by

  1. Go to Setup
  2. Open the Environment selection
  3. Click on oAuth Configuration
  4. Click on New to add a new application and enter the application name, ID, and redirect URL. The redirect URL should start with http:// or https://. BizzStream redirects user to this URL after they have been authorized.
  5. Click on Save.

Authentication Flow

The authentication flow consists of four steps, which are depicted in the diagram below.

The authentication flow consists of four steps.

1. Application Requests Authentication

The application redirects to user to the following URL:

https://app.bizzstream.com/ENVIRONMENT_ID/auth/DD_ID/DOC_ID?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE

using the following parameters

  • ENVIRONMENT_ID is the ID of the environment in which the application has been registered.
  • DD_ID is the ID of the document definition of the document against which the user should be authenticated.
  • DOC_ID is the ID of the document against which the user should be authenticated.
  • CLIENT_ID is the ID of the client in the environment in which is has been registered.
  • REDIRECT_URI is the URL where the user will be redirected after successful authentication.
  • STATE is an optional parameter and can be used to pass additional information back to the application.

An example of such a request is

https://app.bizzstream.com/T6LoMS6d27yiAzh4P/auth/McFNDangdH2fERNKd/3K7eivvqrsAT9gLwg?response_type=code&client_id=TestAPP&redirect_uri=http://testapp.com/callback

2. Application Receives Authentication code

If the user does not have an active BizzStream session, BizzStream will show a login dialog. If the user has read access to the document, BizzStream redirects the user to the REDIRECT_URI. BizzStream will add the 

redirectUri?code=CODE&state=STATE

where state will be have the value of the STATE parameter in the authentication request described in step 1.

3. Application Requests Access Token

Next, the application requests BizzStream the access token. It does so by making HTTP POST request

https://app.bizzstream.com/auth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL

using the following parameters

  • CLIENT_ID is the ID of the client in the environment in which is has been registered.
  • CLIENT_SECRET is the client secret that was generated when the application was registered.
  • AUTHORIZATION_CODE is the authorization code BizzStream provided in step 2.
  • REDIRECT_URI is the URL where the user will be redirected after successful authentication.

An example of such a request is

https://app.bizzstream.com/auth/token?client_id=TestAPP&client_secret=mXNcsLYi46NwWyHWp&grant_type=authorization_code&code=12345&redirect_uri=http://testapp.com/callback

Moreover, you need to send the following parameters through the body of the request in a JSON format:

{
"grant_type":"authorization_code",
"code":"generated_code",
"redirect_uri":"http://your_redirect_uri",
"client_id":"registered_client_id",
"client_secret":"generated_client_secret"
}

4. Application Receives Access Token

If the request is correct, BizzStream responds with status code 200 and the following body:

{
    "access_token": "MMsRwNgFYGNouMBGi",
    "token_type": "Bearer",
    "userId": "yN5Lvfc8tePhyrEop",
    "username": "testuser@company.com",
    "environmentEmail": "testuser@company.com"
}

where the field access_token contains the access token that can be used for further requests to BizzStream.