Connect to DocuWare with an App Registration

This example is going to show how to obtain an Access Token using values from an App Registration plugin configuration to authenticate with DocuWare platform.

Note

For this example, an App Registration configuration is required. This needs to be created in the Configuration page in DocuWare.

Once the configuration is created, you will need some values from the configuration to create the Access Token to connect to DocuWare.

• ClientId (GUID): This is the "Application (Client) ID" in the in the "General" section of the App Registration Configuration
• ClientSecret (String - Optional): This is the "Client secret" in the App Registration Configuration. This setting is only in an App Registration of type "Web application". It is omitted for "Native" and "Single-page" applications.
• Scope (String): This is the "Scope" in the "Access" section of the App Registration Configuration.
• RedirectUri (String): This is the "Redirect URL" in the "General" section of the App Registration Configuration.

Other DocuWare specific values will need to be used from the DocuWare environment that the App Registration is created in.

• OrganizationGuid (GUID): This is the Organization Id GUID.
• PlatformUrl (String): This is the Platform URL for DocuWare. The format of this URL should be "https://[Cloud Name].docuware.cloud/DocuWare/Platform"

Note

The sample code below uses these NuGet packages.

• DocuWare.Platform.ServerClient.Extensions
• IdentityModel (OpenID Connect & OAuth 2.0 client library)
• IdentityModel.OidcClient (RFC8252 compliant and certified OpenID Connect and OAuth 2.0 client library for native applications)

Once the Access Token is generated, the code below will use DocuWare.Platform.ServerClient.ServiceConnection.CreateWithJwtAsync to create the DocuWare Service Connection. More information on that can be found here.

C#

 static class Program
{
    private const string ClientId = ""; //Application Client ID from the App Registration configuration 
    private const string ClientSecret = ""; //Client secret from the App Registration configuration
    private const string Scope = "docuware.platform dwprofile openid offline_access"; //Access Scope for the token from the App Registration configuration
    private const string RedirectUri = ""; //Redirect URI from the App Registration configuration
    private const string PlatformUrl = ""; //DocuWare Platform URL
    private const string OrganizationGuid = ""; //DocuWare Organization ID

    static async Task Main(string[] args)
    {
        try
        {
            var response = await AuthorizationCodeFlow().ConfigureAwait(false);
            await Console.Out.WriteLineAsync(response.RefreshToken);

            var connect = await DocuWare.Platform.ServerClient.ServiceConnection.CreateWithJwtAsync(new Uri(PlatformUrl),
                response.AccessToken,
                DWProductTypes.PlatformService);

            var myOrg = connect.Organizations[0];
            var fileCabinets = myOrg.GetFileCabinetsFromFilecabinetsRelation().FileCabinet;
            connect.Disconnect();
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }

    private static async Task<RetrieveTokenResponse> AuthorizationCodeFlow()
    {
        var idsInfo = ServiceConnection.GetIdentityServiceInfoAsync(new Uri(PlatformUrl), new IdentityServiceInfoConnectionData()).ConfigureAwait(false).GetAwaiter().GetResult();
        var oidcClient = new OidcClient(new OidcClientOptions()
        {
            Authority = idsInfo.IdentityServiceUrl,
            ClientId = ClientId,
            ClientSecret = ClientSecret,
            Scope = Scope,
            RedirectUri = RedirectUri,
            FilterClaims = true,
            LoadProfile = false,
            Policy = new Policy { Discovery = new DiscoveryPolicy { RequireHttps = false } },
        });

        var response = await RetrieveAccessTokenAsync(oidcClient).ConfigureAwait(false);
        return response;
    }

    private static async Task<RetrieveTokenResponse> RetrieveAccessTokenAsync(OidcClient client)
    {
        var state = await client.PrepareLoginAsync().ConfigureAwait(false);

        using var http = new HttpListener();
        http.Prefixes.Add(state.RedirectUri);
        http.Start();

        var browserProcess = Process.Start(new ProcessStartInfo("cmd", $"/c start {state.StartUrl.Replace("&", "^&")}") { CreateNoWindow = true });

        var context = await http.GetContextAsync().ConfigureAwait(false);
        var requestQueryString = context.Request.QueryString;

        await SendSuccessMessageResponseAsync(context.Response, client.Options.Authority).ConfigureAwait(false);
        browserProcess?.Close();

        var query = HttpUtility.ParseQueryString(string.Empty);
        query[QueryStringConstants.Code] = requestQueryString[QueryStringConstants.Code];
        query[QueryStringConstants.Scope] = requestQueryString[QueryStringConstants.Scope];
        query[QueryStringConstants.State] = requestQueryString[QueryStringConstants.State];
        query[QueryStringConstants.SessionState] = requestQueryString[QueryStringConstants.SessionState];

        var result = await client.ProcessResponseAsync(
            query.ToString(),
            state,
            new Parameters
            {
                { $"acr_values", $"tenant:{OrganizationGuid}" }
            }).ConfigureAwait(false);

        return new RetrieveTokenResponse(result.AccessToken, result.RefreshToken, result.IsError ? result.Error : string.Empty);
    }

    private static async Task SendSuccessMessageResponseAsync(HttpListenerResponse response, string serviceUrl)
    {
        var url = serviceUrl.EndsWith("/") ? serviceUrl : serviceUrl + "/";
        var responseString = "<html><head><meta http-equiv='Refresh' content='0; url = " + url + "Account/LoginSuccess' /></head><body></body></html>";
        var buffer = Encoding.UTF8.GetBytes(responseString);
        response.ContentLength64 = buffer.Length;

        var responseOutput = response.OutputStream;
        await responseOutput.WriteAsync(buffer, 0, buffer.Length).ConfigureAwait(false);
        responseOutput.Close();
    }
}

public static class QueryStringConstants
{
    public const string Code = "code";
    public const string SessionState = "session_state";
    public const string State = "state";
    public const string Scope = "scope";
}

public class RetrieveTokenResponse
{
    public RetrieveTokenResponse(string accessToken, string refreshToken, string error)
    {
        AccessToken = accessToken;
        RefreshToken = refreshToken;
        Error = error;
    }

    public string AccessToken { get; }
    public string RefreshToken { get; }
    public string Error { get; }
}