2023.1

Registration and authentiaction

Application registration

In WEBCON BPS you can create and manage all of your applications from the admin panel, which is available at https://[WEBCON Portal address]/adminpanel, e.g. https://dev20.webcon.pl/WEBCONBPS/adminpanel. This panel can only be used by global administrators.

Before we create a new application, there were some changes introduced in version 2022. First of all, now there are two types of applications to choose from, App context and User context.

App context is the equivalent of applications existing in older versions. It should be used for service-to-service communication and it uses client credentials flow to authenticate. This type also creates user account in WEBCON BPS, so you can assign permissions, tasks, etc. to it.

The second type, User Context, will be used when we want to act in the context of an existing user and use his permissions. This one uses autorization code flow, so we will need user interaction to get an auth token.

How to create a new application?

  1. Open [WEBCON Portal address]/adminpanel in your browser and enter login details (if necessary).
  2. Choose New API application.
  3. Now you have to choose application type, App or User context.
  4. Enter the application name, login (in UPN format) and e-mail address (only App context). Your login should be unique and UPNs used in the system are not allowed.
    1. User context also allows you to configure Authorized redirect URIs and Authorization flows configuration, but they may remain empty for now, we will discuss them later.
  5. Choose Save

The following screenshot shows an example web application registration:

AppRegister

Client ID and secret

Application uses both Client ID and Secret to authenticate. ID is generated during application registration while secret can be generated in next screen (after application save). Every application has exactly one Client ID (that cannot be changed) and can have multiple Secrets used in different systems. New secrets can be created by using the ‘Generate new client secret’ button. In the next pop-up we can add key description, which can be used for easier Secrets identification and management. It is important to save newly generated secret, because it will not be shown again and cannot be restored. Keep client ID and key secret as they can be used to access Webcon BPS data and perform actions such as read, edit or delete workflows. You should keep Client Secret as secure as a password, and regularly review the secrets you have created to remove any you no longer need.

Following screenshot shows example of generating a secret:

ClientSecret-1024x565

User context configuration

  • Authorized redirect URIs - after a user successfully authorizes an application, the BPS authorization server will redirect the user back to the application only if the requested return URL is configured. Because the redirect URL will contain sensitive information, it is important that the service does not redirect the user to arbitrary locations.

  • Authorization flows configuration

    • Allow offline access (issue Refresh Tokens) - allows application to ask for refresh token, to do so, app has to request an offline_access scope
    • Show consent screen for new scopes - each time the application will ask the user for a new scope, a screen will be displayed on which he will have to agree to this scope. The user may withdraw consent at any time for a given application in the security section of their user profile in the Portal interface.

UserAppOptions

Scopes

Each application has a defined set of scopes that it can request when generating an access token. Allowed scopes will be used to limit access throught use of a token.

More on the topic can be found in this article

Impersonation

Impersonation is still available, but only for applications created before version 2022 and that had the Allow impersonation option enabled.

It allows application to use other user permissions via an impersonation, but to do so, first you need to allow API application to impersonate and select the list of applications within which it will be able to do so. This also can be done in edit page in the admin panel.

Authentication

To call WEBCON REST API, your application must acquire an access token, which contains information about your application and the permissions it has. To get an access token, your application has to be registered in WEBCON admin panel. Access tokens are JSON Web Tokens (JWT). They contain claims that web API uses to validate the caller and to ensure that the caller has the proper permissions to perform the operation they’re requesting. To call WEBCON API, you attach the access token as a Bearer token to the authorization header in an HTTP request.

Get access token

To get an access token, your application has to exchange ‘http’ requests with login endpoint. Currently we have several methods of authentication:

OAuth 2.0 client credentials

Available on endpoint POST /api/oauth2/token. Uses standard oauth client_credentials type authentication flow. Below is request in curl for our example application:

curl -X POST "http://dev20/WEBCONBPS/api/oauth2/token" 
-H "accept: text/plain” 
-H "Content-Type: application/x-www-form-urlencoded" 
-d "grant_type=client_credentials&client_id=2be2fd55-5662-4507-b255-1558a7ab9786&client_secret=2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc%2F800xub4%3D&
scope=Admin.Read.All"

OAuth 2.0 authorization code

This one will be used to authorize User context applications via the browser. The endpoint for authorization server that will be used to get authorization code: /connect/authorize and the endpoint for authentication server which will be used to exchange the authorization code for an access token: /api/oauth2/token.

Here is example authorization request:

GET /connect/authorize?
response_type=code&
client_id=5be9806d-6c17-494c-a66f-f4845f9caba8&
redirect_uri=https%3A%2F%2Fmyexampleapp.com%2FOAuthFlows%2FReceiveTokens&
scope=profile&
state=VHVlIEphbiAxMSAyMDIyIDA5OjQ3OjA4IEdNVCswMTAwIChjemFzIMWbcm9ka293b2V1cm9wZWpza2kgc3RhbmRhcmRvd3kp

Below is example request to exchange code:

curl -X POST "http://dev20/WEBCONBPS/api/oauth2/token" 
-H "accept: text/plain” 
-H "Content-Type: application/x-www-form-urlencoded" 
-d "grant_type=authorization_code&
client_id=2be2fd55-5662-4507-b255-1558a7ab9786&
client_secret=2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc%2F800xub4%3D&
code=877290efe8054c85185374e4bda08fd7b46a8fd8b1afbd32b3c2a3024d9d9f89&
redirect_uri=https://myexampleapp.com/OAuthFlows/ReceiveTokens"

OAuth 2.0 implicit grant

This is another type of browser authentication. It is a way for a single-page JavaScript app to get an access token without an intermediate code exchange step. The endpoint for authorization server that will be used to get authorization code is the same: /connect/authorize and the token will be returned directly in the url fragment (after the #).

Here is example authorization request:

GET /connect/authorize
?response_type=token
&state=
&client_id=408ffe58-c066-4c8f-b2c2-731886082f80
&scope=User.Data
&redirect_uri=https%3A%2F%2Fmyexampleapp.com%2FOAuthFlows%2FReceiveTokens

And here is example response (token was truncated for readability):

https://myexampleapp.com/OAuthFlows/ReceiveTokens
#access_token=eyJhbGciO(..)LqYcYg
&token_type=Bearer
&expires_in=3600
&scope=User.Data

Webcon authentication

Available on endpoint POST /api/login. Here credentials are passed as json in request body. Below is example request without impersonation:

curl -X POST "http://dev20/WEBCONBPS/api/login" 
-H "accept: text/plain" 
-H "Content-Type: application/json " 
-d "{\"clientId\":\"2be2fd55-5662-4507-b255-1558a7ab9786\",\"clientSecret\":\"2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc/800xub4=\",
\"scope\": \"Admin.Read.All\"}"

Each endpoint returns a response with token in same format (the access token has been truncated for readability):

{ 
"token": "eyJhbGciOiJIUzI1NiIsI … cD7FSf35S3--z1U7E-qrDMNu0OKi51DY32LA7s8qMlQ" 
}

To call WEBCON API, you attach the access token as Bearer token to the Authorization header in HTTP request. Here’s an example call that returns instance data with id 1:

HTTP/1.1 Host: dev20.webcon.pl 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsI … cD7FSf35S3--z1U7E-qrDMNu0OKi51DY32LA7s 
GET http://dev20.webcon.pl/WEBCONBPS/api/data/v5.0/db/1/elements/1
← Rest APIScopes and permissions →