Documaster Noark5 API is secured using OAuth2/OIC and more specifically the Resource Owner Passoword Grant. This is a standard flow part of the OAuth2 specification here https://datatracker.ietf.org/doc/html/rfc6749#section-4.3. This particular flow is used only in server-to-server integrations.
Each integrating party should make sure the provided credentials as part of the onboarding process and kept secure on the integrating system server side. The credentials should never be embedded in any Web or mobile applications.
OAuth2 scopes are not currently used to restrict access to the API, a single scope openid
should be provided indicating that OIC capabilities should be enabled on the IDP side.
Documaster Archive has an internal security mechanism based on access groups. Access groups provide Read/Write/Update control over Noark5 entity model. As part of the project that the integration is implemented, specific permissions will be assigned to the integration access group and from there to the integration user.
Documaster provides IDP Client SDKs for both Java and .NET. Their code and samples can be found here:
Retrieving an access token and a related refresh token, a call to the IDP endpoint /oauth2/token
should be made with the provided credentials part of the onboarding.
Field | Location | Value |
---|---|---|
Authorization |
Base64 encoded client_id:client_secret | |
Content-Type |
fixed value of application/x-www-form-urlencoded | |
grant_type |
fixed value of password | |
username |
username provided during onboarding process | |
password |
password provided during onboarding process | |
scope |
fixed value of openid |
Request
POST https://v2-34-0.local.documaster.tech/idp/oauth2/token HTTP/1.1
...
Authorization: Basic {client_id:client_secret}
Content-Type: application/x-www-form-urlencoded
grant_type=password
&username={username}
&password={password}
&scope=openid
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "f295ace60f0a92808c496249a572a5784aa6af6f",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid",
"refresh_token": "0a4a4f8633a8c9a289fca751e181eeaea5cd2455"
}
Initialize Documaster RMS Client
// Acquire access token from Documaster IDP
// Parameter to the HttpClientIDP constructor is the endpoint to the IDP without the final /token element
// client_id, client_secret, username and password are the provided credentials to access the API.
// The scope parameter is always set to openid
ClientIDP idpClient = new HttpClientIDP("https://v2-34-0.local.documaster.tech/idp/oauth2");
AccessTokenResponse atr = idpClient.getTokenWithPasswordCredentials(
client_id, client_secret,
username, password,
scope);
// Collect tokens from the response
String accessToken = atr.getAccessToken();
String refreshToken = atr.getRefreshToken();
// Instantiate RMS Client
// RmsClient is created by passing the URL of the Documaster APIs hostname and port, without any parts of the path
NoarkClient client = new NoarkClient(new RmsClient("https://v2-34-0.local.documaster.tech:8083"));
client.setAuthToken(accessToken);
Initialize Documaster RMS Client
// Acquire access token from Documaster IDP
// Parameters to the PasswordGrantTypeParams constructor are the
// client_id, client_secret, username and password as provided by Documaster to access the API.
// The scope parameter is always set to OpenIDConnectScope.OPENID
// Initializing clients
Oauth2HttpClient idpClient = new Oauth2HttpClient("https://v2-34-0.local.documaster.tech/idp/oauth2", true);
NoarkClient client = new NoarkClient("https://v2-34-0.local.documaster.tech:8083", true);
// Acquiring access token
PasswordGrantTypeParams passwordGrantTypeParams = new PasswordGrantTypeParams(
ClientId,
ClientSecret,
Username,
Password,
OpenIDConnectScope.OPENID);
AccessTokenResponse atr =
idpClient.GetTokenWithPasswordGrantType(passwordGrantTypeParams);
string accessToken = atr.AccessToken;
string refreshToken = atr.RefreshToken;
client.AuthToken = accessToken;
Access tokens are supplied with each and every call to the Documaster Noark5 API in the Authorization
HTTP header, in the format Bearer {{accessTokenIntegrator}}
. Calls to the API without the header or with an invalid format or access token result in HTTP 401 Unauthorized
code to be returned back.
Access tokens ($.accessToken
in HTTP response) generated by Documaster IDP are with default lifetime of 3600 seconds, which is 1 hour. Refresh tokens are valid for 14 days.
The access tokens should be cached and reused across calls, for the period of their validity (1 hour). Refreshing the access token can be done in one of two ways - either acquire a new access token, or use the refresh token ($.refreshToken
) to acquire a new access token.
Recommended approach is to use the refresh token as shown in the samples below. The result of refreshing the access token using the refresh token is another set of both tokens. Refresh token should also be cached if that would be the chosen uproach for acquiring new access tokens.
Access token should be renewed in one of two scenarios - when an API call return HTTP 401 Unauthorized or on a regular basis. Recommended is the first scenario, since there is always a chance that access tokens may get invalidated on IDP side earlier than they are to expire.
Field | Location | Value |
---|---|---|
Authorization |
Base64 encoded client_id:client_secret | |
Content-Type |
fixed value of application/x-www-form-urlencoded | |
grant_type |
fixed value of refresh_token | |
refresh_token |
refresh token received as a response of the Resource Owner Password Grant call above, from element $.refresh_token |
Request
POST https://v2-34-0.local.documaster.tech/idp/oauth2/token
Authorization: Basic {client_id:client_secret}
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=0a4a4f8633a8c9a289fca751e181eeaea5cd2455
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "504e347005b2df9a8769b884c2bbfcb6fe4ab387",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid",
"refresh_token": "6562ff52129474fe9029518b28bbb1a20f8c9ecc"
}
Refresh Access Token
// Acquire new access token using the refresh token
AccessTokenResponse atrRefresh = idpClient.refreshToken(client_id, client_secret, refreshToken);
// Set access token to be used by the NoarkClient instance
client.setAuthToken(atrRefresh.getAccessToken());
Query by CaseYear and CaseSequenceNumber
// Acquire new access token using the refresh token
AccessTokenResponse rtr = idpClient.RefreshToken(
new RefreshTokenGrantTypeParams(
refreshToken,
ClientId,
ClientSecret));
// Set access token to be used by the NoarkClient instance
client.AuthToken = rtr.AccessToken;
Before proceeding with making first calls to the API, short introduction to Documaster API model and operations needs to be covered.
Model and Operatons Overview