Authentication and Authorization

Authentication

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.

Authorization

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.

IDP Client SDKs

Documaster provides IDP Client SDKs for both Java and .NET. Their code and samples can be found here:

Acquire an Access Token

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.

HTTP parameters mapping
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;

Using the Access Token

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 Token Management

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.

HTTP parameters mapping
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