Authentication and Authorization

Authentication

Documaster Noark5 API is secured using OAuth2/OIC and more specifically the OAuth2 Client Credentials. This is a standard flow part of the OAuth2 specification here https://datatracker.ietf.org/doc/html/rfc6749#section-4.4. This particular flow is used only in server-to-server integrations.

OAuth2 scope openid should be provided indicating that OIC capabilities should be enabled on the IDP side when using Documaster IDP.

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:

• Java IDP Client SDK
• .NET IDP Client SDK

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

POST https://<documaster-instance>.local.documaster.tech/idp/oauth2/token HTTP/1.1
...
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{client_id}}
&client_secret={{client_secret}}
&scope={{scope}}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "f295ace60f0a92808c496249a572a5784aa6af6f",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": "openid"
}

    // 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, scope are the provided credentials to access the API.

    ClientIDP idpClient = new HttpClientIDP("https://<documaster-instance>.local.documaster.tech/idp/oauth2");
    AccessTokenResponse atr = idpClient.getTokenWithClientCredentials(
            client_id, client_secret,
            scope);

    // Collect tokens from the response
    String accessToken = atr.getAccessToken();

    // 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://<documaster-instance>.local.documaster.tech:8083"));
    client.setAuthToken(accessToken);

    // Acquire access token from Documaster IDP
    // Parameters to the ClientCredentialsGrantTypeParams constructor are the
    // client_id, client_secret and scope as provided by Documaster to access the API.
    
    // Initializing clients
    Oauth2HttpClient idpClient = new Oauth2HttpClient("https://<documaster-instance>.local.documaster.tech/idp/oauth2", true);
    NoarkClient client = new NoarkClient("https://<documaster-instance>.local.documaster.tech:8083", true);

    // Acquiring access token
    ClientCredentialsGrantTypeParams clientCredentialsGrantTypeParams = new ClientCredentialsGrantTypeParams(
        ClientId, 
        ClientSecret, 
        Scope);

    AccessTokenResponse atr = idpClient.GetTokenWithClientCredentialsGrantType(clientCredentialsGrantTypeParams);

    string accessToken = atr.AccessToken;
    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.

The access tokens should be cached and reused across calls, for the period of their validity (1 hour). Access tokens cannot be refreshed, new access token needs to be acquired making the exact same call.

Before proceeding with making first calls to the API, short introduction to Documaster API model and operations needs to be covered.